Kg Sync

Future repos (foundation-PLR, any research repo) can use the same Skill with their own scanner + experiment tracker.

7-Step Workflow

1. SCAN-CODE   →  ast.parse() scan of src/ → code-structure/*.yaml
2. SCAN-EXP    →  DuckDB query over mlruns/ → experiments/*.yaml
2b. PROPAGATE  →  Check _network.yaml propagation: for modified nodes → requires_review flags
3. STAMP       →  Write _generated_at.yaml (git commit hash + timestamp)
4. STALENESS   →  check_projection_staleness.py → stale file report
5. GENERATE    →  Render stale projections via Jinja2 templates/*.j2 → .tex files
6. VALIDATE    →  (a) Schema check (b) Idempotency (c) pdflatex compile
7. EXPORT      →  If --export-to: atomic copy to sci-llm-writer kg-snapshot/

Step-by-Step Reference

Step 1: SCAN-CODE

uv run python scripts/scan_code_structure.py \
  --source-dir src/minivess/ \
  --output-dir knowledge-graph/code-structure/

What it does:

• ast.parse() all .py files in src/minivess/ (CLAUDE.md Rule #16 — no regex)
• Extracts: @flow decorated functions, ModelAdapter subclasses, Hydra config nodes, test markers
• Writes: flows.yaml, adapters.yaml, config-schema.yaml, test-coverage.yaml
• FALLBACK: if ast.parse() fails on a file → log warning, skip file, continue

Step 2: SCAN-EXP

uv run python scripts/scan_experiments.py \
  --mlruns-dir mlruns/ \
  --output-dir knowledge-graph/experiments/

What it does:

• DuckDB analytics query over mlruns/ (already in src/minivess/observability/analytics.py)
• Extracts FINISHED runs only — FAILED/KILLED runs are excluded
• Writes: one YAML per experiment name + current_best.yaml
• MISSING RESULTS: if SAM3/VesselFM absent → insert {status: "PENDING", reason: "GPU runs not complete"}
• HARD ERROR: run_id in existing YAML absent from mlruns/ → error, not silent fallback

Step 2b: PROPAGATE

• Parse knowledge-graph/_network.yaml propagation: section
• For each source node with git changes (compare to last _generated_at.yaml commit hash):
  • Find target nodes in propagation section
  • For type=hard/soft: add requires_review: true + review_reason: "parent changed: <id>"
  • For type=signal: log only, no YAML change
• Run scripts/review_prd_integrity.py to validate _network.yaml consistency
• Report propagation tree to user before continuing

Step 3: STAMP

Writes knowledge-graph/code-structure/_generated_at.yaml and knowledge-graph/experiments/_generated_at.yaml:

generated_at: "2026-03-15T10:00:00Z"
git_commit: "<sha>"
git_dirty: false