predicate-skill 1.2.0

package/skills/predicate/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: predicate
+description: Local reasoning knowledge graph for "why", "what breaks if", and "what's connected to" questions. OWL-backed, provenance-tracked, schema-versioned. Use instead of RAG when the question is structural rather than fuzzy-semantic.
+---
+
+<EXTREMELY-IMPORTANT>
+Do NOT invent predicates. ALWAYS call `kg_explore_schema` before drafting SPARQL.
+If a predicate you need does not exist, call `kg_propose_schema` — never use
+`kg_assert` with a fabricated property name.
+</EXTREMELY-IMPORTANT>
+
+# When to use this skill
+
+Use Predicate when the user asks:
+- **Why** something happened ("why did login break?")
+- **What breaks if** X changes ("blast radius of renaming `validateToken`?")
+- **What's connected to** X transitively ("everything downstream of `JWT_SECRET`?")
+- **Where the contradiction is** ("these two docs disagree — which holds?")
+
+Do NOT use Predicate for:
+- Fuzzy semantic recall ("find docs about login" — use vector search)
+- One-shot Q&A with no entities/relations
+
+# Workflow
+
+Follow this sequence. Each step has a hard gate.
+
+1. **Explore the schema first.** Call `kg_explore_schema(concept)` to learn the
+   predicates available. Do not draft SPARQL without doing this.
+2. **Draft fresh SPARQL.** Compose a query against `kg:abox` and `kg:inferred`.
+   Pre-baked templates are forbidden. The query should be specific to the
+   concept slice you just read.
+3. **Execute via `kg_ask`.** Pass the question and SPARQL. Inspect rows. If
+   empty or odd, refine — narrow filters, broaden graphs, check for typos.
+4. **Cite provenance.** For every claim the user might act on, call
+   `kg_explain` to surface the inference path. Show the user the SOURCE,
+   CONFIDENCE, and METHOD for the load-bearing triples.
+5. **Assert only after research.** If you learned something new in the session,
+   call `kg_assert(triple, source, confidence, method)`. Confidence must be
+   honest (parsed code: 0.95+; extracted from prose: 0.6–0.8).
+6. **Propose schema only when ABox cannot represent the fact.** If the gap is
+   structural (no class or property exists), call `kg_propose_schema(delta,
+   justification)`. The promotion gate requires the proposed concept be used
+   in N ≥ 3 successful queries within 7 days before it joins the live TBox.
+
+# HARD-GATE anti-patterns
+
+- ❌ Dumping raw text into `kg_assert` — assertions are triples, not prose.
+- ❌ Querying `kg:inferred` to write back into `kg:abox`.
+- ❌ Bypassing SHACL by writing to graphs that skip validation.
+- ❌ Inventing predicates — always check the TBox first.
+
+# Worked examples
+
+## 1. Why did login break?
+
+```
+kg_explore_schema("Function")     # learn :calls, :declaredIn, :reads
+kg_ask(
+  question="What does login depend on?",
+  sparql="""
+    PREFIX c: <https://predicate.dev/codebase#>
+    SELECT ?dep WHERE {
+      { GRAPH <kg:abox> { <https://predicate.dev/codebase/auth.ts#login> c:reads|c:calls ?dep } }
+      UNION
+      { GRAPH <kg:inferred> { <https://predicate.dev/codebase/auth.ts#login> c:dependsOn ?dep } }
+    }
+  """
+)
+kg_explain("auth.ts#login depends on JWT_SECRET")
+```
+
+## 2. Blast radius of renaming `validateToken`
+
+```
+kg_explore_schema("calls")
+kg_ask(
+  question="What calls validateToken transitively?",
+  sparql="""
+    PREFIX c: <https://predicate.dev/codebase#>
+    SELECT ?caller WHERE {
+      GRAPH <kg:inferred> { ?caller c:calls* <...#validateToken> }
+    }
+  """
+)
+```
+
+## 3. Contradiction detection
+
+```
+kg_ask(
+  question="Any disjoint-class violations?",
+  sparql="""
+    PREFIX c: <https://predicate.dev/codebase#>
+    PREFIX owl: <http://www.w3.org/2002/07/owl#>
+    SELECT ?x ?a ?b WHERE {
+      GRAPH <kg:inferred> { ?x a ?a, ?b }
+      GRAPH <kg:tbox> { ?a owl:disjointWith ?b }
+    }
+  """
+)
+```
+
+## 4. Schema gap → propose
+
+```
+# User asks: "which services own these endpoints?"
+# kg_explore_schema reveals: no :owns property exists
+kg_propose_schema(
+  delta="""
+    @prefix c: <https://predicate.dev/codebase#> .
+    c:Service a owl:Class .
+    c:owns a owl:ObjectProperty ;
+      rdfs:domain c:Service ; rdfs:range c:Endpoint .
+  """,
+  justification="Goal G-123 asks 'which service owns /login'; no current property captures service-to-endpoint ownership."
+)
+# This goes to kg:tbox-staging. The promotion gate requires 3 successful uses in 7 days.
+```

package/skills/predicate-doctor/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: predicate-doctor
+description: Run a health check on the Predicate stack — Fuseki reachability, TBox loaded, all 8 kg_* tools responsive. Use when the user asks "is predicate working", "what's the status", or any kg_* tool just returned an unexpected error.
+---
+
+# When to use
+
+- The user asks "is predicate up", "check predicate", "what's wrong with the kg".
+- A `kg_*` MCP tool just returned a connection or auth error.
+- After bringing Fuseki up for the first time, to confirm the seed TBox loaded.
+
+# Workflow
+
+1. Call `kg_stats`. If it errors with a connection refused or 401, **Fuseki is not reachable** — tell the user to run `predicate up` (or `pnpm fuseki:up` from a dev clone) and stop here.
+2. If `kg_stats` succeeds, report:
+   - `s.tbox > 0` → TBox is loaded.
+   - `s.classes` → number of declared classes (should be ≥ 10 for the seed codebase TBox).
+   - `s.triples`, `s.abox`, `s.inferred` → graph sizes.
+3. Optionally call `kg_explore_schema("File")` to confirm the seed TBox is the codebase domain.
+
+# Report format
+
+A short summary in this shape:
+
+> Predicate is **up**. TBox: N classes. ABox: M triples. Inferred: K. Last
+> materialization p95: X ms. (or: "no materialization events yet")
+
+If anything is off, lead with what's broken and the one-liner fix.

package/skills/predicate-stats/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: predicate-stats
+description: Show current graph metrics — triple counts, inferred ratio, unused-concept ratio. Use when the user asks "how big is the graph", "what's the inferred ratio", "show stats", or wants to track v1 success metrics from the PRD.
+---
+
+# When to use
+
+- The user asks "how many triples", "graph size", "stats", "metrics".
+- The user wants to track the bounded-growth metric (`unusedConceptRatio < 0.15`).
+- Before/after a `kg_maintain` run to see what changed.
+
+# Workflow
+
+1. Call `kg_stats`.
+2. Render the result as a compact table:
+
+```
+triples                123
+abox                   45
+inferred                8
+tbox                   70
+classes                12
+inferredRatio        0.151
+unusedConceptRatio   0.500
+materializationLatencyMsP95   0
+```
+
+3. If `unusedConceptRatio > 0.15`, note that the bounded-growth metric is currently failing the PRD §16 target and the next `kg_maintain` run should help.
+4. If `materializationLatencyMsP95 == 0`, note that no materialization events have been recorded yet (this is normal until the reasoner runs).