codebeacon 0.3.3__tar.gz → 0.5.0__tar.gz

{codebeacon-0.3.3 → codebeacon-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codebeacon
-Version: 0.3.3
+Version: 0.5.0
 Summary: Source code AST analysis tool for AI context generation — unified multi-framework knowledge graph
 Project-URL: Homepage, https://github.com/codebeacon/codebeacon
 Project-URL: Repository, https://github.com/codebeacon/codebeacon
@@ -97,6 +97,11 @@ Existing tools solve this partially. Route analyzers map your controllers but mi
 - **Zero configuration** — auto-detects frameworks and languages; generates `codebeacon.yaml` for repeat runs
 - **Deep-dive mode** — `--deep-dive` generates per-project `.codebeacon/` + `CLAUDE.md` for every sub-project; running `codebeacon scan . --update` from any sub-project folder automatically syncs all projects in the workspace
 - **Workspace auto-rediscovery** — on every `scan` / `sync`, codebeacon re-scans the workspace and appends any new project folders to `codebeacon.yaml` before extraction, so freshly added sub-projects are never silently skipped; pass `--no-rediscover` to opt out for hand-curated configs
+- **Graphify-style semantic enrichment** — after AST extraction, the skill dispatches one parallel subagent per chunk to emit `{nodes, edges, hyperedges}` with 8 relation types (`calls`/`implements`/`references`/`cites`/`conceptually_related_to`/`shares_data_with`/`semantically_similar_to`/`rationale_for`) and EXTRACTED/INFERRED/AMBIGUOUS confidence; on Claude Code the subagent runs one tier below the host model (Opus→Sonnet, Sonnet→Haiku) so spend stays proportional to corpus size. AST owns code nodes; LLM only contributes `concept`/`document`/`paper` nodes. Existing 0.3.x archives replay through the new schema unchanged.
+- **Knowledge mode (`codebeacon knowledge`)** — scan markdown notes (ADRs, meeting notes, retros, specs, research) and produce a single `KNOWLEDGE.md` next to `.codebeacon/`. Auto-classifies by filename and heading patterns, parses Obsidian YAML frontmatter and `[[backlinks]]`, surfaces a top-level "Key Decisions" + "Open Questions" rollup so an agent learns *why* the codebase looks the way it does. Pure heuristics — no LLM call.
+- **Bare-path shortcut** — `codebeacon ./src` is now equivalent to `codebeacon scan ./src`; when the first argument isn't a registered subcommand, `scan` is auto-injected, so muscle memory from `graphify <path>` / `codesight <path>` works here too.
+- **Hardened semantic pipeline** — `semantic-apply` guards against malformed agent JSONL (null/list/code-fence lines, missing fields), coerces broken `confidence_score` values (None/NaN/string/out-of-range) to a safe default, snapshots `beacon.json` → `beacon.json.bak` before merging so the AST baseline is always recoverable, and regenerates `beacon.html` + `callflow.html` so visual exports reflect the newly-inferred edges.
+- **Sensitive file/dir guard** — `secrets/`, `credentials/`, `.ssh/`, `.aws/`, `.gnupg/` directories are always skipped; filenames matching credential patterns (`api_token`, `oauth_token`, `private_key`, `client_secret`; underscore *and* hyphen variants) are excluded from the source-file collector before they reach extractors.
 
 ---
 
@@ -185,11 +190,14 @@ project-root/
         components/<Name>.md
     obsidian/            ← Obsidian vault (one note per graph node)
     semantic/
-      original.jsonl     ← durable archive of every applied AI-semantic result
-                           (skipped on rescans, never re-emitted as a task)
-    semantic-tasks.jsonl     ← pending AI-semantic batch (present only between
-                               `semantic-prepare` and `semantic-apply`)
-    semantic-results.jsonl   ← agent-written results (same lifecycle as above)
+      pending/           ← prepare writes chunk_NNN.jsonl here (≤ --chunk-size tasks each)
+        chunk_001.jsonl
+        chunk_002.jsonl
+      results/           ← agent writes a matching chunk_NNN.jsonl per pending file
+        chunk_001.jsonl
+      original/          ← apply moves done chunks here (durable archive)
+        chunk_001.jsonl
+        chunk_002.jsonl  ← (older runs accumulate; chunk numbers are monotonic)
 ```
 
 ### Deep Dive Mode
@@ -356,14 +364,21 @@ codebeacon sync --config <file>           # use a specific config file
 codebeacon sync --no-rediscover           # don't auto-append newly added projects (hand-curated yaml mode)
 
 # AI-semantic enrichment (the agent does the LLM work, codebeacon does the bookkeeping)
-codebeacon semantic-prepare [--dir .codebeacon] [--max-tasks N]
-                                          # rehydrate semantic archive onto beacon.json, emit fresh tasks
-                                          # for NEW candidates only (god-node folders + unresolved targets);
-                                          # writes .codebeacon/semantic-tasks.jsonl
+codebeacon semantic-prepare [--dir .codebeacon] [--max-tasks N] [--chunk-size N]
+                                          # rehydrate archive (.codebeacon/semantic/original/*.jsonl) onto
+                                          # the fresh graph, prune entries pointing at missing nodes,
+                                          # then emit every NEW candidate (god folders + hub files +
+                                          # unresolved targets) into .codebeacon/semantic/pending/
+                                          # chunk_NNN.jsonl (--chunk-size tasks per file, default 10).
+                                          # `--max-tasks` is an optional cap (0 = no cap = emit all).
+                                          # task_id includes a content hash, so a file whose semantic
+                                          # content changes between scans is automatically re-emitted.
 codebeacon semantic-apply   [--dir .codebeacon]
-                                          # read .codebeacon/semantic-results.jsonl, merge as INFERRED
-                                          # references edges, append to .codebeacon/semantic/original.jsonl
-                                          # archive, clear pending files, regenerate wiki/obsidian/context map
+                                          # for each .codebeacon/semantic/results/chunk_NNN.jsonl the
+                                          # agent has written, merge edges (INFERRED references) into
+                                          # beacon.json and MOVE the pending chunk into
+                                          # .codebeacon/semantic/original/chunk_NNN.jsonl (durable
+                                          # archive). Regenerates wiki/obsidian/context map.
 
 # Query the knowledge graph
 codebeacon query <term> [--dir .codebeacon] [--limit N]   # search nodes by label substring
@@ -398,22 +413,23 @@ The CLI itself never makes an LLM API call. The AI-semantic layer is intentional
 When you invoke `/codebeacon` in Claude Code:
 
 1. `scan` / `sync` builds `beacon.json` from the AST (no LLM).
-2. `codebeacon semantic-prepare` re-applies the prior archive to the fresh graph, then writes `.codebeacon/semantic-tasks.jsonl` containing **only new candidates** — files that score high (unresolved-target edges + god-node folders) and have never been processed before.
-3. The skill loops over the tasks file. For each line, the agent (using its current model) reads the `excerpt` field and returns inferred references inline. Results are written to `.codebeacon/semantic-results.jsonl`.
-4. `codebeacon semantic-apply` merges the results as `INFERRED references` edges into `beacon.json`, **appends them to `.codebeacon/semantic/original.jsonl`** (the durable archive), clears the pending tasks/results files, and regenerates wiki + obsidian + context map.
-5. Next scan: `semantic-prepare` rehydrates the archive onto the freshly built graph (so historical inferences don't disappear) and emits a tasks file with **only newly discovered candidates** since the last archive. Already-processed files are skipped via `task_id` (SHA1 of `file_path|node_id`).
+2. `codebeacon semantic-prepare` rehydrates the archive at `.codebeacon/semantic/original/*.jsonl` onto the fresh graph, **prunes** archive entries whose source node no longer exists, and writes new task chunks to `.codebeacon/semantic/pending/chunk_NNN.jsonl` (≤ `--chunk-size` tasks per file, default 10). Chunk numbers continue from where the durable archive left off, so they never collide.
+3. The skill iterates the pending chunks **one chunk at a time**. For each `pending/chunk_NNN.jsonl`, the agent (using its current model) reads each task's `excerpt` and writes a matching `semantic/results/chunk_NNN.jsonl`.
+4. `codebeacon semantic-apply` merges the results as `INFERRED references` edges into `beacon.json` and **moves** each finished `pending/chunk_NNN.jsonl` into `semantic/original/chunk_NNN.jsonl` (with the applied edges spliced in for auditability). Result files are deleted; wiki + obsidian + context map regenerated.
+5. Next scan: `semantic-prepare` reads every chunk under `original/`, applies their edges to the freshly built graph (so historical inferences don't disappear), and skips any task whose `task_id` is already on file. `task_id` is `SHA1(file_path | node_id | excerpt_hash[:8])` — a file whose semantic content changes earns a new id and gets re-analysed automatically.
 
-This gives you incremental, idempotent enrichment: the agent never re-analyzes the same file twice, and accumulated AI signal survives every rescan.
+This gives you incremental, idempotent enrichment: the agent never re-analyses the same `(file, content)` twice, accumulated AI signal survives every rescan, and chunked files keep the agent's working set small.
 
 ### Direct CLI usage
 
-If you're not running through the skill (e.g. CI), you can drive the same two commands manually and supply your own `semantic-results.jsonl`:
+If you're not running through the skill (e.g. CI), you can drive the same two commands manually and supply your own `results/chunk_NNN.jsonl` files:
 
 ```bash
 codebeacon scan .
-codebeacon semantic-prepare --dir .codebeacon --max-tasks 50
+codebeacon semantic-prepare --dir .codebeacon --max-tasks 50 --chunk-size 10
 
-# now write .codebeacon/semantic-results.jsonl yourself; each line is:
+# .codebeacon/semantic/pending/chunk_001.jsonl ... now exist.
+# For each pending chunk, write a matching results/chunk_NNN.jsonl. Each line:
 #   {"task_id":"...", "source_node_id":"...", "edges":[
 #     {"target_name":"UserService","relation":"references","confidence_score":0.7}
 #   ]}

{codebeacon-0.3.3 → codebeacon-0.5.0}/README.de.md

@@ -56,6 +56,11 @@ Bestehende Tools lösen dieses Problem nur teilweise. Route-Analyzer erfassen Ih
 - **Keine Konfiguration notwendig** — erkennt Frameworks und Sprachen automatisch; generiert `codebeacon.yaml` für Folgeläufe
 - **Deep-Dive-Modus** — `--deep-dive` erzeugt für jedes Sub-Projekt eigene `.codebeacon/` + `CLAUDE.md`; ein Update-Aufruf aus **beliebigem** Sub-Projekt-Ordner synchronisiert automatisch alle Projekte im Workspace
 - **Automatische Workspace-Wiedererkennung** — bei jedem `scan`/`sync` scannt codebeacon den Workspace erneut und hängt vor der Extraktion automatisch neue Projekte an die `codebeacon.yaml` an, sodass frisch hinzugefügte Sub-Projekte nicht unbemerkt übersprungen werden; `--no-rediscover` deaktiviert dies für handgepflegte Konfigurationen
+- **Graphify-artige Semantik-Anreicherung** — nach der AST-Extraktion dispatcht der Skill einen parallelen Subagenten pro Chunk, der vollständige Knowledge-Graph-Fragmente `{nodes, edges, hyperedges}` mit 8 Relationstypen (`calls`/`implements`/`references`/`cites`/`conceptually_related_to`/`shares_data_with`/`semantically_similar_to`/`rationale_for`) und Konfidenz EXTRACTED/INFERRED/AMBIGUOUS erzeugt; auf Claude Code läuft der Subagent eine Stufe unter dem Host-Modell (Opus→Sonnet, Sonnet→Haiku), damit die Kosten proportional zur Korpus-Größe bleiben. Code-Knoten gehören dem AST; das LLM darf nur `concept`/`document`/`paper`-Knoten beisteuern. Bestehende 0.3.x-Archive werden unter dem neuen Schema unverändert wiedergegeben
+- **Wissensmodus (`codebeacon knowledge`)** — scannt Markdown-Notizen (ADRs, Meeting-Protokolle, Retros, Specs, Research) und erzeugt eine einzelne `KNOWLEDGE.md` neben `.codebeacon/`. Automatische Klassifizierung nach Dateinamen- und Überschriftenmustern, Parsing von Obsidian-YAML-Frontmatter und `[[backlinks]]`, sowie ein „Key Decisions" + „Open Questions"-Roll-up ganz oben, damit der Agent versteht, *warum* die Codebasis so aussieht, wie sie aussieht. Reine Heuristik — kein LLM-Aufruf
+- **Pfad-Kurzform** — `codebeacon ./src` ist jetzt äquivalent zu `codebeacon scan ./src`; wenn das erste Argument kein registrierter Sub-Befehl ist, wird `scan` automatisch eingefügt — die `graphify <path>` / `codesight <path>` Muskelerinnerung funktioniert genauso
+- **Gehärtete Semantik-Pipeline** — `semantic-apply` schützt vor fehlerhaftem Agent-JSONL (null/Listen/Code-Fence-Zeilen, fehlende Felder), coerced kaputte `confidence_score`-Werte (None/NaN/String/außerhalb des Bereichs) zu einem sicheren Default, snapshottet `beacon.json` → `beacon.json.bak` vor dem Merge, sodass die AST-Baseline jederzeit wiederherstellbar ist, und regeneriert `beacon.html` + `callflow.html`, damit die visuellen Exporte die neu inferierten Kanten reflektieren
+- **Schutzschienen für sensible Dateien/Verzeichnisse** — `secrets/`, `credentials/`, `.ssh/`, `.aws/`, `.gnupg/` werden immer übersprungen; Dateinamen, die Credential-Mustern entsprechen (`api_token`, `oauth_token`, `private_key`, `client_secret`; Underscore- *und* Bindestrich-Varianten) werden vom Collector vor den Extraktoren ausgeschlossen
 
 ---
 
@@ -378,16 +383,19 @@ codebeacon hook install [path]            # Merge-Driver + Post-Commit-Inkrement
 codebeacon merge-driver <base> <cur> <other>  # von git nach `hook install` aufgerufen; Union-Merge von beacon.json
 
 # AI-semantische Anreicherung (LLM macht der Agent, codebeacon nur die Buchführung)
-codebeacon semantic-prepare [--dir .codebeacon] [--max-tasks N]
-                                          # spielt vorhandenes Archiv wieder auf das frische
-                                          # beacon.json an und gibt Aufgaben nur für NEUE
-                                          # Kandidaten aus (god-node-Ordner + unaufgelöste Ziele)
+codebeacon semantic-prepare [--dir .codebeacon] [--max-tasks N] [--chunk-size N]
+                                          # rehydriert .codebeacon/semantic/original/*.jsonl auf das
+                                          # frische beacon.json + entfernt Einträge mit verschwundenen
+                                          # Knoten, schreibt dann neue Aufgaben nach
+                                          # .codebeacon/semantic/pending/chunk_NNN.jsonl
+                                          # (--chunk-size pro Chunk, Std. 10). task_id enthält einen
+                                          # Content-Hash – geänderte Dateien werden neu emittiert.
 codebeacon semantic-apply   [--dir .codebeacon]
-                                          # mergt .codebeacon/semantic-results.jsonl als
-                                          # INFERRED references-Kanten in beacon.json,
-                                          # hängt an .codebeacon/semantic/original.jsonl an,
-                                          # räumt Pending-Dateien auf und regeneriert
-                                          # wiki/obsidian/Kontextkarte
+                                          # für jede vom Agent geschriebene .codebeacon/semantic/
+                                          # results/chunk_NNN.jsonl: INFERRED references-Kanten in
+                                          # beacon.json mergen + den Pending-Chunk nach
+                                          # .codebeacon/semantic/original/chunk_NNN.jsonl VERSCHIEBEN
+                                          # (dauerhaftes Archiv). Results löschen, alles regenerieren.
 
 codebeacon serve [--dir .codebeacon]      # MCP-Server starten (stdio)
 codebeacon install                        # Claude-Code-Skill installieren
@@ -413,22 +421,24 @@ Das CLI selbst **ruft niemals einen LLM-Anbieter auf**. Die AI-semantik-Schicht
 Wenn Sie `/codebeacon` in Claude Code aufrufen:
 
 1. `scan` / `sync` baut `beacon.json` aus dem AST (kein LLM-Aufruf).
-2. `codebeacon semantic-prepare` spielt das frühere Archiv wieder auf den frischen Graphen ein und schreibt dann `.codebeacon/semantic-tasks.jsonl` mit **nur neuen Kandidaten** — hochbewertete Dateien (Kanten zu nicht aufgelösten Zielen + god-node-Ordner), die noch nie verarbeitet wurden.
-3. Der Skill iteriert die Tasks-Datei. Für jede Zeile liest der Agent (mit dem Modell der aktuellen Sitzung) das `excerpt`-Feld und liefert inline gefolgerte References. Ergebnisse werden in `.codebeacon/semantic-results.jsonl` geschrieben.
-4. `codebeacon semantic-apply` mergt die Ergebnisse als `INFERRED references`-Kanten in `beacon.json`, **hängt sie an `.codebeacon/semantic/original.jsonl`** (das dauerhafte Archiv) an, räumt die Pending-Dateien auf und regeneriert Wiki + Obsidian + Kontextkarte.
-5. Beim nächsten Scan: `semantic-prepare` rehydriert das Archiv auf den frisch gebauten Graphen (damit historische Inferenzen nicht durch ein erneutes Scannen verschwinden) und gibt eine Tasks-Datei mit **nur den seit dem letzten Archiv neu entdeckten Kandidaten** aus. Bereits verarbeitete Dateien werden per `task_id` (SHA1 von `file_path|node_id`) übersprungen.
+2. `codebeacon semantic-prepare` rehydriert das Archiv unter `.codebeacon/semantic/original/*.jsonl` auf den frischen Graphen und **entfernt** Einträge, deren Quellknoten nicht mehr existiert. Anschließend schreibt es neue Aufgaben nach `.codebeacon/semantic/pending/chunk_NNN.jsonl` (≤ `--chunk-size` pro Datei, Std. 10). Chunk-Nummern setzen genau dort an, wo das dauerhafte Archiv aufhört — keine Kollisionen möglich.
+3. Der Skill verarbeitet Pending-Chunks **einzeln**. Für jedes `pending/chunk_NNN.jsonl` liest der Agent (mit dem Modell der laufenden Sitzung) den `excerpt` jeder Aufgabe und schreibt eine gleichnamige `semantic/results/chunk_NNN.jsonl`.
+4. `codebeacon semantic-apply` mergt die Ergebnisse als `INFERRED references`-Kanten in `beacon.json` und **verschiebt** jede abgeschlossene `pending/chunk_NNN.jsonl` nach **`semantic/original/chunk_NNN.jsonl`** (mit den angewandten Kanten zur Nachvollziehbarkeit). Die Result-Dateien werden gelöscht, Wiki + Obsidian + Kontextkarte regeneriert.
+5. Beim nächsten Scan: `semantic-prepare` liest jeden Chunk unter `original/`, wendet seine Kanten auf den frisch gebauten Graphen an (historische Inferenzen bleiben erhalten) und überspringt jede Aufgabe, deren `task_id` bereits archiviert ist. `task_id` = `SHA1(file_path | node_id | excerpt_hash[:8])` — ändert sich der semantische Inhalt einer Datei, bekommt sie eine neue id und wird neu analysiert.
 
-Das ergibt inkrementelle, idempotente Anreicherung: der Agent analysiert dieselbe Datei nie zweimal, und das angesammelte AI-Signal überlebt jeden Rescan.
+Inkrementelle, idempotente Anreicherung: der Agent analysiert dieselbe (Datei, Inhalt)-Kombination nie zweimal, das angesammelte AI-Signal überlebt jeden Rescan, und die Chunk-Aufteilung hält den Arbeitsumfang des Agenten klein.
 
 ### Direkte CLI-Nutzung
 
-Wenn Sie nicht über den Skill gehen (z. B. CI), können Sie dieselben zwei Befehle manuell ausführen und Ihr eigenes `semantic-results.jsonl` liefern:
+Wenn Sie nicht über den Skill gehen (z. B. CI), können Sie dieselben zwei Befehle manuell ausführen und Ihre eigenen `results/chunk_NNN.jsonl` liefern:
 
 ```bash
 codebeacon scan .
-codebeacon semantic-prepare --dir .codebeacon --max-tasks 50
+codebeacon semantic-prepare --dir .codebeacon --max-tasks 50 --chunk-size 10
 
-# jetzt selbst .codebeacon/semantic-results.jsonl schreiben; jede Zeile:
+# .codebeacon/semantic/pending/chunk_001.jsonl ... existieren jetzt.
+# Schreiben Sie für jeden Pending-Chunk eine gleichnamige results/chunk_NNN.jsonl.
+# Jede Zeile:
 #   {"task_id":"...", "source_node_id":"...", "edges":[
 #     {"target_name":"UserService","relation":"references","confidence_score":0.7}
 #   ]}

{codebeacon-0.3.3 → codebeacon-0.5.0}/README.es.md

@@ -56,6 +56,11 @@ Las herramientas existentes resuelven esto de forma parcial. Los analizadores de
 - **Cero configuración** — detecta frameworks y lenguajes automáticamente; genera `codebeacon.yaml` para ejecuciones posteriores
 - **Modo Deep Dive** — `--deep-dive` genera `.codebeacon/` + `CLAUDE.md` propios para cada sub-proyecto; ejecutar el comando de actualización desde **cualquier** sub-proyecto sincroniza automáticamente todos los proyectos del workspace
 - **Auto-redescubrimiento del workspace** — en cada `scan`/`sync`, codebeacon re-escanea el workspace y añade automáticamente al `codebeacon.yaml` los nuevos proyectos antes de extraer, de modo que los sub-proyectos recién añadidos nunca se omitan silenciosamente; usa `--no-rediscover` para optar por el modo de configuración curada manualmente
+- **Enriquecimiento semántico estilo Graphify** — tras la extracción AST, el skill despacha un subagente paralelo por chunk para emitir fragmentos completos de grafo `{nodes, edges, hyperedges}` con 8 tipos de relación (`calls`/`implements`/`references`/`cites`/`conceptually_related_to`/`shares_data_with`/`semantically_similar_to`/`rationale_for`) y confianza EXTRACTED/INFERRED/AMBIGUOUS; en Claude Code el subagente se ejecuta un nivel por debajo del modelo host (Opus→Sonnet, Sonnet→Haiku) para mantener el gasto proporcional al tamaño del corpus. El AST posee los nodos de código; el LLM solo puede aportar nodos `concept`/`document`/`paper`. Los archivos 0.3.x existentes se replayean con el nuevo esquema sin cambios
+- **Modo de conocimiento (`codebeacon knowledge`)** — escanea notas markdown (ADRs, actas de reunión, retros, specs, research) y produce un único `KNOWLEDGE.md` junto a `.codebeacon/`. Clasifica automáticamente por patrones de nombre de fichero y de encabezados, parsea frontmatter YAML de Obsidian y `[[backlinks]]`, y muestra arriba un resumen de "Key Decisions" + "Open Questions" para que el agente entienda *por qué* el código tiene la forma que tiene. Heurística pura — sin llamadas a LLM
+- **Atajo de ruta** — `codebeacon ./src` ahora equivale a `codebeacon scan ./src`; cuando el primer argumento no es un subcomando registrado, `scan` se inyecta automáticamente, conservando la memoria muscular de `graphify <path>` / `codesight <path>`
+- **Pipeline semántico endurecido** — `semantic-apply` protege contra JSONL del agente mal formado (líneas null/lista/code-fence, campos faltantes), coerce valores rotos de `confidence_score` (None/NaN/string/fuera de rango) a un default seguro, snapshotea `beacon.json` → `beacon.json.bak` antes del merge para que la baseline AST siempre sea recuperable, y regenera `beacon.html` + `callflow.html` para que los exports visuales reflejen los nuevos edges inferidos
+- **Guardas de ficheros/directorios sensibles** — los directorios `secrets/`, `credentials/`, `.ssh/`, `.aws/`, `.gnupg/` se omiten siempre; los nombres de fichero que coincidan con patrones de credenciales (`api_token`, `oauth_token`, `private_key`, `client_secret`; variantes con guion bajo *y* guion) quedan excluidos del recolector antes de llegar a los extractores
 
 ---
 
@@ -376,16 +381,19 @@ codebeacon hook install [path]            # instala merge driver + hook post-com
 codebeacon merge-driver <base> <cur> <other>  # invocado por git tras `hook install`; union-merge de beacon.json
 
 # Enriquecimiento AI-semántico (el LLM lo ejecuta el agente, codebeacon lleva la contabilidad)
-codebeacon semantic-prepare [--dir .codebeacon] [--max-tasks N]
-                                          # rehidrata el archivo histórico sobre el nuevo beacon.json
-                                          # y emite tareas solo para candidatos NUEVOS
-                                          # (carpetas god-node + objetivos no resueltos)
+codebeacon semantic-prepare [--dir .codebeacon] [--max-tasks N] [--chunk-size N]
+                                          # rehidrata .codebeacon/semantic/original/*.jsonl sobre el
+                                          # nuevo beacon.json + poda entradas que apuntan a nodos
+                                          # desaparecidos, luego escribe tareas en
+                                          # .codebeacon/semantic/pending/chunk_NNN.jsonl
+                                          # (--chunk-size por chunk, predet. 10). El task_id incluye
+                                          # hash de contenido: si el archivo cambia, se reemite.
 codebeacon semantic-apply   [--dir .codebeacon]
-                                          # fusiona .codebeacon/semantic-results.jsonl como
-                                          # aristas INFERRED references en beacon.json,
-                                          # añade al archivo .codebeacon/semantic/original.jsonl,
-                                          # limpia los archivos pendientes y regenera
-                                          # wiki/obsidian/mapa de contexto
+                                          # por cada .codebeacon/semantic/results/chunk_NNN.jsonl que
+                                          # haya escrito el agente, fusiona las aristas INFERRED
+                                          # references en beacon.json y MUEVE el chunk pendiente a
+                                          # .codebeacon/semantic/original/chunk_NNN.jsonl (archivo
+                                          # durable). Borra los resultados y regenera todo.
 
 codebeacon serve [--dir .codebeacon]      # servidor MCP (stdio)
 codebeacon install                        # instalar skill de Claude Code
@@ -411,22 +419,24 @@ El CLI por sí mismo **nunca llama a un LLM**. La capa AI-semántica es propieda
 Cuando invocas `/codebeacon` en Claude Code:
 
 1. `scan` / `sync` construye `beacon.json` desde el AST (sin LLM).
-2. `codebeacon semantic-prepare` reaplica el archivo histórico sobre el grafo nuevo y luego escribe `.codebeacon/semantic-tasks.jsonl` con **sólo los candidatos nuevos** — archivos con puntuación alta (aristas a objetivos no resueltos + carpetas god-node) que nunca se han procesado.
-3. El skill itera sobre el archivo de tareas. Por cada línea, el agente (usando el modelo de su sesión actual) lee el campo `excerpt` y devuelve referencias inferidas en línea. Los resultados se escriben en `.codebeacon/semantic-results.jsonl`.
-4. `codebeacon semantic-apply` mezcla los resultados como aristas `INFERRED references` en `beacon.json`, **los anexa a `.codebeacon/semantic/original.jsonl`** (el archivo durable), limpia los ficheros pendientes y regenera wiki + obsidian + mapa de contexto.
-5. En la próxima ejecución: `semantic-prepare` rehidrata el archivo sobre el grafo recién construido (para que las inferencias históricas no desaparezcan en una nueva exploración) y emite un fichero de tareas con **sólo candidatos nuevos** desde la última actualización del archivo. Los archivos ya procesados se omiten vía `task_id` (SHA1 de `file_path|node_id`).
+2. `codebeacon semantic-prepare` rehidrata el archivo en `.codebeacon/semantic/original/*.jsonl` sobre el grafo nuevo y **poda** las entradas que apuntan a nodos ya desaparecidos. Después escribe los nuevos task chunks en `.codebeacon/semantic/pending/chunk_NNN.jsonl` (cada chunk ≤ `--chunk-size`, predet. 10). La numeración de chunks continúa donde dejó el archivo durable, así nunca colisiona.
+3. El skill itera los chunks pendientes **uno por uno**. Para cada `pending/chunk_NNN.jsonl`, el agente (con el modelo de su sesión actual) lee el `excerpt` de cada task y escribe un `semantic/results/chunk_NNN.jsonl` con el mismo nombre.
+4. `codebeacon semantic-apply` mezcla los resultados como aristas `INFERRED references` en `beacon.json` y **mueve** cada `pending/chunk_NNN.jsonl` terminado a **`semantic/original/chunk_NNN.jsonl`** (con las aristas aplicadas para auditoría). Los archivos de resultados se eliminan; wiki + obsidian + mapa de contexto se regeneran.
+5. En la siguiente ejecución: `semantic-prepare` lee cada chunk bajo `original/`, aplica sus aristas al grafo recién construido (las inferencias históricas no se pierden) y omite cualquier task cuyo `task_id` ya esté archivado. `task_id` = `SHA1(file_path | node_id | excerpt_hash[:8])`: si el contenido del archivo cambia, recibe un id nuevo y se reanaliza.
 
-Esto da enriquecimiento incremental e idempotente: el agente nunca reanaliza el mismo archivo dos veces, y la señal AI acumulada sobrevive a cada re-escaneo.
+Enriquecimiento incremental e idempotente: el agente nunca reanaliza la misma combinación (archivo, contenido) dos veces, la señal AI acumulada sobrevive a cada re-escaneo y los chunks mantienen pequeño el conjunto de trabajo del agente.
 
 ### Uso directo del CLI
 
-Si no usas el skill (p. ej. en CI), puedes ejecutar las mismas dos órdenes manualmente y suministrar tu propio `semantic-results.jsonl`:
+Si no usas el skill (p. ej. en CI), puedes ejecutar las mismas dos órdenes manualmente y proporcionar tus propios `results/chunk_NNN.jsonl`:
 
 ```bash
 codebeacon scan .
-codebeacon semantic-prepare --dir .codebeacon --max-tasks 50
+codebeacon semantic-prepare --dir .codebeacon --max-tasks 50 --chunk-size 10
 
-# ahora escribe tú mismo .codebeacon/semantic-results.jsonl; cada línea:
+# Existen .codebeacon/semantic/pending/chunk_001.jsonl ...
+# Para cada chunk pendiente, escribe un results/chunk_NNN.jsonl con el mismo
+# nombre. Cada línea:
 #   {"task_id":"...", "source_node_id":"...", "edges":[
 #     {"target_name":"UserService","relation":"references","confidence_score":0.7}
 #   ]}

{codebeacon-0.3.3 → codebeacon-0.5.0}/README.fr.md

@@ -56,6 +56,11 @@ Les outils existants ne résolvent ce problème qu'en partie. Les analyseurs de
 - **Zéro configuration** — détecte automatiquement les frameworks et langages ; génère `codebeacon.yaml` pour les exécutions suivantes
 - **Mode Deep Dive** — `--deep-dive` génère un `.codebeacon/` + `CLAUDE.md` propre à chaque sous-projet ; une commande de mise à jour depuis **n'importe quel** sous-projet synchronise automatiquement tous les projets du workspace
 - **Redécouverte automatique du workspace** — à chaque `scan`/`sync`, codebeacon réanalyse le workspace et ajoute automatiquement les nouveaux projets au `codebeacon.yaml` avant l'extraction, de sorte que les sous-projets fraîchement ajoutés ne soient jamais oubliés en silence ; utilisez `--no-rediscover` pour conserver une configuration yaml gérée manuellement
+- **Enrichissement sémantique façon Graphify** — après l'extraction AST, le skill dispatche un sous-agent parallèle par chunk pour émettre des fragments complets de knowledge graph `{nodes, edges, hyperedges}` avec 8 types de relations (`calls`/`implements`/`references`/`cites`/`conceptually_related_to`/`shares_data_with`/`semantically_similar_to`/`rationale_for`) et confiance EXTRACTED/INFERRED/AMBIGUOUS ; sur Claude Code, le sous-agent s'exécute un cran sous le modèle hôte (Opus→Sonnet, Sonnet→Haiku) pour garder le coût proportionnel à la taille du corpus. L'AST possède les nœuds de code ; le LLM ne peut contribuer que des nœuds `concept`/`document`/`paper`. Les archives 0.3.x existantes sont rejouées sous le nouveau schéma sans modification
+- **Mode connaissance (`codebeacon knowledge`)** — scanne les notes markdown (ADRs, comptes-rendus, rétros, specs, research) et produit un unique `KNOWLEDGE.md` à côté de `.codebeacon/`. Classification automatique par motifs de nom de fichier et de titres, parsing du frontmatter YAML Obsidian et des `[[backlinks]]`, et un résumé « Key Decisions » + « Open Questions » en tête pour que l'agent comprenne *pourquoi* la base de code a cette forme. Pure heuristique — sans appel LLM
+- **Raccourci chemin** — `codebeacon ./src` équivaut désormais à `codebeacon scan ./src` ; quand le premier argument n'est pas une sous-commande enregistrée, `scan` est injecté automatiquement, ce qui préserve la mémoire musculaire de `graphify <path>` / `codesight <path>`
+- **Pipeline sémantique durci** — `semantic-apply` protège contre les lignes JSONL mal formées de l'agent (null/listes/code-fences/champs manquants), coerce les valeurs cassées de `confidence_score` (None/NaN/string/hors-plage) vers un défaut sûr, snapshote `beacon.json` → `beacon.json.bak` avant le merge pour que la baseline AST reste toujours récupérable, et régénère `beacon.html` + `callflow.html` pour que les exports visuels reflètent les nouvelles arêtes inférées
+- **Garde-fous fichiers/dossiers sensibles** — les répertoires `secrets/`, `credentials/`, `.ssh/`, `.aws/`, `.gnupg/` sont toujours ignorés ; les noms de fichiers correspondant à des motifs de credentials (`api_token`, `oauth_token`, `private_key`, `client_secret` ; variantes avec underscore *et* tiret) sont exclus du collecteur avant d'atteindre les extracteurs
 
 ---
 
@@ -377,16 +382,19 @@ codebeacon hook install [path]            # installer merge driver + hook post-c
 codebeacon merge-driver <base> <cur> <other>  # invoqué par git après `hook install` ; union-merge de beacon.json
 
 # Enrichissement AI-sémantique (le LLM est exécuté par l'agent, codebeacon tient la comptabilité)
-codebeacon semantic-prepare [--dir .codebeacon] [--max-tasks N]
-                                          # réapplique l'archive existante au beacon.json frais
-                                          # puis n'émet de tâches que pour les candidats NEUFS
-                                          # (dossiers god-node + cibles non résolues)
+codebeacon semantic-prepare [--dir .codebeacon] [--max-tasks N] [--chunk-size N]
+                                          # réhydrate .codebeacon/semantic/original/*.jsonl sur le
+                                          # nouveau beacon.json + élague les entrées pointant vers
+                                          # des nœuds disparus, puis écrit les nouvelles tâches
+                                          # dans .codebeacon/semantic/pending/chunk_NNN.jsonl
+                                          # (--chunk-size par chunk, défaut 10). task_id inclut un
+                                          # hash de contenu : un fichier modifié est ré-émis.
 codebeacon semantic-apply   [--dir .codebeacon]
-                                          # fusionne .codebeacon/semantic-results.jsonl comme
-                                          # arêtes INFERRED references dans beacon.json,
-                                          # ajoute à l'archive .codebeacon/semantic/original.jsonl,
-                                          # nettoie les fichiers en attente et régénère
-                                          # wiki/obsidian/carte de contexte
+                                          # pour chaque .codebeacon/semantic/results/chunk_NNN.jsonl
+                                          # écrit par l'agent, fusionne les arêtes INFERRED references
+                                          # dans beacon.json et DÉPLACE le chunk pending vers
+                                          # .codebeacon/semantic/original/chunk_NNN.jsonl (archive
+                                          # durable). Supprime les résultats, régénère tout.
 
 codebeacon serve [--dir .codebeacon]      # serveur MCP (stdio)
 codebeacon install                        # installer le skill Claude Code
@@ -412,22 +420,24 @@ Le CLI lui-même **n'appelle jamais un LLM**. La couche AI-sémantique est inten
 Quand vous invoquez `/codebeacon` dans Claude Code :
 
 1. `scan` / `sync` construit `beacon.json` à partir de l'AST (aucun appel LLM).
-2. `codebeacon semantic-prepare` réapplique l'archive précédente au graphe frais puis écrit `.codebeacon/semantic-tasks.jsonl` contenant **uniquement les nouveaux candidats** — fichiers à score élevé (arêtes vers cibles non résolues + dossiers god-node) qui n'ont jamais été traités.
-3. Le skill itère sur le fichier de tâches. Pour chaque ligne, l'agent (en utilisant le modèle de sa session courante) lit le champ `excerpt` et renvoie inline les références inférées. Les résultats sont écrits dans `.codebeacon/semantic-results.jsonl`.
-4. `codebeacon semantic-apply` fusionne les résultats en arêtes `INFERRED references` dans `beacon.json`, **les ajoute à `.codebeacon/semantic/original.jsonl`** (l'archive durable), nettoie les fichiers en attente et régénère wiki + obsidian + carte de contexte.
-5. Au prochain scan : `semantic-prepare` réhydrate l'archive sur le graphe fraîchement construit (pour que les inférences historiques ne disparaissent pas lors d'un re-scan) et n'émet dans le fichier de tâches que **les candidats nouvellement découverts** depuis la dernière mise à jour de l'archive. Les fichiers déjà traités sont sautés via `task_id` (SHA1 de `file_path|node_id`).
+2. `codebeacon semantic-prepare` réhydrate l'archive sous `.codebeacon/semantic/original/*.jsonl` sur le graphe frais et **élague** les entrées dont le nœud source a disparu. Il écrit ensuite les nouvelles tâches dans `.codebeacon/semantic/pending/chunk_NNN.jsonl` (≤ `--chunk-size` par fichier, défaut 10). La numérotation des chunks reprend là où l'archive durable s'est arrêtée — pas de collision possible.
+3. Le skill itère les chunks pending **un par un**. Pour chaque `pending/chunk_NNN.jsonl`, l'agent (avec le modèle de sa session courante) lit l'`excerpt` de chaque tâche et écrit un `semantic/results/chunk_NNN.jsonl` du même nom.
+4. `codebeacon semantic-apply` fusionne les résultats en arêtes `INFERRED references` dans `beacon.json` et **déplace** chaque `pending/chunk_NNN.jsonl` terminé vers **`semantic/original/chunk_NNN.jsonl`** (les arêtes appliquées y sont incluses pour auditabilité). Les fichiers de résultats sont supprimés ; wiki + obsidian + carte de contexte sont régénérés.
+5. Au prochain scan : `semantic-prepare` lit chaque chunk sous `original/`, applique ses arêtes au graphe fraîchement construit (les inférences historiques sont conservées) et saute toute tâche dont le `task_id` est déjà archivé. `task_id` = `SHA1(file_path | node_id | excerpt_hash[:8])` — si le contenu sémantique d'un fichier change, il obtient un nouvel id et est ré-analysé.
 
-Vous obtenez ainsi un enrichissement incrémental et idempotent : l'agent ne réanalyse jamais deux fois le même fichier et le signal AI accumulé survit à chaque re-scan.
+Enrichissement incrémental et idempotent : l'agent ne ré-analyse jamais deux fois la même combinaison (fichier, contenu), le signal AI accumulé survit à chaque re-scan et les chunks gardent l'ensemble de travail de l'agent petit.
 
 ### Utilisation directe du CLI
 
-Si vous n'utilisez pas le skill (par ex. en CI), vous pouvez piloter les deux mêmes commandes manuellement et fournir votre propre `semantic-results.jsonl` :
+Si vous n'utilisez pas le skill (par ex. en CI), vous pouvez piloter les deux mêmes commandes manuellement et fournir vos propres `results/chunk_NNN.jsonl` :
 
 ```bash
 codebeacon scan .
-codebeacon semantic-prepare --dir .codebeacon --max-tasks 50
+codebeacon semantic-prepare --dir .codebeacon --max-tasks 50 --chunk-size 10
 
-# écrivez vous-même .codebeacon/semantic-results.jsonl ; chaque ligne :
+# .codebeacon/semantic/pending/chunk_001.jsonl ... existent.
+# Pour chaque chunk pending, écrivez un results/chunk_NNN.jsonl du même nom.
+# Chaque ligne :
 #   {"task_id":"...", "source_node_id":"...", "edges":[
 #     {"target_name":"UserService","relation":"references","confidence_score":0.7}
 #   ]}

{codebeacon-0.3.3 → codebeacon-0.5.0}/README.ja.md

@@ -56,6 +56,11 @@ AI コーディングセッションを新しく開くたびに、アシスタ
 - **ゼロ設定** — フレームワークと言語を自動検出；繰り返し実行のために `codebeacon.yaml` を自動生成
 - **ディープダイブモード** — `--deep-dive` で各サブプロジェクトに専用の `.codebeacon/` + `CLAUDE.md` を生成；**どのサブプロジェクトからでも**更新コマンドを実行するだけでワークスペース全体が自動同期
 - **ワークスペース自動再検出** — `scan`/`sync` 実行のたびにワークスペースを再スキャンし、`codebeacon.yaml` に未登録の新規プロジェクトを自動追加してから抽出を開始するため、新しく追加されたサブプロジェクトが見落とされることがない；yaml を手動で管理している場合は `--no-rediscover` でオプトアウト可能
+- **Graphify 風のセマンティック強化** — AST 抽出後、スキルがチャンクごとに 1 つのサブエージェントを並列でディスパッチし、`{nodes, edges, hyperedges}` のフル知識グラフ断片を抽出。関係 8 種（`calls`/`implements`/`references`/`cites`/`conceptually_related_to`/`shares_data_with`/`semantically_similar_to`/`rationale_for`）+ 信頼度 3 段階（EXTRACTED/INFERRED/AMBIGUOUS）をサポート。Claude Code ではサブエージェントがホストモデルより 1 段階下（Opus→Sonnet、Sonnet→Haiku）に自動ダウングレードされ、コーパスサイズに比例したコストを維持。コードノードは AST が担当し、LLM は `concept`/`document`/`paper` ノードのみ寄与可能。既存の 0.3.x アーカイブは新スキーマで透過的にリプレイされる
+- **ナレッジモード (`codebeacon knowledge`)** — マークダウンノート（ADR、議事録、ふりかえり、仕様、リサーチ）をスキャンし、`.codebeacon/` の隣に単一の `KNOWLEDGE.md` を生成。ファイル名・見出しパターンで自動分類、Obsidian の YAML frontmatter と `[[backlinks]]` をパースし、最上部に「Key Decisions」+「Open Questions」のロールアップを提示することで、コードベースが*なぜ*このような形になっているのかをエージェントに伝える。ヒューリスティックのみで LLM 呼び出しなし
+- **パス省略形** — `codebeacon ./src` が `codebeacon scan ./src` と等価に。先頭引数が登録済みサブコマンドでない場合は `scan` が自動注入されるため、`graphify <path>` / `codesight <path>` の操作感もそのまま使える
+- **強化された semantic パイプライン** — `semantic-apply` がエージェント JSONL の不正行（null/リスト/code-fence/必須フィールド欠落）をガードし、壊れた `confidence_score`（None/NaN/文字列/範囲外）を安全なデフォルトに coerce、merge 直前に `beacon.json` → `beacon.json.bak` をスナップショットして AST ベースラインを常に復元可能にし、`beacon.html`/`callflow.html` も再生成して新たに推論されたエッジが可視化に反映される
+- **機密ファイル・ディレクトリのガード** — `secrets/`、`credentials/`、`.ssh/`、`.aws/`、`.gnupg/` を常にスキップ。credential パターン（`api_token`、`oauth_token`、`private_key`、`client_secret`; アンダースコア*と*ハイフン両方の変種）に一致するファイル名は、抽出器に到達する前にコレクタ段階で除外
 
 ---
 
@@ -285,17 +290,19 @@ codebeacon hook install [path]            # merge driver + post-commit インク
 codebeacon merge-driver <base> <cur> <other>  # `hook install` 後 git が呼び出す；beacon.json を union マージ
 
 # AI-セマンティック補強 (LLM はエージェント、整合性管理は codebeacon)
-codebeacon semantic-prepare [--dir .codebeacon] [--max-tasks N]
-                                          # 過去のアーカイブを fresh beacon.json に再適用後、
-                                          # 未処理の NEW 候補 (god-node フォルダ + unresolved
-                                          # ターゲット) のみを .codebeacon/semantic-tasks.jsonl
-                                          # に書き出す
+codebeacon semantic-prepare [--dir .codebeacon] [--max-tasks N] [--chunk-size N]
+                                          # .codebeacon/semantic/original/*.jsonl アーカイブを fresh
+                                          # beacon.json に再適用 + 失われたノードを指す stale エントリ
+                                          # を prune し、新規候補のみを .codebeacon/semantic/pending/
+                                          # chunk_NNN.jsonl に書き出す (chunk あたり --chunk-size 件、
+                                          # 既定 10)。task_id にコンテンツハッシュが入っているので、
+                                          # ファイル内容が変わると自動で再発行される。
 codebeacon semantic-apply   [--dir .codebeacon]
-                                          # .codebeacon/semantic-results.jsonl を INFERRED
-                                          # references エッジとして beacon.json に統合し、
-                                          # .codebeacon/semantic/original.jsonl アーカイブに
-                                          # 追記、pending ファイルを掃除し、
-                                          # wiki/obsidian/コンテキストマップを再生成
+                                          # エージェントが書いた .codebeacon/semantic/results/
+                                          # chunk_NNN.jsonl をそれぞれ INFERRED references エッジ
+                                          # として beacon.json にマージし、pending/chunk_NNN.jsonl
+                                          # を original/chunk_NNN.jsonl に移動 (永続アーカイブ)。
+                                          # results は削除、wiki/obsidian/コンテキストマップを再生成。
 
 # インテグレーション
 codebeacon serve [--dir .codebeacon]      # MCP サーバー起動 (stdio)
@@ -322,22 +329,23 @@ CLI 自体は LLM API 呼び出しを **行いません**。AI-セマンティ
 Claude Code で `/codebeacon` を呼び出すと：
 
 1. `scan` / `sync` が AST から `beacon.json` を構築（LLM 呼び出しなし）。
-2. `codebeacon semantic-prepare` が過去のアーカイブを新しいグラフに再適用後、**新しい候補のみ**を含む `.codebeacon/semantic-tasks.jsonl` を書き出します — スコアが高い（unresolved ターゲットエッジ + god-node フォルダ）かつ一度も処理されたことのないファイル。
-3. スキルが tasks ファイルを順次処理。各行についてエージェント（現在セッションのモデル）が `excerpt` フィールドを読み、推論された references をインラインで返します。結果は `.codebeacon/semantic-results.jsonl` に書き込まれます。
-4. `codebeacon semantic-apply` が結果を `INFERRED references` エッジとして `beacon.json` にマージし、**`.codebeacon/semantic/original.jsonl`**（永続アーカイブ）に追記、pending ファイルを掃除、wiki + obsidian + コンテキストマップを再生成します。
-5. 次回スキャン時：`semantic-prepare` がアーカイブを新グラフに再適用（再スキャンで過去の推論が失われないように）し、最後のアーカイブ以降の**新しく発見された候補のみ**を tasks ファイルに含めます。処理済みファイルは `task_id`（SHA1 of `file_path|node_id`）でスキップ。
+2. `codebeacon semantic-prepare` が `.codebeacon/semantic/original/*.jsonl` アーカイブを新グラフに再適用し、グラフから消えたノードを指す stale エントリを **prune**。続いて新規 task を `.codebeacon/semantic/pending/chunk_NNN.jsonl` に書き出す（`--chunk-size` 単位、既定 10）。chunk 番号は永続アーカイブの続きから始まるため衝突しません。
+3. スキルは pending chunk を**1 つずつ**処理。各 `pending/chunk_NNN.jsonl` について、エージェント（現在セッションのモデル）が task の `excerpt` を読み、同名の `semantic/results/chunk_NNN.jsonl` を書きます。
+4. `codebeacon semantic-apply` が結果を `INFERRED references` エッジとして `beacon.json` にマージし、完了済み `pending/chunk_NNN.jsonl` を **`semantic/original/chunk_NNN.jsonl`** に**移動**（適用済みエッジを一緒に記録）。results は削除、wiki + obsidian + コンテキストマップを再生成。
+5. 次回スキャン時：`semantic-prepare` が `original/` の全 chunk のエッジを新グラフに再適用（過去の推論を保全）し、既に処理済みの `task_id` はスキップ。`task_id` = `SHA1(file_path | node_id | excerpt_hash[:8])` — ファイルのセマンティック内容が変われば自動的に新しい id になり再解析されます。
 
-→ 増分かつ冪等の補強。同じファイルを二度分析せず、蓄積された AI シグナルは毎回の再スキャンを生き延びます。
+→ 増分かつ冪等の補強。同じ (ファイル, 内容) を二度分析せず、蓄積された AI シグナルは毎回の再スキャンを生き延び、chunk 分割でエージェントの作業セットも小さく保てます。
 
 ### 直接 CLI 使用
 
-スキルを介さず（例：CI）に同じ 2 コマンドで手動運用し、`semantic-results.jsonl` を自分で書くこともできます：
+スキルを介さず（例：CI）に同じ 2 コマンドで手動運用し、`results/chunk_NNN.jsonl` を自分で書くこともできます：
 
 ```bash
 codebeacon scan .
-codebeacon semantic-prepare --dir .codebeacon --max-tasks 50
+codebeacon semantic-prepare --dir .codebeacon --max-tasks 50 --chunk-size 10
 
-# 次に .codebeacon/semantic-results.jsonl を自分で書く；各行：
+# .codebeacon/semantic/pending/chunk_001.jsonl ... が生成される。
+# 各 pending chunk について同名の results/chunk_NNN.jsonl を書く。各行：
 #   {"task_id":"...", "source_node_id":"...", "edges":[
 #     {"target_name":"UserService","relation":"references","confidence_score":0.7}
 #   ]}

{codebeacon-0.3.3 → codebeacon-0.5.0}/README.ko.md

@@ -56,6 +56,11 @@ AI 코딩 세션을 새로 열 때마다 어시스턴트는 백지 상태에서
 - **제로 설정** — 프레임워크와 언어 자동 감지; 반복 실행을 위한 `codebeacon.yaml` 자동 생성
 - **딥다이브 모드** — `--deep-dive`는 각 서브 프로젝트에 개별 `.codebeacon/` + `CLAUDE.md`를 생성; 어느 서브 프로젝트 폴더에서든 `codebeacon scan . --update`를 실행하면 워크스페이스의 모든 프로젝트가 자동으로 업데이트됨
 - **워크스페이스 자동 재발견** — `scan`/`sync` 실행마다 워크스페이스를 다시 훑어 `codebeacon.yaml`에 없는 신규 프로젝트를 자동으로 yaml에 추가한 뒤 추출 시작 — 새로 추가된 서브 프로젝트가 조용히 누락되지 않음; 수동으로 yaml을 큐레이션 중이라면 `--no-rediscover`로 옵트아웃
+- **Graphify 스타일 semantic 보강** — AST 추출 후 스킬이 청크당 subagent 1개를 병렬로 띄워 `{nodes, edges, hyperedges}` 풀 그래프 단편을 추출. 관계 8종(`calls`/`implements`/`references`/`cites`/`conceptually_related_to`/`shares_data_with`/`semantically_similar_to`/`rationale_for`) + 신뢰도 3단계(EXTRACTED/INFERRED/AMBIGUOUS) 지원. Claude Code에서는 subagent가 호스트 모델보다 한 단계 아래(Opus→Sonnet, Sonnet→Haiku)로 자동 강등되어 코퍼스 크기에 비례한 비용 유지. 코드 노드는 AST 전담, LLM은 `concept`/`document`/`paper` 노드만 기여 가능. 기존 0.3.x 아카이브는 새 스키마로 그대로 replay됨
+- **지식 모드 (`codebeacon knowledge`)** — 마크다운 노트(ADR, 회의록, 회고, 스펙, 리서치)를 스캔해서 `.codebeacon/` 옆에 단일 `KNOWLEDGE.md` 생성. 파일명·제목 패턴으로 자동 분류, Obsidian YAML frontmatter와 `[[backlinks]]` 파싱, 최상단에 "Key Decisions" + "Open Questions" 롤업을 제공해 코드베이스가 *왜* 이런 모습인지 에이전트에게 전달. 휴리스틱만 사용 — LLM 호출 없음
+- **경로 단축 입력** — `codebeacon ./src`가 이제 `codebeacon scan ./src`와 동일. 첫 인자가 등록된 서브커맨드가 아니면 `scan`이 자동 주입되어, `graphify <path>` / `codesight <path>` 머슬 메모리도 그대로 동작
+- **강화된 semantic 파이프라인** — `semantic-apply`가 agent JSONL의 비정상 라인(null/리스트/code-fence/필수 필드 누락)을 가드, 잘못된 `confidence_score`(None/NaN/문자열/범위 초과)를 안전 기본값으로 coerce, merge 직전 `beacon.json` → `beacon.json.bak` 스냅샷으로 AST 베이스라인 복구 가능 보장, `beacon.html`/`callflow.html`도 재생성해서 새 inferred 엣지가 시각화에 반영됨
+- **민감 파일·디렉토리 가드** — `secrets/`, `credentials/`, `.ssh/`, `.aws/`, `.gnupg/` 디렉토리는 항상 스킵. credential 패턴(`api_token`, `oauth_token`, `private_key`, `client_secret`; 언더스코어 *및* 하이픈 변형) 파일명은 추출기에 도달하기 전 수집 단계에서 제외
 
 ---
 
@@ -143,11 +148,14 @@ project-root/
         components/<Name>.md
     obsidian/            ← Obsidian 볼트 (그래프 노드당 노트 1개)
     semantic/
-      original.jsonl     ← 적용된 모든 AI-시맨틱 결과의 영구 아카이브
-                           (재스캔 시 스킵됨, 다시 task 로 발행되지 않음)
-    semantic-tasks.jsonl     ← pending AI-시맨틱 배치
-                               (`semantic-prepare` 와 `semantic-apply` 사이에만 존재)
-    semantic-results.jsonl   ← 에이전트가 작성한 결과 (동일 라이프사이클)
+      pending/           ← prepare 가 chunk_NNN.jsonl 작성 (chunk 당 --chunk-size 개)
+        chunk_001.jsonl
+        chunk_002.jsonl
+      results/           ← 에이전트가 같은 이름의 chunk_NNN.jsonl 작성
+        chunk_001.jsonl
+      original/          ← apply 가 완료 chunk 를 이동 (영구 아카이브)
+        chunk_001.jsonl
+        chunk_002.jsonl  ← (과거 실행 분이 누적; chunk 번호는 monotonic)
 ```
 
 ### 딥다이브 모드
@@ -314,15 +322,20 @@ codebeacon sync --config <file>           # 특정 설정 파일 사용
 codebeacon sync --no-rediscover           # 신규 프로젝트 자동 추가 비활성화 (수동 큐레이션 모드)
 
 # AI-시맨틱 보강 (LLM 작업은 에이전트가, 부기는 codebeacon이 담당)
-codebeacon semantic-prepare [--dir .codebeacon] [--max-tasks N]
-                                          # 시맨틱 아카이브를 fresh beacon.json에 재적용 후,
-                                          # 아카이브에 없는 NEW 후보(god-node 폴더 + unresolved 타겟)
-                                          # 만 골라 .codebeacon/semantic-tasks.jsonl 작성
+codebeacon semantic-prepare [--dir .codebeacon] [--max-tasks N] [--chunk-size N]
+                                          # .codebeacon/semantic/original/*.jsonl 아카이브를 fresh
+                                          # beacon.json 에 재적용 + 사라진 노드를 가리키는 stale 엔트리
+                                          # prune, 그 후 **모든** NEW 후보 (god 폴더 + hub file +
+                                          # unresolved 타겟) 를 .codebeacon/semantic/pending/
+                                          # chunk_NNN.jsonl 로 작성 (chunk 당 --chunk-size 개, 기본 10).
+                                          # --max-tasks 는 선택적 cap (0 = no cap, 기본 — 모두 emit).
+                                          # task_id 에 콘텐츠 해시가 포함되어 파일 내용이 바뀌면 자동 재발행.
 codebeacon semantic-apply   [--dir .codebeacon]
-                                          # .codebeacon/semantic-results.jsonl 을 읽어
-                                          # INFERRED references 엣지로 beacon.json 에 머지,
-                                          # .codebeacon/semantic/original.jsonl 아카이브에 적재,
-                                          # pending 파일 정리, wiki/obsidian/컨텍스트 맵 재생성
+                                          # 에이전트가 작성한 .codebeacon/semantic/results/
+                                          # chunk_NNN.jsonl 각각을 INFERRED references 엣지로
+                                          # beacon.json 에 머지 + pending/chunk_NNN.jsonl 을
+                                          # original/chunk_NNN.jsonl 로 이동 (영구 아카이브).
+                                          # results 파일 삭제, wiki/obsidian/컨텍스트 맵 재생성.
 
 # 지식 그래프 쿼리
 codebeacon query <term> [--dir .codebeacon] [--limit N]   # 라벨 부분 문자열로 노드 검색
@@ -357,22 +370,23 @@ CLI 자체는 LLM API 호출을 **하지 않습니다**. AI-시맨틱 계층은
 Claude Code 에서 `/codebeacon` 호출 시:
 
 1. `scan` / `sync` 가 AST 로부터 `beacon.json` 빌드 (LLM 호출 없음).
-2. `codebeacon semantic-prepare` 가 이전 아카이브를 새 그래프에 재적용한 뒤, **신규 후보만** 담긴 `.codebeacon/semantic-tasks.jsonl` 작성 — 점수가 높은 파일 (unresolved 타겟 엣지 + god-node 폴더) 중 한 번도 처리된 적 없는 것.
-3. 스킬이 tasks 파일을 순회합니다. 각 라인마다 에이전트(현재 세션의 모델)가 `excerpt` 필드를 읽고 추론된 references 를 인라인으로 반환. 결과는 `.codebeacon/semantic-results.jsonl` 에 기록.
-4. `codebeacon semantic-apply` 가 결과를 `INFERRED references` 엣지로 `beacon.json` 에 머지하고, **`.codebeacon/semantic/original.jsonl`** (영구 아카이브) 에 append, pending 파일 정리, wiki + obsidian + 컨텍스트 맵 재생성.
-5. 다음 스캔: `semantic-prepare` 가 아카이브를 새 그래프에 재적용 (재스캔으로 인해 과거 추론이 사라지지 않도록) 한 뒤, 마지막 아카이브 이후 **새로 발견된 후보만** tasks 파일에 담음. 이미 처리된 파일은 `task_id` (SHA1(`file_path|node_id`)) 로 스킵.
+2. `codebeacon semantic-prepare` 가 `.codebeacon/semantic/original/*.jsonl` 아카이브를 새 그래프에 재적용하고, 그래프에서 사라진 노드를 가리키는 stale 엔트리를 **prune** 한 뒤, 신규 task 들을 `.codebeacon/semantic/pending/chunk_NNN.jsonl` 로 작성 (`--chunk-size` 당 1 chunk, 기본 10). chunk 번호는 영구 아카이브의 다음 번호부터 시작 — 절대 충돌하지 않음.
+3. 스킬이 pending chunk 들을 **한 번에 하나씩** 처리. 각 `pending/chunk_NNN.jsonl` 에 대해 에이전트(현재 세션의 모델)가 각 task 의 `excerpt` 를 읽고 같은 이름의 `semantic/results/chunk_NNN.jsonl` 을 작성.
+4. `codebeacon semantic-apply` 가 결과를 `INFERRED references` 엣지로 `beacon.json` 에 머지하고, 각 완료된 `pending/chunk_NNN.jsonl` 을 **`semantic/original/chunk_NNN.jsonl`** 로 **이동** (적용된 엣지를 함께 적재, 감사 가능). results 파일은 삭제, wiki + obsidian + 컨텍스트 맵 재생성.
+5. 다음 스캔: `semantic-prepare` 가 `original/` 의 모든 chunk 엣지를 새 그래프에 재적용 (과거 추론 보존) 하고, 이미 처리된 task_id 는 스킵. `task_id` = `SHA1(file_path | node_id | excerpt_hash[:8])` — 파일 시맨틱 내용이 바뀌면 자동으로 새 id 가 되어 재분석.
 
-→ 증분 + 멱등 보강. 같은 파일을 두 번 분석하지 않고, 누적된 AI 시그널은 매 재스캔을 살아남습니다.
+→ 증분 + 멱등 보강. 같은 (파일, 내용) 조합을 두 번 분석하지 않고, 누적된 AI 시그널은 매 재스캔을 살아남으며 chunk 분할로 에이전트의 working set 도 작게 유지됩니다.
 
 ### 직접 CLI 사용
 
-스킬 없이 (예: CI) 같은 두 명령으로 직접 운영하고 `semantic-results.jsonl` 을 본인이 채울 수 있습니다:
+스킬 없이 (예: CI) 같은 두 명령을 직접 운영할 수 있습니다 — `results/chunk_NNN.jsonl` 파일들을 본인이 채우면 됩니다:
 
 ```bash
 codebeacon scan .
-codebeacon semantic-prepare --dir .codebeacon --max-tasks 50
+codebeacon semantic-prepare --dir .codebeacon --max-tasks 50 --chunk-size 10
 
-# 이제 .codebeacon/semantic-results.jsonl 을 직접 작성; 각 라인:
+# .codebeacon/semantic/pending/chunk_001.jsonl ... 이 생성됨.
+# 각 pending chunk 에 대해 같은 이름의 results/chunk_NNN.jsonl 을 작성. 각 라인:
 #   {"task_id":"...", "source_node_id":"...", "edges":[
 #     {"target_name":"UserService","relation":"references","confidence_score":0.7}
 #   ]}