predicate-skill 1.6.0 → 2.0.1

package/skills/predicate/SKILL.md

@@ -16,6 +16,11 @@ Use Predicate when the user asks:
 - **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?")
+- **What was done previously** ("which files did I modify last session?",
+  "did `pnpm test` pass last time?", "what commands have failed most often?") —
+  the Stop-hook extractor records every prior session's tool calls into
+  `kg:abox` as `pred:Session` + `codebase:modifiedIn` / `succeededIn` /
+  `failedIn` triples. See worked example 4.
 
 Do NOT use Predicate for:
 - Fuzzy semantic recall ("find docs about login" — use vector search)
@@ -101,7 +106,99 @@ kg_ask(
 )
 ```
 
-## 4. Schema gap → propose
+## 4. Session history — "which files did I touch last session?"
+
+When the user references prior work, query the session-history slice that
+the Stop-hook extractor maintains in `kg:abox`. The relevant predicates
+are `pred:Session` (the session entity), `codebase:modifiedIn`,
+`codebase:succeededIn`, `codebase:failedIn`, `codebase:commandText`.
+
+```
+kg_explore_schema("Session")         # confirm the predicates
+kg_ask(
+  question="Which files did I modify in the most recent session?",
+  sparql="""
+    PREFIX pred: <https://predicate.dev/meta#>
+    PREFIX cb:   <https://predicate.dev/codebase#>
+    SELECT ?file ?session ?at WHERE {
+      GRAPH <kg:abox> {
+        ?session a pred:Session ; pred:at ?at .
+        ?file cb:modifiedIn ?session .
+      }
+    } ORDER BY DESC(?at) LIMIT 20
+  """
+)
+```
+
+Other useful queries on this slice:
+
+```
+# Commands that have failed most often (debug-cycle hotspots)
+SELECT ?text (COUNT(?session) AS ?failures) WHERE {
+  GRAPH <kg:abox> {
+    ?cmd a cb:Command ; cb:commandText ?text ; cb:failedIn ?session .
+  }
+} GROUP BY ?text ORDER BY DESC(?failures)
+
+# Files modified in this session that also failed a command (suspect debug targets)
+SELECT DISTINCT ?file WHERE {
+  GRAPH <kg:abox> {
+    ?file cb:modifiedIn ?session .
+    ?cmd  cb:failedIn   ?session .
+  }
+}
+```
+
+Cite the session URI as provenance when the answer is "you last touched
+auth.ts in session ses-X".
+
+The reasoner derives additional classes on top of the raw action data
+(refreshed by every `predicate maintain` run):
+
+| Derived class | Means |
+|---|---|
+| `codebase:Hotspot` | File modified in >= 3 sessions — likely active work-in-progress |
+| `codebase:FlakyCommand` | Command that has failed in >= 2 sessions — suspect debug target |
+| `codebase:ActiveFile` | File modified in the single most-recent session |
+
+Query them directly via `kg:inferred`:
+
+```sparql
+PREFIX cb: <https://predicate.dev/codebase#>
+SELECT ?file WHERE { GRAPH <kg:inferred> { ?file a cb:Hotspot } }
+```
+
+## 5. Memory recall — "what did I do with X recently?"
+
+For substring-match recall over session history, call `predicate recall`
+(or `kg_ask` with the equivalent SPARQL). Useful when the user asks
+"what did I work on related to X?" or "did I ever run command Y?"
+
+```sparql
+PREFIX cb:   <https://predicate.dev/codebase#>
+PREFIX pred: <https://predicate.dev/meta#>
+SELECT ?file (COUNT(DISTINCT ?session) AS ?n) (MAX(?at) AS ?lastAt)
+WHERE {
+  GRAPH <kg:abox> {
+    ?file cb:modifiedIn ?session .
+    ?session pred:at ?at .
+    FILTER (CONTAINS(LCASE(STR(?file)), LCASE("auth")))
+  }
+} GROUP BY ?file ORDER BY DESC(?lastAt)
+```
+
+Combine with the `cb:Hotspot` / `cb:FlakyCommand` / `cb:ActiveFile` derived
+classes from `kg:inferred` for richer answers ("is auth.ts a hotspot?").
+
+Shell shortcut:
+
+```bash
+predicate recall auth          # files + commands matching "auth"
+predicate recall "pnpm test"   # commands matching exact substring
+predicate recall auth --json   # machine-readable output
+```
+
+## 6. Schema gap → propose
 
 ```
 # User asks: "which services own these endpoints?"
@@ -117,3 +214,98 @@ kg_propose_schema(
 )
 # This goes to kg:tbox-staging. The promotion gate requires 3 successful uses in 7 days.
 ```
+
+## Federation
+
+If teammates also use Predicate, they can share session-history:
+
+```bash
+# On Alice's machine:
+predicate export-sessions --user alice > alice.trig
+# Send to Bob (Slack, scp, etc.)
+
+# On Bob's machine:
+predicate import-sessions alice.trig
+predicate peer add alice http://alice.local:3030/predicate/query  # optional, for live queries
+
+# Then kg_ask can union local + remote:
+kg_ask --include-remote ...
+```
+
+This MVP is offline-friendly: no realtime sync, no auth. Each user's data
+lives in a separate named graph so there are no merge conflicts. Same-IRI
+collisions (e.g. `file:///work/auth.ts` from two users) are treated as
+the same resource by RDF — use `owl:sameAs` if you want them merged, or
+namespace your files per-user if you want them separate.
+
+## External Linked Data
+
+For canonical public knowledge (Wikidata, DBpedia), call `predicate ld
+ask` instead of trying to recall from training data. Examples:
+
+```bash
+predicate ld init  # one-time
+
+predicate ld ask 'SELECT ?label WHERE {
+  <http://dbpedia.org/resource/JSON> rdfs:label ?label .
+  FILTER (LANG(?label) = "en")
+} LIMIT 1'
+```
+
+Use cases:
+- "Is library X deprecated?" → check Wikidata for last-release metadata
+- "Who maintains project Y?" → DBpedia abstract
+- "What's the canonical URI for concept Z?" → both
+
+`predicate ld init` registers `dbpedia` and `wikidata` as peers in
+`kg:peers` with `pred:peerKind "external-ld"`. The marker keeps them
+distinct from team peers — `predicate peer list` shows everything
+side-by-side with a `kind` column; `predicate ld list` filters to just
+the LD endpoints. Results from `ld ask` are NOT written back to local
+`kg:abox` — each call re-fetches, so don't run this in tight loops.
+
+## Goal decomposition
+
+The default `kg_research_goal` uses a pattern-based decomposer
+(deterministic, fast, predictable). For questions that don't match any
+pattern, you can opt-in to LLM-augmented decomposition by passing
+`useLlmDecomposer: true`. The LLM (Claude Haiku) is constrained to
+emit only the known intent kinds — invented kinds are filtered out.
+If no `ANTHROPIC_API_KEY` is set, it transparently falls back to the
+deterministic decomposer's 'unknown' result. The response includes a
+`decomposerKind` field (`"deterministic"` or `"semantic"`) so you know
+which path produced the sub-questions. Pattern-matched questions like
+"what calls X" skip the LLM entirely.
+
+## Schema-learning toggle (v2.0)
+
+The autonomous proposer (Generalizer) runs by default — when the agent
+asserts a triple using a not-yet-declared pattern that appears in >= K
+instances, it auto-stages a `kg_propose_schema` candidate. The sweeper
+promotes after 3 successful uses.
+
+To pause that loop (e.g., the user says "stop adding new predicates"):
+
+```
+kg_config_set({ key: "schema-learning", value: false })
+```
+
+When off:
+- The Generalizer skips proposal generation.
+- `kg_propose_schema` (explicit MCP calls) STILL works.
+- The PromotionSweeper STILL promotes existing staged proposals.
+
+Re-enable with `kg_config_set({ key: "schema-learning", value: true })`.
+Read current state with `kg_config_get({ key: "schema-learning" })`.
+
+## Init / bootstrap (v2.0)
+
+Predicate v2.0 boots empty. On first `predicate up`, the user picks one
+of three modes via `predicate init` (interactive prompt or flags):
+
+- **community**: bundled ontology (codebase, foaf, schema-org-lite, fhir-core)
+- **upload**: user-supplied .ttl
+- **empty**: meta + minimal top vocab; agent grows it via propose -> 3-use -> promote
+
+The chosen mode is stored at `<urn:predicate:config>` in kg:meta and the
+SessionStart banner reflects it.