170 added, 1 removed. Audit C to A.
- /Users/tomdimino/.claude/skills/dag-typesafe/SKILL.md
+ ---
+ name: dag-typesafe
+ description: >-
+ Analyze a repository's type system and generate type-safe DAG execution pipelines
+ with GraphSentry-style certificate verification. This skill should be used when
+ building LLM-driven workflows that need deterministic type safety, when composing
+ typed operations into validated execution graphs, or when adding contract-checked
+ pipeline orchestration to any codebase. Supports Python (Pydantic) and TypeScript (Zod).
+ argument-hint: "[analyze|compose|compile|validate|registry] [args...]"
+ ---
+
+ # dag-typesafe
+
+ Deterministic type safety via directed acyclic graphs for reasoning language models.
+
+ Analyze any repo's public API surface, extract a typed node registry, compose validated
+ execution DAGs from natural language, and compile them into native pipeline code with
+ GraphSentry-style `(artifact, certificate)` verification at every node boundary.
+
+ ## Category
+
+ Code Scaffolding & Templates
+
+ ## Core Concepts
+
+ Three layers compose into a single architecture:
+
+ 1. **Typed Node Registry** — the repo's public functions/classes extracted as typed nodes
+ with JSON Schema input/output contracts. The LLM selects from this registry; it never
+ generates arbitrary code.
+
+ 2. **DAG Plan** — a language-neutral execution graph where nodes reference registry entries
+ and edges are schema-validated. No cycles, all inputs satisfied, all types compatible.
+
+ 3. **Certificates** — each node emits an `(artifact, certificate)` pair. Certificates are
+ deterministic predicates evaluated from logged evidence. Failed certificates halt the
+ pipeline with diagnostic context. Based on GraphSentry (Li et al., 2026).
+
+ ## Commands
+
+ Parse `$ARGUMENTS` to determine which command to run:
+
+ ### `analyze`
+
+ Extract a typed node registry from the current repository.
+
+ ```bash
+ python3 ~/.claude/skills/dag-typesafe/scripts/analyze.py [--language python|typescript|auto] [--output dag-registry.json]
+ ```
+
+ 1. Detect repo language(s) from file extensions and config files
+ 2. Run the appropriate extractor(s) from `extractors/`
+ 3. Walk the AST for public API surface only (exported functions, public classes, API endpoints)
+ 4. Convert type annotations to JSON Schema
+ 5. Output `dag-registry.json` at repo root
+
+ ### `compose`
+
+ Generate a DAG plan from natural language using the typed registry.
+
+ The compose phase is **endpoint-agnostic** — it works with any OpenAI-compatible API
+ (OpenRouter, Groq, Subq Code, local models) or in-session via Claude Code.
+
+ **In-session mode (default):** Build a structured prompt from the registry and task
+ description, then use the current Claude Code session to generate the DAG plan.
+
+ **Headless mode:** Set `DAG_LLM_BASE_URL` and `DAG_LLM_API_KEY` environment variables
+ to point at any OpenAI-compatible endpoint.
+
+ ```bash
+ python3 ~/.claude/skills/dag-typesafe/scripts/compose.py "task description" --registry dag-registry.json [--output dag-plan.json] [--provider session|openai]
+ ```
+
+ 1. Load registry from `dag-registry.json`
+ 2. Build structured prompt constraining LLM to node selection and parameterization
+ 3. Generate DAG plan conforming to `schemas/dag-plan.schema.json`
+ 4. Validate the plan (type compatibility, no cycles, all inputs satisfied)
+ 5. Generate certificate predicates for each node
+ 6. Output `dag-plan.json`
+
+ ### `compile`
+
+ Compile a validated DAG plan into native executable code.
+
+ ```bash
+ python3 ~/.claude/skills/dag-typesafe/scripts/compile.py dag-plan.json [--target python|typescript] [--output pipeline.py]
+ ```
+
+ 1. Read validated `dag-plan.json` and `dag-registry.json`
+ 2. Topologically sort nodes
+ 3. Generate native pipeline code via inline code generation
+ 4. Wrap each node call in schema validation (Pydantic `.model_validate()` / Zod `.parse()`)
+ 5. Inject certificate predicate evaluation at every node boundary
+ 6. Output executable pipeline file with zero runtime dependencies beyond standard validation libs
+
+ ### `validate`
+
+ Type-check an existing DAG plan against a registry.
+
+ ```bash
+ python3 ~/.claude/skills/dag-typesafe/scripts/validate.py dag-plan.json --registry dag-registry.json
+ ```
+
+ Checks: cycle detection, edge type compatibility, required input satisfaction, certificate
+ predicate well-formedness, registry reference integrity.
+
+ ### `registry`
+
+ Inspect, filter, and query the typed node registry.
+
+ ```bash
+ python3 ~/.claude/skills/dag-typesafe/scripts/registry.py [--filter "pattern"] [--show-schemas] [--stats]
+ ```
+
+ ## Schemas
+
+ All schemas live in `schemas/` as JSON Schema (draft 2020-12):
+
+ - `dag-plan.schema.json` — DAG plan format (nodes, edges, metadata)
+ - `registry.schema.json` — typed node registry format
+ - `certificate.schema.json` — GraphSentry certificate format
+
+ Read these schemas before generating or validating any DAG artifacts.
+
+ ## Extractors
+
+ Language-specific type extractors in `extractors/`:
+
+ | Extractor | Source Types | Output |
+ |-----------|-------------|--------|
+ | `python_extractor.py` | Pydantic BaseModel, dataclass, TypedDict, function annotations | JSON Schema |
+ | `typescript_extractor.py` | Zod schemas, interfaces, type aliases, function signatures | JSON Schema |
+
+ Each extractor walks the AST, identifies public API surface, and converts type definitions
+ to JSON Schema for the registry. Internal/private symbols are excluded.
+
+ ## Code Generation
+
+ The compiler generates pipeline code inline (no external templates). Both Python and TypeScript
+ targets produce complete executable files with:
+
+ - Certificate/CertificateError classes
+ - Topologically sorted node execution
+ - Per-node certificate emission and predicate evaluation
+ - Predicate expression sandboxing (AST-validated safe subset only)
+
+ ## LLM Provider Configuration
+
+ For headless/CI use, configure via environment variables:
+
+ ```bash
+ export DAG_LLM_BASE_URL="https://openrouter.ai/api/v1" # or Groq, Subq, local
+ export DAG_LLM_API_KEY="your-key"
+ export DAG_LLM_MODEL="anthropic/claude-sonnet-4-20250514" # model identifier
+ ```
+
+ When these are unset, compose mode generates a structured prompt for in-session use.
+
+ ## Research Basis
+
+ This skill synthesizes patterns from:
+
+ - **GraphSentry** (Li et al., 2026) — certificate-driven typed DAGs, contract-checked graph surgery
+ - **ChopChop** (Nagy et al., POPL 2026) — semantic constrained decoding via coinductive realizability
+ - **PlanCompiler** (prnvh, 2026) — LLM confined to typed node registry selection
+ - **PlanAI** (Provos, 2026) — Pydantic-typed DAG orchestration with automatic routing
+ - **Agint** (Chivukula et al., 2025) — type floors (text→data→spec→code) in agentic graph compilation
+
+ Full source list: `references/research-sources.md`
+