kb-codeindex

name	kb-codeindex
description	Parse all `# implements:` annotations in source code and emit `library/_code-index.md` as a shelf-index. Also extracts cross-module import edges and writes `library/_dependency-edges.md`. Idempotent — re-running produces byte-identical output if no annotations or imports changed.

Skill: kb-codeindex

Use this skill to build or refresh the project's code index. The output is structurally a KB shelf-index, queryable by the research-librarian agent like the regular library files. Run after adding/changing # implements: annotations or modifying import structure.

Inputs

• (no arguments — operates on the whole project)

Steps

1. Load the project root. Detect from .git/.

2. Walk source files. Glob **/*.{py,js,ts,go,rs,java} excluding standard ignored paths (.venv/, node_modules/, .git/, etc.).

3. Parse annotations. Use parse_code_annotations to extract every # implements: line.

4. Verify cited IDs. For each citation, look it up in library/_ids.md. Report unresolved citations as warnings (not errors — annotation_format_integrity blocks at pre-push).

5. Render the index. Use render_code_index to produce shelf-index-shaped markdown.

6. Write to library/_code-index.md. If the file already exists, compare byte-for-byte; only write if different.

7. Extract dependency edges. For each language detected in the project paths, invoke the registered DependencyExtractor adapter:

   • Python paths → PythonAstExtractor (uses ast.parse for precise cross-module import resolution)
   • All other paths → GenericRegexExtractor (regex-based; configured per language via make_swift_extractor() or equivalent)

   Accumulate all returned ImportEdge objects across languages. Resolve each edge against the Decomposition module paths so edges carry qualified module IDs (e.g. P1.SP1.M1 → P1.SP1.M2). Edges that cannot be resolved to a known module are silently dropped (same policy as unresolved annotation citations).

8. Write to library/_dependency-edges.md. Use render_dependency_edges(edges, library_handle=<library-handle>) to produce the artefact. If the file already exists, compare byte-for-byte; only write if different. The file is consumed by visibility_rule_enforcement during decomposition validation.

9. Report. Print: number of annotations processed, number of unresolved citations, number of import edges extracted, whether either index file changed.

Done criteria

• library/_code-index.md is up to date.
• library/_dependency-edges.md is up to date.
• Idempotent (re-running with no changes produces no diff on either file).
• Unresolved citations and unresolvable edges reported but not failed.