@damiangilgonzalez/harness 1.3.7

package/skills/muscle-memory/evals/cases.yaml

@@ -0,0 +1,32 @@
+skill: muscle-memory
+
+should_trigger:
+  - prompt: "Ponme ejercicios de Python basados en mi codigo reciente."
+    why: "Disparador directo de muscle-memory."
+  - prompt: "Quiero practicar para mantener el codigo afilado."
+    why: "Disparador directo de muscle-memory."
+  - prompt: "Revisa mi solucion a este kata."
+    why: "Disparador directo de muscle-memory."
+  - prompt: "Generate a short Python kata from my recent code."
+    why: "Disparador directo de muscle-memory."
+  - prompt: "Como voy con mi progreso de practica."
+    why: "Disparador directo de muscle-memory."
+
+should_not_trigger:
+  - prompt: "Implementa esta funcion de produccion directamente."
+    route_to: "implement"
+    why: "Implementar el codigo es el trabajo de implement, no de muscle-memory."
+  - prompt: "Ensename un concepto nuevo a lo largo de varias sesiones."
+    route_to: "teach"
+    why: "Ensenar un concepto a lo largo de varias sesiones es el trabajo de teach, no de muscle-memory."
+  - prompt: "Revisa el codigo de este PR."
+    route_to: "code-review"
+    why: "Revisar el codigo de un PR es el trabajo de code-review, no de muscle-memory."
+  - prompt: "Documenta el modelo de dominio."
+    route_to: "domain-modeling"
+    why: "Documentar el modelo de dominio es el trabajo de domain-modeling, no de muscle-memory."
+
+capability:
+  - scenario: "El usuario quiere practicar Python con katas generados a partir de su codigo."
+    must_include:
+      - "kata"

package/skills/muscle-memory/references/kata-authoring.md

@@ -0,0 +1,212 @@
+# Kata authoring guide
+
+How to write a new kata skeleton for `library/<concept>/katas/l<level>-<slug>.json`,
+and how to adapt an existing skeleton into a session kata. Read this whenever
+Generate needs to create a card that doesn't exist yet, or whenever you want to
+extend the library with a new concept.
+
+A skeleton is a JSON object with exactly these fields:
+
+```json
+{
+  "concept": "context-managers",
+  "level": 2,
+  "title_en": "Build ManagedConnection with __enter__/__exit__",
+  "spec_html_en": "<p>...</p>",
+  "stub": "...",
+  "test": "...",
+  "canonical": "..."
+}
+```
+
+`concept` must be one of the canonical slugs in `scripts/scan_repo.py`'s
+`CONCEPT_SLUGS`, and must match the folder it lives in
+(`scripts/validate_library.py` enforces both). `level` is `1`-`4`. Everything
+must be valid Python (`stub`, `test`, `canonical` are each parsed and, for
+`canonical` + `test`, actually executed — run `validate_library.py` after
+writing a new card and fix anything it reports as `FAIL`).
+
+> **Gotcha — the validator is not the browser.** `validate_library.py` runs
+> katas on local CPython, but the user solves them in Pyodide (browser wasm),
+> where an asyncio event loop is *already running*. A kata can pass the
+> validator and still fail in the app. The known case: `asyncio.run(...)`
+> inside a test raises `RuntimeError: cannot be called from a running event
+> loop` in Pyodide (see the async rule under "How to write tests" — use
+> `async def test_*` + `await`). Whenever a new concept could behave
+> differently under a running event loop or in wasm, verify it in the actual
+> app, not just the validator.
+
+## The concept card (`library/<concept>/card.md`)
+
+Every concept folder also has a `card.md`: the study material the user reads,
+and the context Generate leans on. When you add a new concept, write its card
+with exactly these four sections, in this order (match the 20 existing cards),
+in English:
+
+```markdown
+# <Concept name>
+
+## What it is
+One short paragraph: what the concept is and when you reach for it.
+
+## Idiomatic example
+​```python
+# a few lines of the canonical, idiomatic form
+​```
+
+## Common mistakes
+- 2-4 bullets naming the real pitfalls (mutable default args, forgetting
+  `self`, comparing without an `isinstance` guard, ...).
+
+## Where you see it in real code
+- 1-3 bullets tying it to real-world usage (ORM models, service classes,
+  context-managed connections, ...).
+```
+
+Keep it tight — it is a study cheat-sheet, not a tutorial.
+
+## Signal -> concept slug mapping
+
+This is what `scan_repo.py` detects in the user's code and how it maps to a
+library folder name. Use it to pick the right concept when a scan surfaces
+several signals in the same file:
+
+| Signal in the user's code | Slug |
+|---|---|
+| Any class definition | `classes` |
+| `@staticmethod` / `@classmethod` (no `property`) | `methods` |
+| `@property` | `properties` |
+| `@dataclass` decorator or `from dataclasses import ...` | `dataclasses` |
+| Non-`__init__`/`__enter__`/`__exit__`/`__iter__`/`__next__` dunder method | `dunder-methods` |
+| Class with base classes, or `from abc import ...` | `inheritance` |
+| `class X(Enum)` or `from enum import ...` | `enums` |
+| `try`/`except` block | `exceptions` |
+| `Optional`/`Union`/`Protocol`/`TypedDict` from `typing` | `typing` |
+| `__enter__` method, or `from contextlib import ...` | `context-managers` |
+| Any other decorator (not `dataclass`/`property`/`static`/`classmethod`) | `decorators` |
+| `yield` / `yield from` in a function | `generators` |
+| List/set/dict comprehension or generator expression | `comprehensions` |
+| `__iter__`/`__next__` methods | `iterators` |
+| `async def`, `await`, or `import asyncio` | `async` |
+| A class/function that builds and returns other objects by type/config | `factory` |
+| An object holding a swappable callable/behavior | `strategy` |
+| A publish/subscribe or notify-list pattern | `observer` |
+| A class wrapping one interface to expose another | `adapter` |
+| A class restricting itself to one instance (module-level cache, `__new__` guard) | `singleton` |
+
+If a scanned file shows a signal not in this table, fall back to the closest
+fundamental (usually `classes` or `exceptions`) rather than inventing a new
+slug — `CONCEPT_SLUGS` is a closed set on purpose.
+
+## Brevity rules (non-negotiable)
+
+- **<=25 lines to write.** Count only the code the user actually has to
+  produce (the stub's `TODO` region), not the surrounding class/test scaffolding.
+- **One concept per kata.** Don't smuggle a second concept in "for realism" —
+  a context-manager kata should not also require a decorator.
+- **Spec is 1-3 sentences.** State the class/function name, its
+  signature, and the exact behavior expected. No prose, no motivation
+  paragraph. Use `<code>` for identifiers.
+- **Stdlib or Pyodide-safe only.** No `pip`/`micropip` packages. The kata
+  runs both via local `python` (Review) and via Pyodide in the browser
+  (the app) — anything not in the standard library breaks one of the two.
+- **Stub comes with the signature already in place.** The user fills in a
+  body, not a blank page: parameter names, `self`, return type intent (via the
+  spec) should already be visible in the stub. A bare `pass` with no signature
+  is a bad stub.
+
+## How to write tests
+
+- Test functions are named `test_*` — this is how both the local runner and
+  the app's Pyodide runner discover them (`ns` gets `exec`'d, then every
+  callable starting with `test_` is invoked).
+- Every `assert` carries a **didactic message** as its second argument: it
+  should explain the rule being checked, not just restate the assertion
+  (`"__exit__ must run even if the with-block raises"`, not `"failed"`).
+- Cover **3 cases**: the normal/happy path, one edge case (empty input,
+  boundary value, "equal to the limit" rather than strictly over/under), and
+  one case that exercises error handling if the concept involves it
+  (exception raised/propagated, invalid state).
+- **Do not depend on dict ordering, wall-clock time, or `repr()`/`str()`
+  output** unless the kata is specifically about `__repr__`/`__str__`. Compare
+  values, not incidental representations.
+- **Tests must be self-contained and order-independent.** Each `test_*`
+  function builds its own fixtures (fresh instances, fresh lists) — never
+  rely on a previous test having run first or on module-level mutable state
+  a test mutates and another reads.
+- **Async katas: write `async def test_*` and `await` the coroutine — never
+  `asyncio.run(...)`.** In the browser (Pyodide) an event loop is already
+  running, so `asyncio.run()` raises `RuntimeError: asyncio.run() cannot be
+  called from a running event loop`, even though it works under local
+  `python`. Both runners detect a coroutine-returning test and await it, so an
+  `async def test_x(): result = await my_coro(...)` works in both. A sync
+  helper test (e.g. `inspect.iscoroutinefunction(...)`) stays a plain `def`.
+- Prefer 2-3 test functions per kata (see the examples below); more than 4
+  usually means the kata covers more than one concept.
+
+## One example per level
+
+**Level 1 — recall** (`classes/katas/l1-init.json`): fill in a constructor
+whose fields are already used elsewhere in the stub (`deposit` reads
+`self.balance`). Tests check each stored field plus one line of behavior that
+depends on it.
+
+**Level 2 — reconstruction** (`context-managers/katas/l2-managed-connection.json`):
+implement a small protocol (`__init__`/`__enter__`/`__exit__`) from a spec
+that states each method's exact side effect. Tests check the happy path, the
+exact order of side effects, and that cleanup still runs when the block
+raises.
+
+**Level 3 — application** (`strategy/katas/l3-router-swap.json`): build a
+class that composes a behavior at runtime (`Router` holding a swappable
+`strategy` callable) and exercises it through 2-3 collaborators. Tests check
+the initial behavior, that swapping actually changes behavior, and that
+swapping back works (state isn't hidden anywhere else).
+
+**Level 4 — refactor** (`comprehensions/katas/l4-heavy-pallets.json`): a
+working implementation is given (a manual loop) and the task is to rewrite it
+idiomatically (as a comprehension) without changing behavior. The spec says
+explicitly "it already works, rewrite the body as...". Tests are behavioral
+only (they don't inspect the source) so both the loop and the comprehension
+would pass — the human value is in reading the rewritten `canonical`.
+
+## Mistakes to avoid
+
+- Writing a spec that describes *why* something matters instead of *what* to
+  implement — cut it to the signature and the behavior.
+- A stub that gives away the solution (e.g. already showing the one line
+  that matters) or one so bare it doesn't compile the surrounding scaffolding.
+- Tests with generic messages (`"wrong result"`) instead of naming the rule.
+- Mixing two concepts in one kata "to save a slot" — write two katas instead.
+- A `canonical` that doesn't actually satisfy its own `test` — this is
+  exactly what `validate_library.py` catches; never skip running it after
+  writing or editing a skeleton.
+- Depending on insertion order of a `dict`/`set` literal across Python
+  versions, or on `datetime.now()`/`time.time()` inside a test.
+- Forgetting the `concept` field must equal the folder name
+  (`library/<slug>/katas/...json` -> `"concept": "<slug>"`), or picking a
+  `level` outside `1`-`4` — `validate_library.py` rejects both.
+
+## How to adapt a skeleton for a session
+
+When Generate reuses an existing `library/<slug>/katas/l<level>-*.json` for a
+session kata, adapt only two things:
+
+1. **Translate the statement** (`spec_html_en` -> `spec_html`) and the title
+   (`title_en` -> `title`) into the language the user is conversing in. Keep it
+   literal unless recontextualizing (below) requires renaming something inside
+   it.
+2. **Recontextualize names to the user's domain** when it adds clarity — e.g.
+   rename `Router`/`plan`/`distance` to something from the scanned repo's
+   domain if a natural fit exists (a maintenance-incident router, a
+   discount-strategy for tariffs...). If nothing fits naturally, keep the
+   original names translated as-is; a forced rename is worse than a neutral
+   one.
+
+**Do not touch the test's structure** beyond consistent renames. If you
+rename `Router` to `IncidentRouter` in the `spec_html`/`stub`, rename it
+identically in `test` and `canonical` too — the same identifier, everywhere,
+in all three fields. Do not add, remove, or reorder assertions, do not change
+what's being tested, and do not introduce a second concept while adapting.
+The three cases (happy path, edge case, error case) and their didactic
+messages carry over unchanged except for the renamed identifiers.

package/skills/muscle-memory/scripts/build_session.py

@@ -0,0 +1,117 @@
+#!/usr/bin/env python3
+"""Vuelca una sesion adaptada al directorio de datos del usuario.
+
+Entrada: JSON de sesion (katas ya adaptadas, con campo canonical).
+Salidas: sessions/<id>.js (sin canonical), manifest.js regenerado,
+canonicas en sessions/canonical/, y registro en progress.json.
+"""
+
+import json
+import re
+import sys
+from pathlib import Path
+
+SESSION_FIELDS = ("id", "date", "project", "title", "lang", "katas")
+KATA_FIELDS = ("id", "title", "concept", "level", "spec_html", "stub", "test", "canonical", "skeleton")
+
+
+def fail(msg):
+    print(f"[error] {msg}", file=sys.stderr)
+    sys.exit(1)
+
+
+def _natural_key(filename):
+    """Clave de orden natural: los tramos numericos del nombre (sin .js)
+    se comparan como int, no como string, para que '-2' ordene tras la
+    base y '-10' tras '-2' (sorted(..., reverse=True) da el mas reciente
+    primero de verdad, no solo por orden ASCII de caracteres)."""
+    stem = filename[:-3] if filename.endswith(".js") else filename
+    return [int(part) if part.isdigit() else part
+            for part in re.split(r"(\d+)", stem)]
+
+
+def load_session(path):
+    try:
+        session = json.loads(Path(path).read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError) as e:
+        fail(f"unreadable session JSON: {e}")
+    for f in SESSION_FIELDS:
+        if f not in session:
+            fail(f"session missing field: {f}")
+    if not session["katas"]:
+        fail("session has no katas")
+    for kata in session["katas"]:
+        for f in KATA_FIELDS:
+            if f not in kata:
+                fail(f"kata {kata.get('id', '?')} missing field: {f}")
+    return session
+
+
+def write_outputs(session, user_dir):
+    sessions_dir = Path(user_dir) / "sessions"
+    canonical_dir = sessions_dir / "canonical"
+    canonical_dir.mkdir(parents=True, exist_ok=True)
+
+    # 1. Canonicas fuera de la app (primero limpiar huerfanas de una regeneracion
+    #    con menos katas que la vez anterior)
+    for old_canonical in canonical_dir.glob(f"{session['id']}__*.py"):
+        old_canonical.unlink()
+    for kata in session["katas"]:
+        (canonical_dir / f"{session['id']}__{kata['id']}.py").write_text(
+            kata["canonical"], encoding="utf-8")
+    public = dict(session)
+    public["katas"] = [{k: v for k, v in kata.items() if k != "canonical"}
+                       for kata in session["katas"]]
+
+    # 2. Archivo de sesion (JS para poder cargarse desde file://)
+    js = ("window.MM_SESSIONS = window.MM_SESSIONS || [];\n"
+          f"window.MM_SESSIONS.push({json.dumps(public, ensure_ascii=False, indent=2)});\n")
+    (sessions_dir / f"{session['id']}.js").write_text(js, encoding="utf-8")
+
+    # 3. Manifest regenerado del contenido real de la carpeta, mas reciente primero
+    #    (orden natural sobre el nombre, no orden ASCII puro: ver _natural_key)
+    files = sorted((p.name for p in sessions_dir.glob("*.js") if p.name != "manifest.js"),
+                   key=_natural_key, reverse=True)
+    (sessions_dir / "manifest.js").write_text(
+        f"window.MM_MANIFEST = {json.dumps(files, indent=2)};\n", encoding="utf-8")
+
+    # 4. Progreso: registrar la sesion con sus esqueletos (los aciertos los anota review)
+    progress_path = Path(user_dir) / "progress.json"
+    if progress_path.is_file():
+        progress = json.loads(progress_path.read_text(encoding="utf-8"))
+    else:
+        progress = {"concepts": {}, "excluded": [], "sessions": []}
+    progress.setdefault("excluded", [])
+    progress["sessions"] = [s for s in progress["sessions"] if s["id"] != session["id"]]
+    progress["sessions"].append(
+        {"id": session["id"],
+         "concepts": [k["concept"] for k in session["katas"]],
+         "skeletons": [k["skeleton"] for k in session["katas"]]})
+    progress_path.write_text(json.dumps(progress, ensure_ascii=False, indent=2),
+                             encoding="utf-8")
+
+    # 5. Track record legible: una entrada por sesion, append-only
+    #    (idempotente: reejecutar el mismo id no debe duplicar su entrada)
+    history_path = Path(user_dir) / "history.md"
+    if not history_path.is_file():
+        history_path.write_text("# Training history\n", encoding="utf-8")
+    history_content = history_path.read_text(encoding="utf-8")
+    marker = f"<!-- session: {session['id']} -->"
+    if marker not in history_content:
+        concepts_line = ", ".join(f"{k['concept']} (N{k['level']})" for k in session["katas"])
+        entry = (f"\n## {session['date']} — {session['project']}\n"
+                 f"{marker}\n- Sesion: {concepts_line}\n")
+        with open(history_path, "a", encoding="utf-8") as f:
+            f.write(entry)
+
+
+def main():
+    if len(sys.argv) != 3:
+        fail("usage: build_session.py <session.json> <user_dir>")
+    session = load_session(sys.argv[1])
+    write_outputs(session, sys.argv[2])
+    print(f"Session {session['id']} written: {len(session['katas'])} katas")
+
+
+if __name__ == "__main__":
+    main()

package/skills/muscle-memory/scripts/scan_repo.py

@@ -0,0 +1,292 @@
+#!/usr/bin/env python3
+"""Escanea los cambios recientes de un repo para alimentar la generacion de katas.
+
+Salida legible en ingles: archivos .py tocados, resumen por archivo (clases,
+funciones, decoradores, imports) y conceptos candidatos como slugs canonicos.
+
+Uso:
+    python scan_repo.py --days 7 --repo /path/to/project
+"""
+
+import argparse
+import ast
+import os
+import subprocess
+import sys
+from datetime import datetime, timedelta
+
+# Unica fuente de verdad de los slugs. Las carpetas de library-seed/ usan estos nombres.
+CONCEPT_SLUGS = {
+    "classes", "methods", "properties", "dataclasses", "dunder-methods",
+    "inheritance", "exceptions", "typing", "enums", "context-managers",
+    "decorators", "generators", "comprehensions", "iterators", "async",
+    "factory", "strategy", "observer", "adapter", "singleton",
+}
+
+
+def run_git(repo, args):
+    try:
+        out = subprocess.run(["git", "-C", repo, *args],
+                             capture_output=True, text=True, check=True)
+        return out.stdout.strip()
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        return None
+
+
+def recent_files(repo, days):
+    since = (datetime.now() - timedelta(days=days)).strftime("%Y-%m-%d")
+    out = run_git(repo, ["log", f"--since={since}", "--name-only",
+                         "--pretty=format:", "--", "*.py"])
+    if out is None:
+        return None
+    return sorted({l.strip() for l in out.splitlines() if l.strip().endswith(".py")})
+
+
+def _deco_name(node):
+    if isinstance(node, ast.Name):
+        return node.id
+    if isinstance(node, ast.Attribute):
+        return node.attr
+    if isinstance(node, ast.Call):
+        return _deco_name(node.func)
+    return None
+
+
+# Nodos que denotan "logica real" (no glue): ramas, bucles, comprehensions,
+# comparaciones, manejo de errores... Cuantos mas, mas jugosa es la funcion
+# para convertirla en una kata de reconstruccion.
+_LOGIC_NODES = (
+    ast.If, ast.For, ast.While, ast.Try, ast.With, ast.Raise, ast.Assert,
+    ast.BoolOp, ast.Compare, ast.IfExp, ast.comprehension,
+    ast.ListComp, ast.SetComp, ast.DictComp, ast.GeneratorExp,
+)
+
+
+def _signature(fn):
+    """Firma legible: nombre(arg1, arg2, ...) sin tipos, para el menu del scan."""
+    a = fn.args
+    parts = [arg.arg for arg in (a.posonlyargs + a.args)]
+    if a.vararg:
+        parts.append("*" + a.vararg.arg)
+    if a.kwonlyargs:
+        if not a.vararg:
+            parts.append("*")
+        parts.extend(arg.arg for arg in a.kwonlyargs)
+    if a.kwarg:
+        parts.append("**" + a.kwarg.arg)
+    return f"{fn.name}({', '.join(parts)})"
+
+
+def _logic_score(fn):
+    """Cuenta nodos de logica dentro de la funcion (excluye su propia cabecera)."""
+    return sum(1 for n in ast.walk(fn) if isinstance(n, _LOGIC_NODES))
+
+
+def _reconstruction_candidates(tree):
+    """Funciones/metodos con logica reconstruible, ordenados por riqueza de logica.
+
+    Devuelve lista de dicts: name, qualname, sig, line, score, is_async.
+    Se salta cabeceras triviales (score < 2) y los dunder salvo los interesantes.
+    """
+    out = []
+    for node in ast.walk(tree):
+        if isinstance(node, ast.ClassDef):
+            for m in node.body:
+                if isinstance(m, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                    _maybe_candidate(out, m, prefix=node.name + ".")
+        elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            # Solo funciones a nivel de modulo aqui; los metodos ya salen arriba.
+            if not any(node in getattr(c, "body", []) for c in ast.walk(tree)
+                       if isinstance(c, ast.ClassDef)):
+                _maybe_candidate(out, node, prefix="")
+    out.sort(key=lambda c: -c["score"])
+    return out
+
+
+def _maybe_candidate(out, fn, prefix):
+    score = _logic_score(fn)
+    if score < 2:
+        return
+    if fn.name.startswith("__") and fn.name.endswith("__") and fn.name != "__eq__":
+        return
+    out.append({
+        "name": fn.name,
+        "cls": prefix,  # "Clase." o "" ; la firma ya incluye el nombre de la funcion
+        "sig": _signature(fn),
+        "line": fn.lineno,
+        "score": score,
+        "is_async": isinstance(fn, ast.AsyncFunctionDef),
+    })
+
+
+def extract_concepts(path):
+    """Devuelve dict con classes/functions/decorators/imports/signals, o None si no parsea."""
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            tree = ast.parse(f.read(), filename=path)
+    except (SyntaxError, OSError, UnicodeDecodeError):
+        return None
+
+    classes, functions, decorators, imports = [], [], set(), set()
+    signals = set()
+
+    for node in ast.walk(tree):
+        if isinstance(node, ast.ClassDef):
+            # Captura bases simples (ast.Name) y cualificadas (ast.Attribute).
+            # Ej: class Status(Enum) -> "Enum", class Status(enum.Enum) -> "Enum"
+            bases = []
+            for b in node.bases:
+                if isinstance(b, ast.Name):
+                    bases.append(b.id)
+                elif isinstance(b, ast.Attribute):
+                    bases.append(b.attr)
+            classes.append((node.name, bases))
+            signals.add("classes")
+            for d in node.decorator_list:
+                name = _deco_name(d)
+                if name:
+                    decorators.add(name)
+                    if name == "dataclass":
+                        signals.add("dataclasses")
+            methods = {n.name for n in node.body
+                       if isinstance(n, (ast.FunctionDef, ast.AsyncFunctionDef))}
+            if "__enter__" in methods:
+                signals.add("context-managers")
+            if methods & {"__iter__", "__next__"}:
+                signals.add("iterators")
+            if any(m.startswith("__") and m.endswith("__")
+                   and m not in {"__init__", "__enter__", "__exit__", "__iter__", "__next__"}
+                   for m in methods):
+                signals.add("dunder-methods")
+            if bases:
+                signals.add("inheritance")
+                if "Enum" in bases:
+                    signals.add("enums")
+        elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            functions.append(node.name)
+            if isinstance(node, ast.AsyncFunctionDef):
+                signals.add("async")
+            for d in node.decorator_list:
+                name = _deco_name(d)
+                if name:
+                    decorators.add(name)
+            if any(isinstance(n, (ast.Yield, ast.YieldFrom)) for n in ast.walk(node)):
+                signals.add("generators")
+        elif isinstance(node, (ast.ListComp, ast.SetComp, ast.DictComp, ast.GeneratorExp)):
+            signals.add("comprehensions")
+        elif isinstance(node, ast.Await):
+            signals.add("async")
+        elif isinstance(node, ast.Try):
+            signals.add("exceptions")
+        elif isinstance(node, (ast.Import, ast.ImportFrom)):
+            mod = getattr(node, "module", None)
+            if isinstance(node, ast.Import):
+                for a in node.names:
+                    imports.add(a.name.split(".")[0])
+            elif mod:
+                imports.add(mod.split(".")[0])
+                names = {a.name for a in node.names}
+                if mod == "dataclasses":
+                    signals.add("dataclasses")
+                if mod == "enum":
+                    signals.add("enums")
+                if mod == "typing" and names & {"Protocol", "TypedDict", "Optional", "Union"}:
+                    signals.add("typing")
+                if mod == "abc":
+                    signals.add("inheritance")
+                if mod == "contextlib":
+                    signals.add("context-managers")
+                if mod == "asyncio":
+                    signals.add("async")
+
+    if decorators - {"dataclass", "property", "staticmethod", "classmethod"}:
+        signals.add("decorators")
+    if decorators & {"property", "staticmethod", "classmethod"}:
+        signals.add("properties" if "property" in decorators else "methods")
+
+    assert signals <= CONCEPT_SLUGS, f"slug fuera de catalogo: {signals - CONCEPT_SLUGS}"
+    return {
+        "classes": classes,
+        "functions": functions[:20],
+        "decorators": sorted(decorators),
+        "imports": sorted(imports),
+        "signals": sorted(signals),
+        "candidates": _reconstruction_candidates(tree),
+    }
+
+
+def main():
+    p = argparse.ArgumentParser(description="Scan recent repo changes for kata generation.")
+    p.add_argument("--days", type=int, default=7)
+    p.add_argument("--repo", default=".")
+    p.add_argument("--max-files", type=int, default=15)
+    args = p.parse_args()
+
+    repo = os.path.abspath(args.repo)
+    if not os.path.isdir(repo):
+        print(f"[error] Folder does not exist: {repo}")
+        sys.exit(0)
+
+    files = recent_files(repo, args.days)
+    if files is None:
+        print("[warn] Not a git repository (or git unavailable).")
+        print("Ask the user for a folder or .py files and read them directly.")
+        sys.exit(0)
+    if not files:
+        print(f"[warn] No .py files modified in the last {args.days} days.")
+        print("Widen the window (--days) or ask which topic to practice.")
+        sys.exit(0)
+
+    print(f"# Recent code scan ({args.days} days) in {repo}\n")
+    print(f".py files touched: {len(files)}\n")
+
+    global_signals = {}
+    all_candidates = []
+    for rel in files[: args.max_files]:
+        path = os.path.join(repo, rel)
+        if not os.path.isfile(path):
+            continue
+        info = extract_concepts(path)
+        if not info:
+            continue
+        print(f"## {rel}")
+        if info["classes"]:
+            desc = ", ".join(f"{n}" + (f"({', '.join(b)})" if b else "")
+                             for n, b in info["classes"])
+            print(f"- Classes: {desc}")
+        if info["functions"]:
+            print(f"- Functions: {', '.join(info['functions'])}")
+        if info["decorators"]:
+            print(f"- Decorators: {', '.join(info['decorators'])}")
+        if info["imports"]:
+            print(f"- Imports: {', '.join(info['imports'])}")
+        if info["signals"]:
+            print(f"- Concepts: {', '.join(info['signals'])}")
+            for s in info["signals"]:
+                global_signals[s] = global_signals.get(s, 0) + 1
+        for c in info["candidates"]:
+            c["file"] = rel
+            all_candidates.append(c)
+        print()
+
+    # Menu principal para Generate: codigo REAL que merece reconstruir como kata.
+    # Cada linea es un simbolo del repo; Generate lee su fuente y lo reconstruye
+    # en Python puro (misma logica y nombres, sin dependencias del framework).
+    if all_candidates:
+        all_candidates.sort(key=lambda c: -c["score"])
+        print("## Reconstruction candidates (real code to turn into katas)")
+        print("Read each symbol's source and rebuild it as a stdlib-only kata.\n")
+        for c in all_candidates[:20]:
+            tag = "async " if c["is_async"] else ""
+            print(f"- {c['file']}:{c['line']} {tag}{c['cls']}{c['sig']} "
+                  f"[logic {c['score']}]")
+        print()
+
+    if global_signals:
+        print("## Candidate concepts (for progress/leveling)")
+        for slug, n in sorted(global_signals.items(), key=lambda x: -x[1]):
+            print(f"- {slug} (in {n} file/s)")
+
+
+if __name__ == "__main__":
+    main()