Skip to content
Merged
82 changes: 14 additions & 68 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -584,66 +584,20 @@ verify-bindings, migrate`.

## CRITICAL: Code Search Policy

**NEVER use grep/glob for code search. ALWAYS use pmat query.**

### Decision Tree

| Task | Command |
|------|---------|
| Find functions by intent | `pmat query "error handling" --limit 10` |
| Find important functions | `pmat query "mcp" --rank-by pagerank --limit 5` |
| Find most-called utilities | `pmat query "format" --rank-by indegree --limit 5` |
| Find in specific path | `pmat query "validate" --path src/api/` |
| Find high-quality code only | `pmat query "parse" --min-grade B --max-complexity 15` |

### Examples

```text
# BAD - Raw text search returns 500+ noisy matches with no context
# GOOD - Semantic search returns 10 ranked functions with quality metrics
pmat query "error handling" --limit 10
```

### Cross-Project Search

The index automatically includes sibling projects (aprender, trueno, realizar).
Query from any project to search 60k+ functions across all three codebases.
**NEVER use grep/glob for code search. ALWAYS use `pmat query`.** The full decision tree, enrichment flags
(`-G`, `--churn`, `--duplicates`, `--entropy`, `--faults`), search modes (`--regex`, `--literal`) and coverage-gap
workflow are in the author-local `~/.claude/CLAUDE.md`; the commands every contributor needs are kept here, plus the coverage + contracts rule below.

```text
# Build index in each project first (one-time setup)
cd ~/src/aprender && pmat query "init" --rebuild-index --limit 1
cd ~/src/trueno && pmat query "init" --rebuild-index --limit 1
cd ~/src/realizar && pmat query "init" --rebuild-index --limit 1

# Now query from any project - siblings auto-merge
pmat query "matrix multiplication" --limit 5
```

### Output Formats

- Default (text): Human-readable with signatures and metrics
- `--format json`: For parsing/scripting
- `--format markdown`: For documentation
- `--include-source`: Include full source code in results

### Quick Reference

```text
pmat query "<intent>" # Basic search
pmat query "<intent>" --rank-by pagerank # Most important functions
pmat query "<intent>" --format json # Machine-readable
pmat query "<intent>" --include-source # Include full source code
pmat query "<intent>" --exclude-tests # Skip test functions

# Git history search (find code by commit intent via RRF fusion)
pmat query "fix serialization" -G
pmat query "apr format" --git-history

# Enrichment flags (combine freely)
pmat query "ml algorithm" --churn # git volatility (commit count, churn score)
pmat query "tensor operation" --duplicates # code clone detection (MinHash+LSH)
pmat query "loss function" --entropy # pattern diversity (repetitive vs unique)
pmat query "model training" --churn --duplicates --entropy --faults -G # full audit
pmat query "<intent>" --limit 10 --include-source # semantic search with quality annotations
pmat query "<intent>" --rank-by pagerank # most important functions
pmat query "<intent>" --rank-by indegree # most-called utilities
pmat query "<intent>" --path src/api/ # restrict to a path
pmat query "<intent>" --format json # or markdown; default is text
pmat query "<intent>" --min-grade B --max-complexity 15 --exclude-tests
pmat query "<intent>" -G # fuse git-history intent (also --churn --duplicates --entropy --faults)
# Siblings (aprender, trueno, realizar; 60k+ functions) auto-merge into the index; build once per project:
pmat query "init" --rebuild-index --limit 1
```

### Coverage-Guided Search (pmat 3.0.0+)
Expand Down Expand Up @@ -687,15 +641,7 @@ batuta oracle --rag-index # Reindex (the command prints the do

Use proactively for trueno SIMD patterns, cross-language equivalents, and stack best practices.

## SSC Training Infrastructure Status (snapshot 2026-03-22 — STALE, re-verify before acting)

This block has not been re-measured in ~5 months and one of its premises no longer
holds: it points at "trueno 0.4.36" as an external crate, but since APR-MONO trueno is
in-tree as `crates/aprender-compute` and has no independent version to wait on.
## SSC Training Infrastructure Status (snapshot 2026-03-22 — STALE, re-verify before acting)

- **SSC canary eval**: 90% accuracy, SHIP gate PASS — classifier ready to ship
- **entrenar cuBLAS integration**: GEMM parity verified between CPU and GPU paths
- **Blackwell (GB10) training**: Blocked by JIT pre-warming bug in custom PTX kernels. Must use fused NF4 kernel path until trueno 0.4.36 ships with pre-compiled kernels
- **apr-cli inference NOT affected**: `apr run` / `apr serve` use cuBLAS (GPU) or trueno SIMD (CPU) — pre-compiled, no custom PTX involved
- **Trained model (LoRA adapter)**: Architecture-independent safetensors — works on any GPU or CPU via standard PEFT loading
- **Key tickets**: trueno#200 (Blackwell JIT), trueno#203 (pre-compiled kernels), entrenar#300 (cuBLAS backward)
Moved to `docs/ssc-training-status-2026-03-22.md` (a 2026-03-22 snapshot, stale; re-verify before acting).
2 changes: 1 addition & 1 deletion contracts/contracts.nt
Original file line number Diff line number Diff line change
Expand Up @@ -23382,7 +23382,6 @@
<https://ont.paiml.dev/v1alpha1/llm/claude-md> <https://ont.paiml.dev/v1alpha1/llm/referencedPath> "crates/"^^<http://www.w3.org/2001/XMLSchema#string> .
<https://ont.paiml.dev/v1alpha1/llm/claude-md> <https://ont.paiml.dev/v1alpha1/llm/referencedPath> "crates/apr-cli/"^^<http://www.w3.org/2001/XMLSchema#string> .
<https://ont.paiml.dev/v1alpha1/llm/claude-md> <https://ont.paiml.dev/v1alpha1/llm/referencedPath> "crates/apr-cli/Cargo.toml"^^<http://www.w3.org/2001/XMLSchema#string> .
<https://ont.paiml.dev/v1alpha1/llm/claude-md> <https://ont.paiml.dev/v1alpha1/llm/referencedPath> "crates/aprender-compute"^^<http://www.w3.org/2001/XMLSchema#string> .
<https://ont.paiml.dev/v1alpha1/llm/claude-md> <https://ont.paiml.dev/v1alpha1/llm/referencedPath> "crates/aprender-compute/"^^<http://www.w3.org/2001/XMLSchema#string> .
<https://ont.paiml.dev/v1alpha1/llm/claude-md> <https://ont.paiml.dev/v1alpha1/llm/referencedPath> "crates/aprender-contracts-cli/"^^<http://www.w3.org/2001/XMLSchema#string> .
<https://ont.paiml.dev/v1alpha1/llm/claude-md> <https://ont.paiml.dev/v1alpha1/llm/referencedPath> "crates/aprender-contracts-macros/"^^<http://www.w3.org/2001/XMLSchema#string> .
Expand All @@ -23407,6 +23406,7 @@
<https://ont.paiml.dev/v1alpha1/llm/claude-md> <https://ont.paiml.dev/v1alpha1/llm/referencedPath> "crates/aprender-train/"^^<http://www.w3.org/2001/XMLSchema#string> .
<https://ont.paiml.dev/v1alpha1/llm/claude-md> <https://ont.paiml.dev/v1alpha1/llm/referencedPath> "docs/BEATS.md"^^<http://www.w3.org/2001/XMLSchema#string> .
<https://ont.paiml.dev/v1alpha1/llm/claude-md> <https://ont.paiml.dev/v1alpha1/llm/referencedPath> "docs/specifications/aprender-monorepo-consolidation.md"^^<http://www.w3.org/2001/XMLSchema#string> .
<https://ont.paiml.dev/v1alpha1/llm/claude-md> <https://ont.paiml.dev/v1alpha1/llm/referencedPath> "docs/ssc-training-status-2026-03-22.md"^^<http://www.w3.org/2001/XMLSchema#string> .
<https://ont.paiml.dev/v1alpha1/llm/claude-md> <https://ont.paiml.dev/v1alpha1/llm/referencedPath> "scripts/apr_bin.sh"^^<http://www.w3.org/2001/XMLSchema#string> .
<https://ont.paiml.dev/v1alpha1/llm/claude-md> <https://ont.paiml.dev/v1alpha1/llm/referencedPath> "scripts/bump-version.sh"^^<http://www.w3.org/2001/XMLSchema#string> .
<https://ont.paiml.dev/v1alpha1/llm/claude-md> <https://ont.paiml.dev/v1alpha1/llm/referencedPath> "scripts/check_clippy_current_stable.sh"^^<http://www.w3.org/2001/XMLSchema#string> .
Expand Down
14 changes: 14 additions & 0 deletions docs/ssc-training-status-2026-03-22.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
# SSC training infrastructure status (snapshot 2026-03-22, STALE)

Moved out of CLAUDE.md in the 2026-10-16 context trim. Re-verify before acting.

This block has not been re-measured in ~5 months and one of its premises no longer
holds: it points at "trueno 0.4.36" as an external crate, but since APR-MONO trueno is
in-tree as `crates/aprender-compute` and has no independent version to wait on.

- **SSC canary eval**: 90% accuracy, SHIP gate PASS — classifier ready to ship
- **entrenar cuBLAS integration**: GEMM parity verified between CPU and GPU paths
- **Blackwell (GB10) training**: Blocked by JIT pre-warming bug in custom PTX kernels. Must use fused NF4 kernel path until trueno 0.4.36 ships with pre-compiled kernels
- **apr-cli inference NOT affected**: `apr run` / `apr serve` use cuBLAS (GPU) or trueno SIMD (CPU) — pre-compiled, no custom PTX involved
- **Trained model (LoRA adapter)**: Architecture-independent safetensors — works on any GPU or CPU via standard PEFT loading
- **Key tickets**: trueno#200 (Blackwell JIT), trueno#203 (pre-compiled kernels), entrenar#300 (cuBLAS backward)
Loading