openlore 2.0.0

package/examples/opencode/plugins/openlore-enforcer.ts

@@ -0,0 +1,227 @@
+/**
+ * openlore-enforcer.ts  v2
+ *
+ * Plugin OpenCode : enforce le workflow SDD openlore.
+ *
+ * Blocs :
+ *   1. tool.execute.before  — nudge avant toute écriture de fichier source sans
+ *      décision enregistrée ; avertissement sur approve/reject_decision (déjà
+ *      protégés côté MCP par requiresHumanAuthorization).
+ *   2. session.idle event   — gate check : vérifie l'état des décisions et
+ *      présente les décisions en attente à l'agent.
+ *   3. tool.execute.after   — rappel périodique toutes les 5 actions.
+ *   4. experimental.session.compacting — préserve les décisions actives lors
+ *      des compactions de contexte pour éviter la dérive silencieuse.
+ *
+ * Placer dans : .opencode/plugins/openlore-enforcer.ts
+ */
+
+import { execSync } from 'child_process';
+import type { Plugin } from '@opencode-ai/plugin';
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+interface GateResult {
+  gated: boolean;
+  reason?: string;
+  verified?: any[];
+}
+
+// ─── Config ──────────────────────────────────────────────────────────────────
+
+let _openloreBin: string | null = null;
+
+function resolveOpenLore(): string {
+  if (_openloreBin) return _openloreBin;
+  for (const c of ['node_modules/.bin/openlore', 'dist/cli/index.js']) {
+    try {
+      execSync(`test -f ${c}`, { stdio: 'pipe' });
+      _openloreBin = c.endsWith('.js') ? `node ${c}` : c;
+      return _openloreBin;
+    } catch {}
+  }
+  _openloreBin = 'openlore';
+  return _openloreBin;
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function run(args: string): string {
+  try {
+    return execSync(`${resolveOpenLore()} ${args}`, {
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+  } catch (e: any) {
+    return e.stdout ?? '';
+  }
+}
+
+function parseJSON<T>(raw: string): T | null {
+  try {
+    return JSON.parse(raw.replace(/```json|```/g, '').trim());
+  } catch {
+    return null;
+  }
+}
+
+function runGate(): GateResult | null {
+  return parseJSON<GateResult>(run('decisions --gate --json'));
+}
+
+function getActiveDecisions(): any[] {
+  return parseJSON<any[]>(run('decisions --list --json')) ?? [];
+}
+
+// Fichiers source susceptibles de contenir des choix architecturaux
+const SOURCE_PATTERN = /\.(ts|tsx|js|jsx|py|go|rs|rb|java|cpp|c|h)$/;
+const SKIP_PATTERN =
+  /\.(test|spec|stories|mock|fixture)\.[jt]sx?$|\.d\.ts$|\.lock$|\.json$|\.ya?ml$|\.md$|\.env$/;
+
+function isStructural(path: string): boolean {
+  return !!path && SOURCE_PATTERN.test(path) && !SKIP_PATTERN.test(path);
+}
+
+function presentDecisions(decisions: any[]): void {
+  const sep = '─'.repeat(60);
+  console.log(sep);
+  decisions.forEach((d, i) => {
+    console.log(`\n${i + 1}. [${d.id}] ${d.title}`);
+    console.log(`   Rationale  : ${d.rationale}`);
+    console.log(`   Domains    : ${(d.affectedDomains ?? []).join(', ')}`);
+    if (d.affectedFiles?.length) console.log(`   Files      : ${d.affectedFiles.join(', ')}`);
+  });
+  console.log(`\n${sep}`);
+  console.log('To approve : openlore decisions --approve <id>');
+  console.log('Then sync  : openlore decisions --sync');
+  console.log('Then commit: git commit\n');
+}
+
+// ─── Plugin ──────────────────────────────────────────────────────────────────
+
+export const OpenLoreEnforcer: Plugin = async (_ctx: any) => {
+  let toolCallCount = 0;
+
+  return {
+    // ── 1. Nudge avant chaque écriture de fichier source ────────────────────
+    //
+    // input: { tool, sessionID, callID }
+    // output: { args } — mutable (on ne modifie pas les args ici, juste nudge)
+    //
+    // Note : approve_decision / reject_decision sont déjà protégés côté MCP
+    // par requiresHumanAuthorization. On renforce le message ici.
+    //
+    'tool.execute.before': async (input: any, output: any) => {
+      if (input.tool === 'approve_decision') {
+        console.error('\n❌ ENFORCER: approve_decision requires HUMAN authorization.');
+        console.error('   Present the decision to the user and ask them to run:');
+        console.error('     openlore decisions --approve <id>');
+        console.error('     openlore decisions --sync');
+        console.error('     git commit\n');
+        return;
+      }
+
+      if (input.tool === 'reject_decision') {
+        console.error('\n❌ ENFORCER: reject_decision requires HUMAN authorization.');
+        console.error('   Ask the user before rejecting any decision.\n');
+        return;
+      }
+
+      const isFileWrite = [
+        'write_file',
+        'create_file',
+        'str_replace_based_edit_tool',
+        'edit',
+      ].includes(input.tool);
+      if (!isFileWrite) return;
+
+      // output.args contient les arguments qui seront passés au tool
+      const filePath: string = output.args?.path ?? output.args?.file_path ?? '';
+      if (!filePath || !isStructural(filePath)) return;
+
+      const covered = getActiveDecisions().some((d) => (d.affectedFiles ?? []).includes(filePath));
+      if (!covered) {
+        console.log(`\n⚠️  ENFORCER — STRUCTURAL FILE: ${filePath}`);
+        console.log('   No architectural decision recorded for this file.');
+        console.log('   If this change is architectural, call record_decision FIRST.\n');
+      }
+    },
+
+    // ── 2. Gate check lors des pauses de l'agent ─────────────────────────────
+    //
+    // session.idle est l'event émis quand le modèle s'arrête.
+    // C'est le moment idéal pour vérifier l'état des décisions.
+    //
+    event: async ({ event }: any) => {
+      if (event.type !== 'session.idle') return;
+
+      const gate = runGate();
+      if (!gate || !gate.gated) return;
+
+      console.log('\n🔍 ENFORCER — Gate check:\n');
+
+      if (
+        gate.reason === 'no_decisions_recorded' ||
+        gate.reason === 'drafts_pending_consolidation'
+      ) {
+        console.log('⚠️  Source files modified but decisions not yet consolidated.');
+        console.log('   Run: openlore decisions --consolidate');
+        console.log('   Then: openlore decisions --list\n');
+        return;
+      }
+
+      if (gate.verified?.length) {
+        console.log(`⛔ ${gate.verified.length} decision(s) await human approval before commit:\n`);
+        presentDecisions(gate.verified);
+      }
+    },
+
+    // ── 3. Rappel périodique toutes les 5 actions ─────────────────────────────
+    //
+    // input: { tool, sessionID, callID, args }
+    // output: { title, output, metadata }
+    //
+    'tool.execute.after': async () => {
+      toolCallCount++;
+      if (toolCallCount % 5 !== 0) return;
+
+      const pending = getActiveDecisions().filter(
+        (d) => !['approved', 'synced'].includes(d.status)
+      );
+      if (pending.length === 0) return;
+
+      console.log(`\n📋 DECISION REMINDER [#${toolCallCount}] — ${pending.length} pending:\n`);
+      pending.forEach((d) => console.log(`   [${d.id}] ${d.title} (${d.status})`));
+      console.log('\n   Verify alignment with current changes before committing.\n');
+    },
+
+    // ── 4. Préserver les décisions lors des compactions de contexte ───────────
+    //
+    // input: { sessionID }
+    // output: { context: string[], prompt?: string } — mutable
+    //
+    'experimental.session.compacting': async (_input: any, output: any) => {
+      const decisions = getActiveDecisions();
+      if (decisions.length === 0) return;
+
+      output.context.push(
+        '## ACTIVE ARCHITECTURAL DECISIONS — DO NOT FORGET',
+        '',
+        ...decisions.map(
+          (d) =>
+            `### [${d.id}] ${d.title}\n` +
+            `- Status: ${d.status}\n` +
+            `- Rationale: ${d.rationale}\n` +
+            `- Domains: ${(d.affectedDomains ?? []).join(', ')}\n` +
+            `- Files: ${(d.affectedFiles ?? []).join(', ')}\n` +
+            (d.consequences ? `- Consequences: ${d.consequences}` : '')
+        ),
+        '',
+        '⚠️  All code changes MUST align with these decisions.',
+        'To supersede: record_decision({ ..., supersedes: "<id>" })'
+      );
+
+      console.log(`\n📦 Compaction: preserving ${decisions.length} decision(s).\n`);
+    },
+  };
+};

package/examples/opencode/prompts/sisyphus-sdd.md

@@ -0,0 +1,150 @@
+# Sisyphus — SDD Workflow Instructions
+
+You are Sisyphus, orchestrating a spec-driven development project.
+This project uses **openlore** to maintain a Spec-Driven Development triangle:
+
+```
+     Specifications
+        /       \
+       /         \
+    Tests ——— Code
+```
+
+Your job is to keep all three edges in sync at all times.
+
+Three plugins are active in this session:
+- **anti-laziness** — detects when you stop early and re-prompts you to continue.
+- **openlore-enforcer** — nudges you before structural file writes and presents pending decisions at idle.
+- **openlore-decision-extractor** — analyzes your file writes and suggests `record_decision` calls when it detects architectural changes.
+
+---
+
+## BEFORE taking any action
+
+Think through:
+1. Is this request architectural in nature?
+   - Does it change module responsibility / ownership?
+   - Does it introduce a new pattern or approach?
+   - Does it affect how components communicate?
+   - Does it change data flow or state management?
+   - Does it introduce a new dependency or constraint?
+   - Does it affect error handling strategies?
+
+2. **If ANY answer is YES** → call `record_decision` IMMEDIATELY, before writing any code.
+
+3. **If UNSURE** → treat it as architectural. Over-recording is better than under-recording.
+
+---
+
+## Mandatory tool call order
+
+```
+1. record_decision(...)        ← FIRST, if architectural
+2. [code changes / file writes]
+3. check_spec_drift            ← AFTER changes
+4. openlore decisions --list   ← verify all decisions recorded
+5. [human approval gate]       ← NOT your job to approve
+6. openlore decisions --sync   ← AFTER human approval
+7. git commit                  ← LAST
+```
+
+---
+
+## record_decision — when and how
+
+Call this tool with:
+
+```json
+{
+  "title": "Concise architectural choice (max 10 words)",
+  "rationale": "Why this approach was chosen (2-3 sentences explaining the reasoning)",
+  "affectedDomains": ["domain-name-from-openspec"],
+  "affectedFiles": ["path/to/file.ts"],
+  "consequences": "What this changes downstream (1-2 sentences)",
+  "supersedes": "previous-decision-id (ONLY if replacing an earlier decision)"
+}
+```
+
+**Good examples of decisions to record:**
+- Splitting a service into two responsibilities
+- Choosing async over sync for a pipeline step
+- Adding a caching layer
+- Changing how modules communicate (events vs direct call)
+- Introducing a new abstraction / interface
+
+**NOT decisions (do not record):**
+- Fixing a typo
+- Renaming a variable
+- Adding a log line
+- Formatting / linting changes
+- Trivial bug fixes with no architectural impact
+
+---
+
+## Multi-iteration awareness
+
+If you are in a long session with multiple iterations:
+
+1. Before starting a new iteration, run `openlore decisions --list`
+   to review all previously recorded decisions.
+
+2. If you are about to change something that contradicts an existing decision,
+   you MUST either:
+   - **Supersede it**: `record_decision({ ..., supersedes: "old-id" })`
+   - **Explain the contradiction** to the user before proceeding
+
+3. You must NEVER silently drift from a recorded decision.
+   Drift = recorded decision says X, but code does Y without a new decision.
+
+---
+
+## Approval is HUMAN-ONLY
+
+You CANNOT call `approve_decision` yourself.
+You CANNOT auto-approve.
+You CANNOT skip the approval gate.
+
+When decisions are pending approval, present them to the user:
+
+```
+I've recorded the following architectural decisions for this session:
+
+1. [a3f2e1b0] Add OAuth provider abstraction
+   Rationale: Support multiple auth strategies, separate concerns
+   Domains: auth, security
+
+To approve and commit:
+  openlore decisions --approve a3f2e1b0
+  openlore decisions --sync
+  git commit
+```
+
+---
+
+## Compaction safety
+
+If the session context is compacted/summarized, the active decisions
+will be re-injected automatically by the openlore-enforcer plugin.
+Check `.openlore/decisions/pending.json` if you lose track of decisions.
+
+---
+
+## Final check (mandatory before every commit)
+
+```bash
+# 1. List all decisions
+openlore decisions --list
+
+# 2. Verify no spec drift
+openlore check-drift
+
+# 3. Present pending decisions to user for approval
+# 4. Wait for human to run: openlore decisions --approve <id>
+# 5. Sync to spec.md
+openlore decisions --sync
+
+# 6. Commit
+git commit -m "..."
+```
+
+Never skip this checklist.

package/examples/opencode-skills/openlore-analyze-codebase/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: openlore-analyze-codebase
+description: Run a full static analysis of a project using openlore and summarise the results — architecture, call graph, top refactoring issues, and duplicate code. No LLM required.
+license: MIT
+compatibility: openlore MCP server
+---
+
+# openlore: Analyze Codebase
+
+## When to use this skill
+
+Trigger this skill whenever the user asks to **analyze a codebase** with openlore, with phrasings like:
+- "analyze my project / my code"
+- "give me a code quality report"
+- "what are the structural issues in my codebase"
+- "find duplicates in my code"
+- explicit command `/openlore-analyze-codebase`
+
+This skill is **read-only** — it modifies no files. It produces a report and suggests next steps.
+
+---
+
+## Step 1 — Confirm the project directory
+
+Ask the user which project to analyze, or confirm the current workspace root.
+
+```
+Which project directory should I analyze?
+Options: current workspace root | enter a different path
+```
+
+---
+
+## Step 2 — Run static analysis
+
+Call the openlore MCP tool `analyze_codebase` with `{"directory": "$DIRECTORY"}`.
+
+---
+
+## Step 3 — Summarize the results
+
+Present a concise summary:
+- Project type and detected frameworks
+- File count, function count, internal call count
+- Top 5 refactoring issues (function name, file, issue type, priority score)
+- Detected domains
+
+Also report stack inventory (read directly from `.openlore/analysis/` — no extra MCP call needed):
+- **HTTP routes**: N routes across M files — if `route-inventory.json` exists
+- **ORM tables**: N tables — if `schema-inventory.json` exists
+- **Env vars**: N total, X required without default — if `env-inventory.json` exists
+- **UI components**: N components — if `ui-inventory.json` exists
+
+If none of these files exist, skip this section and suggest running `openlore analyze --force`.
+
+---
+
+## Step 4 — Show the call graph
+
+Call the openlore MCP tool `get_call_graph` with `{"directory": "$DIRECTORY"}`.
+
+Highlight:
+- **Hub functions** (fanIn ≥ 8) — over-solicited functions, high coupling risk
+- **Layer violations** detected (e.g. a UI layer calling the database directly)
+
+---
+
+## Step 5 — Show duplicate code report
+
+Call the openlore MCP tool `get_duplicate_report` with `{"directory": "$DIRECTORY"}`.
+
+Present a concise summary:
+- Overall duplication ratio (e.g. "12% of functions are duplicated")
+- Top 3 clone groups sorted by impact (instances × line count):
+  - Clone type (exact / structural / near) and similarity score
+  - List of instances (file + function name + line range)
+- If no duplicates found, note this as a positive signal
+
+---
+
+## Step 6 — Suggest next steps
+
+Based on the analysis, guide the user through the natural next actions in order:
+
+1. Call `get_minimal_context` on the highest-priority function — returns callers, callees, body, and test coverage in one call (~300 tokens). Use instead of `get_subgraph` + `get_signatures` separately.
+2. Call `get_cluster` on any function to see its full community (tightly coupled neighbors across directories).
+3. Call `detect_changes` to rank recently changed functions by blast radius — spot riskiest commits before reviewing.
+3. If significant duplication was found, suggest consolidating clone groups **before** refactoring
+4. Suggest running `/openlore-plan-refactor` once the user has enough context to act, then `/openlore-execute-refactor` to apply the plan
+5. If the project has OpenSpec specs, call `list_spec_domains` then `search_specs` to enable
+   spec-first reasoning (question → requirements → linked source files). To activate `search_specs`,
+   run `openlore analyze --embed` or `openlore analyze --reindex-specs`.
+
+---
+
+## Absolute constraints
+
+- **No code modifications** in this workflow
+- Never skip the duplication step — it determines the order of subsequent actions
+- Always present call graph and duplicate report results even if numbers are low
+- Next steps (Step 6) are suggestions, not automatic actions