openlore 2.0.0

package/examples/mistral-vibe/skills/openlore-review-changes/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: openlore-review-changes
+description: Risk-aware code review using detect_changes + get_minimal_context + get_cluster. Surfaces the riskiest changed functions, interprets callType/coverage/cluster density, and produces a go/no-go recommendation. No code written.
+license: MIT
+compatibility: openlore MCP server
+user-invocable: true
+allowed-tools:
+  - use_mcp_tool
+  - ask_followup_question
+---
+
+# openlore: Review Changes
+
+## When to use this skill
+
+Trigger whenever the user asks to **review, audit, or check the safety of recent changes**:
+- "review my changes"
+- "what did I break?"
+- "is this branch safe to merge?"
+- "pre-PR check" / "what's risky in this diff?"
+- explicit command `/openlore-review-changes`
+
+**No code is written.** Output is a risk-ranked review with a go/no-go recommendation.
+
+---
+
+## Step 1 — Confirm directory and base ref
+
+Ask: which project? Diff against which base? (default: `main`)
+
+---
+
+## Step 2 — Detect changed functions and risk scores
+
+```xml
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>detect_changes</tool_name>
+  <arguments>{"directory": "$DIRECTORY", "base": "$BASE_REF"}</arguments>
+</use_mcp_tool>
+```
+
+Risk score is **multiplicative**: `likelihood × impact`.
+- `likelihood` = changeScore × (1 + coveragePenalty) — `"called"` tests count full; `"imported"`-only count 0.3×
+- `impact` = log(fanIn) + distance-weighted transitive callers (weighted by callType) + external boundary calls
+
+Functions with fanIn=0 calling nothing external score 0 — correct; focus on non-zero scores.
+
+Present a risk-ranked table:
+
+| Rank | Function | File | riskScore | blastRadius | fanIn | testedBy |
+|---|---|---|---|---|---|---|
+
+Flag: `≥ 5` → 🔴 HIGH | `2–5` → 🟡 MEDIUM | `< 2` → 🟢 LOW
+
+---
+
+## Step 3 — Deep-inspect each HIGH function
+
+```xml
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>get_minimal_context</tool_name>
+  <arguments>{"directory": "$DIRECTORY", "functionName": "$FUNCTION_NAME"}</arguments>
+</use_mcp_tool>
+```
+
+**What to read:**
+- `function.riskLevel` — `"high"` means up to 24 callers/callees shown; all are in blast radius.
+- `callers[*].callType` — all `"awaited"` = async interface frozen; signature change breaks all callers silently. Mixed = looser.
+- `callees[*].isExternal: true` — external boundary; failures propagate past mocks.
+- `testedBy[*].confidence` — `"called"` = strong. `"imported"` only = `vi.mock()` can neutralize; treat as untested.
+
+State for each HIGH function:
+```
+$FUNCTION_NAME: interface frozen? | external boundary? | effective coverage | verdict
+```
+
+---
+
+## Step 4 — Check cluster density for non-safe HIGH functions
+
+```xml
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>get_cluster</tool_name>
+  <arguments>{"directory": "$DIRECTORY", "functionName": "$FUNCTION_NAME"}</arguments>
+</use_mcp_tool>
+```
+
+`stats.clusterDensity`:
+- `< 0.05` → sparse; change isolated; safe to land independently
+- `0.05–0.15` → moderate; review `internalCallGraph` for transitively dependent functions
+- `> 0.15` → dense; coordinate whole cluster; consider feature flag or staged rollout
+
+---
+
+## Step 5 — Coverage gap check
+
+For each HIGH/MEDIUM function with `testedBy` empty or all `"imported"`:
+> "⚠️ `$FUNCTION_NAME` has no direct test coverage. Recommend a characterisation test before merging."
+
+Suggest a concrete test scenario from the function body.
+
+---
+
+## Step 6 — Output
+
+### Summary
+Total changed: N | HIGH: N | MEDIUM: N | Coverage gaps: N
+
+### Risk table (from Step 2)
+
+### Function verdicts (HIGH only)
+
+### Go / No-Go
+- ✅ **Safe to merge** — no HIGH-risk uncovered functions
+- ⚠️ **Merge with caution** — HIGH functions exist but covered by direct tests
+- 🛑 **Do not merge** — HIGH uncovered functions with frozen interfaces or external boundaries
+
+---
+
+## Absolute constraints
+
+- Never skip Step 3 for HIGH functions — riskScore alone is not enough
+- `callType` determines whether interface change is breaking — always interpret it
+- `"imported"` confidence is not strong coverage — always flag it
+- Do not recommend merging: riskScore ≥ 5 + zero direct tests + external callee

package/examples/mistral-vibe/skills/openlore-write-tests/SKILL.md

@@ -0,0 +1,261 @@
+---
+name: openlore-write-tests
+description: Write real tests for a function or spec scenario — language-agnostic (TypeScript, Python, C++…). Reads the implementation and spec contract first, runs tests, fixes failures. No stubs, no placeholders.
+license: MIT
+compatibility: openlore MCP server
+user-invocable: true
+allowed-tools:
+  - ask_followup_question
+  - use_mcp_tool
+  - read_file
+  - write_file
+  - str_replace_based_edit
+  - replace_in_file
+  - run_command
+---
+
+# openlore: Write Tests
+
+## When to use this skill
+
+Trigger this skill when the user wants to **write real tests** for a function, module, or spec
+scenario, with phrasings like:
+- "write tests for X"
+- "add test coverage for Y"
+- "what spec scenarios are untested?"
+- "implement the test for this scenario"
+- explicit command `/openlore-write-tests`
+
+**The rule**: read the implementation and spec contract before writing a single assertion.
+No `expect(true).toBe(true)`, no stubs, no placeholders.
+
+**Prerequisite**: openlore analysis must exist (`openlore analyze` has been run).
+If `orient` returns `"error": "no cache"` → run `openlore analyze` first, then retry.
+
+---
+
+## Step 1 — Identify target + detect framework
+
+Ask the user:
+1. **Target** — a function name, file path, spec scenario, or domain to test. If unsure, skip to Step 1b.
+2. **`$PROJECT_ROOT`** — project root directory.
+
+**Step 1b — Find untested scenarios (if no target given)**
+
+```xml
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>get_test_coverage</tool_name>
+  <arguments>{"directory": "$PROJECT_ROOT"}</arguments>
+</use_mcp_tool>
+```
+
+Present the top 5 uncovered scenarios to the user, ranked by spec importance. Ask which to
+implement first.
+
+**Step 1c — Detect test framework**
+
+Scan the project root for framework config files:
+
+| File found | Framework |
+|---|---|
+| `vitest.config.*`, `vitest.config.ts` | Vitest — runner: `npx vitest run <file>` |
+| `jest.config.*` | Jest — runner: `npx jest <file>` |
+| `pytest.ini`, `pyproject.toml` (with `[tool.pytest]`), `setup.cfg` | pytest — runner: `pytest <file> -v` |
+| `CMakeLists.txt` with `enable_testing()`, `*.test.cpp` | CTest/GTest — runner: build + `ctest` |
+| `go.mod` | Go test — runner: `go test ./...` |
+
+Store as `$TEST_RUNNER`. If ambiguous, ask the user.
+
+---
+
+## Step 2 — Orient
+
+```xml
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>orient</tool_name>
+  <arguments>{
+    "directory": "$PROJECT_ROOT",
+    "task": "write tests for $TARGET",
+    "limit": 5
+  }</arguments>
+</use_mcp_tool>
+```
+
+Extract:
+- **`$TARGET_FILE`** — the file containing the function(s) to test
+- **`$EXISTING_TEST_FILE`** — nearby test file, if any (e.g. `foo.test.ts`, `test_foo.py`, `foo_test.go`)
+- **`$SPEC_DOMAIN`** — the spec domain associated with the target
+
+---
+
+## Step 3 — Read implementation + spec contract
+
+**This step is mandatory. Do not write any test before completing it.**
+
+**3a — Read the function body**
+
+```xml
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>get_function_body</tool_name>
+  <arguments>{
+    "directory": "$PROJECT_ROOT",
+    "symbol": "$TARGET_FUNCTION",
+    "filePath": "$TARGET_FILE"
+  }</arguments>
+</use_mcp_tool>
+```
+
+Identify:
+- What the function takes as input, what it returns
+- What external dependencies it calls (filesystem, network, DB, LLM, subprocess)
+- What invariants are visible (guards, throws, early returns)
+
+**3b — Find the spec contract (if specs exist)**
+
+```xml
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>search_specs</tool_name>
+  <arguments>{
+    "directory": "$PROJECT_ROOT",
+    "query": "$TARGET — expected behaviour",
+    "limit": 5
+  }</arguments>
+</use_mcp_tool>
+```
+
+For each matching spec scenario, note:
+- The **GIVEN / WHEN / THEN** clauses — these become the test body
+- The scenario name — this becomes the `it()` / `def test_` / `TEST()` description
+
+If no specs exist, infer the contract from the function signature, docstring, and call sites.
+Document the inferred contract explicitly before writing any test.
+
+**3c — Absorb local test conventions**
+
+If `$EXISTING_TEST_FILE` exists, read it. Extract:
+- Mock setup pattern (`vi.mock`, `unittest.mock.patch`, `gmock`, etc.)
+- Fixture or factory helpers
+- Import path style (relative vs absolute)
+- Describe/class/suite structure
+
+If no test file exists nearby, find the closest test file in the project tree and read that instead.
+
+---
+
+## Step 4 — Write tests
+
+Write (or append to) `$EXISTING_TEST_FILE` (or create `<name>.test.ts` / `test_<name>.py` / `<name>_test.go` next to the source file).
+
+### Rules — enforced without exception
+
+1. **No placeholder assertions** — `expect(true).toBe(true)`, `assert True`, `EXPECT_TRUE(true)`,
+   `self.assertTrue(True)` are forbidden. Every assertion must test real return values or side effects.
+
+2. **One test = one scenario** — each `it()` / `def test_` / `TEST()` maps to one GIVEN/WHEN/THEN
+   clause. Use the spec scenario name (or a descriptive contract statement) as the test description.
+
+3. **Annotation tag (mandatory)** — place a coverage tag on the line immediately above each
+   `describe` / class / suite block so `openlore test --coverage` can track it:
+   - TypeScript/JS: `// openlore: {"domain":"$DOMAIN","requirement":"$REQ","scenario":"$SCENARIO","specFile":"openspec/specs/$DOMAIN/spec.md"}`
+   - Python: `# openlore: {"domain":"$DOMAIN","requirement":"$REQ","scenario":"$SCENARIO"}`
+   - C++/Go: `// openlore: {"domain":"$DOMAIN","requirement":"$REQ","scenario":"$SCENARIO"}`
+   
+   If no spec scenario exists (contract inferred), omit the tag.
+
+4. **Mock only system boundaries** — mock filesystem, network, LLM API, DB connections, and
+   external processes. Do not mock the function under test, its pure helpers, or in-memory logic.
+
+5. **One suite per function** — `describe` / class / suite named after the function.
+   Use nested blocks for distinct concerns (happy path, error path, edge cases).
+
+6. **At least one edge case** — empty input, null/None/nullptr, maximum value, or an error path
+   must be included for every function tested.
+
+7. **Small model constraint** — if the test file exceeds 200 lines, split into multiple files
+   grouped by concern. Each file must be independently runnable.
+
+### Structure reference (adapt to the detected framework)
+
+```typescript
+// TypeScript / Vitest
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { $TARGET_FUNCTION } from '../$TARGET_FILE';
+
+vi.mock('../$DEPENDENCY', () => ({ ... }));
+
+// openlore: {"domain":"$DOMAIN","requirement":"$REQUIREMENT","scenario":"$SCENARIO","specFile":"openspec/specs/$DOMAIN/spec.md"}
+describe('$TARGET_FUNCTION', () => {
+  beforeEach(() => { vi.resetAllMocks(); });
+
+  describe('$SCENARIO_NAME', () => {
+    it('should $EXPECTED_BEHAVIOUR when $CONDITION', () => {
+      // GIVEN
+      // WHEN
+      const result = $TARGET_FUNCTION($INPUT);
+      // THEN
+      expect(result).toEqual($EXPECTED);
+    });
+  });
+});
+```
+
+```python
+# Python / pytest
+import pytest
+from unittest.mock import patch, MagicMock
+from $MODULE import $TARGET_FUNCTION
+
+# openlore: {"domain":"$DOMAIN","requirement":"$REQUIREMENT","scenario":"$SCENARIO"}
+class Test$TargetFunction:
+    def test_$scenario_name_when_$condition(self):
+        # GIVEN / WHEN / THEN
+        result = $target_function($input)
+        assert result == $expected
+```
+
+---
+
+## Step 5 — Run and fix
+
+Run the test file with `$TEST_RUNNER`. Iterate until all tests pass.
+
+| Outcome | Action |
+|---|---|
+| All green | Proceed to Step 6 |
+| Failure in new test | Diagnose: is the assertion wrong, or is there a real bug? Fix the assertion if the expectation was incorrect. If a real bug is revealed, do not weaken the assertion — report the bug instead. |
+| Failure in pre-existing test | Stop. Fix the regression before adding more tests. |
+| Test can't compile / import | Fix the import path, mock setup, or dependency injection before retrying. |
+
+Do not weaken assertions to make tests pass. A test that masks a bug is worse than no test.
+
+---
+
+## Step 6 — Coverage check
+
+```xml
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>get_test_coverage</tool_name>
+  <arguments>{"directory": "$PROJECT_ROOT"}</arguments>
+</use_mcp_tool>
+```
+
+Report:
+- Which spec scenarios are now covered (new)
+- Which scenarios remain uncovered in `$SPEC_DOMAIN`
+- Whether any hub functions in `$SPEC_DOMAIN` are still untested (high-value next targets)
+
+---
+
+## Absolute constraints
+
+- Never write `expect(true).toBe(true)`, `assert True`, or equivalent placeholder assertions
+- Never skip Step 3 — the implementation read and spec contract are the test source of truth
+- Never mock the function under test itself
+- Never weaken an assertion to make a test pass — fix the implementation or the expectation
+- If `get_test_coverage` shows the scenario is already covered, report it and stop
+- Do not refactor the implementation as part of this skill — open a separate task

package/examples/opencode/agent-guard.ts

@@ -0,0 +1,170 @@
+/**
+ * openlore Agent Guard — OpenCode plugin
+ *
+ * Install: openlore setup --tools opencode
+ * (copies to .opencode/plugins/ — auto-loaded by OpenCode)
+ *
+ * What it does:
+ *   1. Anti-premature-stop: injects a system-prompt rule that prevents the agent
+ *      from declaring "Task completed" without having made real file changes.
+ *      Once real work is done, switches to a check_spec_drift reminder instead.
+ *   2. record_decision nudge: when a structural file (service/, domain/, core/, adapter/)
+ *      is modified without a prior record_decision call, appends a non-blocking
+ *      reminder to the tool output the agent reads.
+ *   3. Compaction safety: injects pending decisions into the compaction context
+ *      so they survive session summarisation.
+ *   4. tool.definition enrichment: adds known spec domains to the record_decision
+ *      tool description so the model uses the right domain names.
+ *
+ * Consolidation is NOT the plugin's responsibility.
+ * The record_decision MCP handler spawns `openlore decisions --consolidate` in the
+ * background automatically after saving each draft. By commit time, decisions are
+ * already consolidated — the pre-commit gate does no LLM work and is instant.
+ */
+
+import type { Plugin } from "@opencode-ai/plugin"
+import { spawn } from "node:child_process"
+import { readFile, readdir } from "node:fs/promises"
+import { join } from "node:path"
+
+const STRUCTURAL = /\/(service|domain|core|adapter)\//
+
+interface PendingDecision {
+  id: string
+  title: string
+  status: string
+  affectedDomains: string[]
+}
+
+async function loadPendingDecisions(directory: string): Promise<PendingDecision[]> {
+  try {
+    const raw = await readFile(join(directory, ".openlore", "decisions", "pending.json"), "utf-8")
+    const store = JSON.parse(raw)
+    return (store.decisions ?? []).filter(
+      (d: PendingDecision) => !["synced", "rejected"].includes(d.status),
+    )
+  } catch {
+    return []
+  }
+}
+
+async function loadSpecDomains(directory: string): Promise<string[]> {
+  try {
+    const entries = await readdir(join(directory, "openspec", "specs"), { withFileTypes: true })
+    return entries.filter(e => e.isDirectory()).map(e => e.name)
+  } catch {
+    return []
+  }
+}
+
+// Tools that write files — trigger re-analysis so the call graph stays fresh.
+const EDIT_TOOL_RE = /write_file|edit_file|create_file|str_replace|insert|patch/i
+
+// In-memory debounce: spawn at most one analysis per 10 s regardless of edit rate.
+let lastAnalyzeMs = 0
+const ANALYZE_DEBOUNCE_MS = 10_000
+
+function spawnAnalyze(directory: string): void {
+  const now = Date.now()
+  if (now - lastAnalyzeMs < ANALYZE_DEBOUNCE_MS) return
+  lastAnalyzeMs = now
+  // Fire-and-forget: detached + unref so it survives plugin process exit.
+  const child = spawn("openlore", ["analyze", "--output", ".openlore/analysis"], {
+    detached: true,
+    stdio: "ignore",
+    cwd: directory,
+  })
+  child.unref()
+}
+
+export const AgentGuard: Plugin = async ({ directory }) => {
+  const toolCalls = new Map<string, number>()
+  const rdCalled = new Map<string, boolean>()
+  const driftChecked = new Map<string, boolean>()
+
+  const inc = (sid: string) => toolCalls.set(sid, (toolCalls.get(sid) ?? 0) + 1)
+  const reset = (sid: string) => {
+    toolCalls.set(sid, 0)
+    rdCalled.set(sid, false)
+    driftChecked.set(sid, false)
+  }
+
+  return {
+    // Keep agent working until it has explicitly verified completion.
+    "experimental.chat.system.transform": async ({ sessionID }, output) => {
+      const n = toolCalls.get(sessionID) ?? 0
+      const checked = driftChecked.get(sessionID) ?? false
+
+      if (n === 0) {
+        output.system.push(
+          "Do not say 'Task completed', 'Done', or 'Finished' without having executed " +
+          "at least one file modification tool call. If no real work has been done yet, keep working.",
+        )
+      } else if (!checked) {
+        output.system.push(
+          "Before saying 'Task completed': re-read the original request and verify every part " +
+          "of it is addressed. If anything is missing or untested, keep working.",
+        )
+      }
+    },
+
+    // Track tool calls; nudge record_decision on structural file changes.
+    "tool.execute.after": async (input, output) => {
+      const { sessionID, tool, args } = input
+      inc(sessionID)
+
+      if (tool.includes("check_spec_drift")) {
+        driftChecked.set(sessionID, true)
+        return
+      }
+
+      if (tool.includes("record_decision")) {
+        rdCalled.set(sessionID, true)
+        return
+      }
+
+      const file: string = args?.filePath ?? args?.path ?? ""
+      if (STRUCTURAL.test(file) && !rdCalled.get(sessionID)) {
+        output.output +=
+          "\n\n[openlore] Structural file modified. " +
+          "Consider calling record_decision before continuing."
+      }
+
+      // Keep call graph fresh after every file edit (debounced 10 s).
+      if (EDIT_TOOL_RE.test(tool)) {
+        spawnAnalyze(directory)
+      }
+    },
+
+    // Inject pending decisions into compaction context so they survive summarisation.
+    "experimental.session.compacting": async (_input, output) => {
+      const decisions = await loadPendingDecisions(directory)
+      if (decisions.length > 0) {
+        const lines = decisions.map(
+          d => `  - [${d.status}] ${d.title} (domains: ${d.affectedDomains.join(", ")})`,
+        )
+        output.context.push(
+          `Pending architectural decisions — do not lose track of these:\n${lines.join("\n")}`,
+        )
+      }
+    },
+
+    // Enrich record_decision description with known spec domains.
+    "tool.definition": async ({ toolID }, output) => {
+      if (!toolID.includes("record_decision")) return
+      const domains = await loadSpecDomains(directory)
+      if (domains.length > 0) {
+        output.description +=
+          `\n\nKnown affectedDomains values for this project: ${domains.join(", ")}`
+      }
+    },
+
+    // Reset per-session counters on lifecycle events.
+    event: async ({ event }) => {
+      const sid = (event as any).properties?.sessionID
+      if (sid && ["session.idle", "session.created"].includes((event as any).type)) {
+        reset(sid)
+      }
+    },
+  }
+}