openlore 2.0.0

package/examples/bmad/tasks/sprint-planning.md

@@ -0,0 +1,168 @@
+# Task: Sprint Planning
+
+**Purpose**: Validate a sprint candidate before committing to it.
+Detects conflicts, blocked stories, and ordering constraints using structural analysis.
+
+**Who runs this**: Scrum Master Agent or Architect Agent, during sprint planning.
+**When**: Before the sprint is locked — after stories are written, before they're assigned.
+
+**Output**: sprint risk report + recommended story order + blocking issues list.
+
+---
+
+## Prerequisites
+
+- Onboarding completed (`bmad/tasks/onboarding.md`)
+- All sprint candidate stories have a `risk_context` section
+- If `risk_context` is missing on any story, run `annotate_story` on it first (not manually)
+
+---
+
+## Step 1 — Refresh the structural analysis
+
+If the last `analyze_codebase` run was more than 24 hours ago, or if code changed since then:
+
+```xml
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>analyze_codebase</tool_name>
+  <arguments>{"directory": "$PROJECT_ROOT", "force": false}</arguments>
+</use_mcp_tool>
+```
+
+---
+
+## Step 2 — Collect risk data per story
+
+For each story in the sprint candidate list:
+
+**If `risk_context` is already populated** (normal case — architect did their job):
+Read it directly from the story file. No MCP call needed.
+
+**If `risk_context` is absent**, run `annotate_story` now:
+
+```xml
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>annotate_story</tool_name>
+  <arguments>{
+    "directory": "$PROJECT_ROOT",
+    "storyFilePath": "$STORY_FILE_PATH",
+    "description": "$STORY_TITLE — $PRIMARY_AC"
+  }</arguments>
+</use_mcp_tool>
+```
+
+Collect from each story's `risk_context`:
+- `Domains` → which spec domains are touched
+- `Max risk score` + level
+- `Blocking refactors` → any listed
+- `Functions in scope` → for conflict detection
+
+**Also verify story quality:**
+- `## Won't Do` section must be present with at least 1 item
+- Every AC must be testable (specific observable outcome, not a vague quality)
+
+Flag non-compliant stories:
+> "⚠️ Story S-NN is missing `## Won't Do` / has vague ACs — return to author before sprint lock."
+
+---
+
+## Step 3 — Build the sprint risk matrix
+
+| Story | Domains | Risk | Blocking Refactors | Status |
+|---|---|---|---|---|
+| S-01 Add retry | payment | 🔴 82 | `processPayment` | ⛔ blocked |
+| S-02 Email validation | auth | 🟢 18 | none | ✅ ready |
+| S-03 Rate limiting | api | 🟡 45 | none | ⚠️ caution |
+
+**Status rules:**
+- ⛔ **blocked**: max risk ≥ 70 and no refactor story scheduled before it
+- ⚠️ **caution**: max risk 40–69, or story touches a critical hub
+- ✅ **ready**: max risk < 40 and no hub involvement
+
+---
+
+## Step 4 — Detect function conflicts
+
+Find stories whose `functions in scope` overlap.
+
+Get the full hub list to cross-reference:
+
+```xml
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>get_critical_hubs</tool_name>
+  <arguments>{"directory": "$PROJECT_ROOT", "limit": 15}</arguments>
+</use_mcp_tool>
+```
+
+For each hub that appears in two or more stories' function scope:
+
+> "⚠️ Stories S-01 and S-04 both touch `processPayment` (fan-in: 12).
+> Parallel risk: merge conflicts and silent regressions.
+> Recommend: sequence them, or assign to the same developer."
+
+---
+
+## Step 5 — Check spec coverage gaps
+
+```xml
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>check_spec_drift</tool_name>
+  <arguments>{"directory": "$PROJECT_ROOT"}</arguments>
+</use_mcp_tool>
+```
+
+For any `uncovered` files already present:
+> "Stories touching these files cannot use `check_spec_drift` as a completion gate.
+> Add a `openlore generate` task to the sprint."
+
+---
+
+## Step 6 — Determine story ordering
+
+**Rules:**
+1. Refactor stories before the stories they unblock
+2. Stories touching the same hub: sequence, do not parallelise
+3. Low-risk stories can be parallelised freely
+4. `openlore generate` after any story that adds new source files
+
+---
+
+## Step 7 — Sprint readiness verdict
+
+| Criterion | Status |
+|---|---|
+| No ⛔ stories without prior refactor scheduled | ✅ / ⛔ |
+| No parallel stories on the same hub | ✅ / ⚠️ |
+| All stories have `risk_context` | ✅ / ⛔ |
+| All stories have `## Won't Do` and testable ACs | ✅ / ⚠️ |
+| Spec coverage adequate for drift detection | ✅ / ⚠️ |
+
+**If any ⛔ remain: do not lock the sprint.** Resolve blockers first.
+
+---
+
+## Output
+
+Write the sprint plan to `.openlore/sprints/sprint-{N}.md`:
+
+```markdown
+# Sprint {N} — Risk Report
+
+Generated: {date}
+
+## Risk Matrix
+{table from Step 3}
+
+## Conflicts
+{list from Step 4}
+
+## Recommended Order
+{from Step 6}
+
+## Readiness
+{verdict from Step 7}
+```

package/examples/bmad/templates/story.md

@@ -0,0 +1,108 @@
+# Story {ID}: {Title}
+
+**Type**: feature | technical-debt | bug | spike
+**Epic**: {epic name}
+**Status**: Draft | Ready | In Progress | Review | Done
+
+---
+
+## User Story
+
+As a **{role}**,
+I want **{capability}**,
+so that **{benefit}**.
+
+---
+
+## Acceptance Criteria
+
+> Each criterion must be testable: describe a specific observable outcome, not a vague quality.
+> ✗ "The UX should be responsive" — not a criterion
+> ✓ "Submitting the form with an empty email field shows a validation error" — testable
+
+- [ ] AC1: {criterion}
+- [ ] AC2: {criterion}
+- [ ] AC3: {criterion}
+
+---
+
+## Won't Do
+
+> What this story explicitly does NOT cover. Minimum 1 item.
+> Prevents scope creep and removes ambiguity for the Dev Agent.
+
+- {out-of-scope item}
+
+---
+
+## Risk Context
+
+> Pre-filled by the Architect Agent using openlore.
+> Dev Agent reads this — does NOT rediscover it at implementation time.
+
+- **Domains in scope**: {e.g. auth, api}
+- **Max risk score**: {0–100} {🟢 low | 🟡 medium | 🟠 high | 🔴 critical}
+- **Functions in scope**: {function1 (file), function2 (file)}
+- **Blocking refactors**: {none | "Refactor X first — Story {ID}"}
+- **Parallel risk**: {none | "Conflicts with Story {ID} on function X"}
+- **Insertion points**: {function (strategy, score)}
+- **Spec domains linked**: {domain1/spec.md, domain2/spec.md}
+
+### Structural Notes
+
+{Any architectural constraints, patterns to follow, anti-patterns to avoid.
+ Filled by Architect Agent based on get_architecture_overview output.}
+
+---
+
+## Technical Constraints
+
+- {constraint 1}
+- {constraint 2}
+
+---
+
+## Tasks
+
+> Filled by Dev Agent during implementation.
+
+- [ ] {task 1}
+- [ ] {task 2}
+- [ ] Add/update tests
+- [ ] Run `check_spec_drift` — confirm clean
+
+---
+
+## Dev Agent Record
+
+> Filled by Dev Agent on completion.
+
+### Implementation Summary
+
+- **Insertion point used**: {function} in {file}
+- **Files changed**: {list}
+- **Tests added**: {N}
+- **Spec drift**: ✅ clean | ⚠️ {details}
+
+### Risk Notes
+
+| Function | Actual Risk Score | Delta vs Estimate |
+|---|---|---|
+| | | |
+
+### Scope Notes
+
+{Were any functions touched outside the planned scope? Why?}
+
+---
+
+## Dependencies
+
+- **Blocked by**: {Story ID — reason} | none
+- **Blocks**: {Story ID} | none
+
+---
+
+## Story Points
+
+{estimate} — basis: {risk level, insertion complexity, test surface}

package/examples/cline-workflows/openlore-analyze-codebase.md

@@ -0,0 +1,101 @@
+# openlore: Analyze Codebase
+
+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.
+
+## Step 1: Get the project directory
+
+Ask the user which project to analyse, or confirm we should use the current workspace root.
+
+<ask_followup_question>
+  <question>Which project directory should I analyse?</question>
+  <options>["Current workspace root", "Enter a different path"]</options>
+</ask_followup_question>
+
+## Step 2: Run static analysis
+
+Call analyze_codebase on the chosen directory.
+
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>analyze_codebase</tool_name>
+  <arguments>{"directory": "$DIRECTORY"}</arguments>
+</use_mcp_tool>
+
+## Step 3: Get the architecture overview
+
+Retrieve the high-level architecture map: clusters, cross-cluster dependencies,
+entry points, and critical hub functions. This is the fastest way to orient
+yourself before diving into details.
+
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>get_architecture_overview</tool_name>
+  <arguments>{"directory": "$DIRECTORY"}</arguments>
+</use_mcp_tool>
+
+Present a concise summary:
+- Total files, clusters, edges, cycles, and layer violations
+- Top 3 clusters sorted by file count, with their role (entry_layer / orchestrator /
+  hub_heavy / internal) and which clusters they depend on
+- Global entry points (the public-facing roots of the codebase)
+- Critical hub functions (high fan-in — touch with care)
+
+## Step 4: Summarise the refactor report
+
+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
+
+## Step 5: Show the call graph
+
+Retrieve hub functions, entry points, and any layer violations.
+
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>get_call_graph</tool_name>
+  <arguments>{"directory": "$DIRECTORY"}</arguments>
+</use_mcp_tool>
+
+Highlight any hub functions (fanIn ≥ 8) or layer violations detected.
+
+## Step 6: Show duplicate code report
+
+Retrieve the duplicate function analysis (Types 1–3, pure static analysis).
+
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>get_duplicate_report</tool_name>
+  <arguments>{"directory": "$DIRECTORY"}</arguments>
+</use_mcp_tool>
+
+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 7: Suggest next steps
+
+Based on the analysis, guide the user through the natural next steps 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. Call `suggest_insertion_points` with a brief feature description to find where new
+   logic should land — useful before starting any new work on this codebase
+4. If significant duplication was found, suggest consolidating clone groups before refactoring
+5. Suggest running `/openlore-plan-refactor` once the user has enough context to act,
+   then `/openlore-execute-refactor` to apply the plan
+6. If the project has OpenSpec specs:
+   - Call `list_spec_domains` to discover available spec domains
+   - Call `search_specs` to find requirements by intent — this enables spec-first reasoning
+     (question → requirements → linked source files) rather than code-first exploration
+   - Suggest `/openlore-implement-feature` for any new feature work
+     (integrates specs + insertion points + adversarial self-check + drift check)
+   - To enable `search_specs`, run `openlore analyze --embed` or `openlore analyze --reindex-specs`
+     (requires the embedding server)
+7. If `.claude/antipatterns.md` exists, mention that it is checked automatically
+   by `/openlore-implement-feature` during the adversarial self-check step

package/examples/cline-workflows/openlore-check-spec-drift.md

@@ -0,0 +1,102 @@
+# openlore: Check Spec Drift
+
+Detect code changes that are not reflected in the project's OpenSpec specifications.
+Runs in static mode — no LLM required, no quota consumed.
+
+**Prerequisites**: `openlore init` and `openlore generate` must have been run at least once
+in the target project.
+
+## Step 1: Get the project directory
+
+Ask the user which project to check, or confirm the current workspace root.
+
+<ask_followup_question>
+  <question>Which project directory should I check for spec drift?</question>
+  <options>["Current workspace root", "Enter a different path"]</options>
+</ask_followup_question>
+
+## Step 2: Run drift detection
+
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>check_spec_drift</tool_name>
+  <arguments>{"directory": "$DIRECTORY"}</arguments>
+</use_mcp_tool>
+
+If the result contains `{ "error": "..." }`, stop and tell the user what is missing
+(not a git repo / no config / no specs) with the exact remediation command to run.
+
+## Step 3: Present the results
+
+### No drift
+
+If `hasDrift` is false and `issues` is empty:
+
+> ✅ **No spec drift detected.** All changed files are covered by up-to-date specs.
+
+Show `baseRef` and `totalChangedFiles` for context.
+
+### Drift found
+
+Present a summary line first:
+
+```
+Drift detected on $totalChangedFiles changed file(s) vs $baseRef
+Gaps: $gaps · Stale: $stale · Uncovered: $uncovered · Orphaned: $orphanedSpecs
+```
+
+Then a table of issues, sorted by severity (error first):
+
+| Severity | Kind | File | Domain | Spec | Lines changed |
+|---|---|---|---|---|---|
+| ⛔ error | gap | src/auth/login.ts | auth | specs/auth/spec.md | +45/-12 |
+| ⚠️ warning | uncovered | src/billing/invoice.ts | — | — | +120/-0 |
+
+For each issue, show the `suggestion` field on the next line in italic.
+
+## Step 4: Recommend actions
+
+Based on the issue kinds found, guide the user:
+
+### gap (spec exists but is outdated)
+> The spec for **$domain** covers `$filePath` but wasn't updated when the code changed.
+> Run `openlore generate --domains $domain` to regenerate it, or edit the spec manually
+> if the change is minor.
+
+### stale (spec references deleted/moved code)
+> The **$domain** spec references code that no longer exists. Either the file was deleted
+> or its structure changed significantly. Run `openlore generate --domains $domain` to
+> rebuild the spec from the current state of the code.
+
+### uncovered (new file with no spec)
+> `$filePath` has no matching spec. If this file introduces new domain logic, run
+> `openlore generate` so that openlore can infer a spec from it. If it is a utility
+> or test helper, it may not need a spec.
+
+### orphaned-spec (spec references non-existent files)
+> A spec references files that no longer exist. The spec may need to be deleted or its
+> `source-files` header updated. Review the spec at `$specPath` manually.
+
+## Step 5: Offer to drill down
+
+If there are `gap` or `stale` issues, offer to show the signatures of the affected files
+so the user can see exactly what changed in the public API:
+
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>get_signatures</tool_name>
+  <arguments>{"directory": "$DIRECTORY", "filePattern": "$AFFECTED_FILE"}</arguments>
+</use_mcp_tool>
+
+## Step 6: Suggest next steps
+
+Present the following options and let the user choose:
+
+1. **Regenerate specs for affected domains** — run `openlore generate --domains <list>`
+   (fastest fix for `gap` and `stale` issues)
+2. **Review and edit specs manually** — appropriate for minor changes where the
+   existing spec is mostly correct
+3. **Install the pre-commit hook** — run `openlore drift --install-hook` so drift is
+   caught automatically before every commit
+4. **Run `/openlore-plan-refactor` then `/openlore-execute-refactor`** — if the drift
+   reveals structural issues in the changed files

package/examples/cline-workflows/openlore-execute-refactor.md

@@ -0,0 +1,212 @@
+# openlore: Execute Refactor
+
+Apply the refactoring plan produced by `/openlore-plan-refactor`. This workflow
+reads `.openlore/refactor-plan.md` at the start and re-reads it before each
+change to stay on track — especially important with small or limited models.
+
+**Prerequisites**: run `/openlore-plan-refactor` first and confirm the plan.
+
+## Step 1: Read the plan
+
+Read `.openlore/refactor-plan.md` from the project directory.
+
+If the file does not exist, stop immediately:
+> "No refactor plan found at `.openlore/refactor-plan.md`. Please run
+> `/openlore-plan-refactor` first to generate a plan."
+
+Extract and display a summary:
+- Target function, file, and line range
+- Strategy and risk score
+- Number of changes planned
+- Test command
+- Acceptance criteria
+
+Ask the user to confirm before proceeding.
+
+## Step 2: Establish a green baseline
+
+Confirm the test suite is passing. Use the test command from the plan.
+
+**If tests are already failing, stop and tell the user.** Do not proceed with
+refactoring on a red baseline — the failures must be fixed first or the user
+must explicitly acknowledge them.
+
+If a coverage tool is available, run it on the target file and compare against
+the coverage baseline in the plan.
+
+| Coverage on files to touch | Recommendation |
+|---|---|
+| ≥ 70% lines | Safe to refactor — proceed |
+| 40–69% lines | Caution — write characterisation tests for the affected functions before starting |
+| < 40% lines | **Stop.** Strongly recommend writing tests first. Refactoring untested code hides regressions. |
+| 0% (no tests at all) | **Block.** Do not refactor. Propose writing a minimal test harness first, then restart the workflow. |
+
+If coverage is below 40%, tell the user:
+> "Coverage on the target file is X%. Refactoring without test coverage risks
+> introducing silent regressions. I recommend writing tests for the affected
+> functions before proceeding. Would you like me to suggest test cases based on
+> the function signatures, or do you want to proceed at your own risk?"
+
+Only continue past this point with explicit user confirmation.
+
+**Large file warning**: If the target function spans more than 300 lines:
+> "This function is X lines long. Small models (< 13B parameters) may lose
+> code when editing files of this size in a single pass. Recommended approach:
+> apply Change 1 from the plan (smallest extraction) first to reduce the target
+> below 200 lines before the main refactor."
+
+## Step 3: Set the restore point
+
+Verify the working tree is clean, then note the restore point:
+
+```bash
+git status            # must show: nothing to commit, working tree clean
+git log --oneline -1  # note this commit hash — your restore point
+```
+
+If there are uncommitted changes, stop and ask the user to commit or stash them
+first. A clean tree guarantees that `git checkout HEAD -- <file>` will fully
+restore any file to its pre-edit state.
+
+Fill in the `Restore point` section of `.openlore/refactor-plan.md` with the
+current commit hash.
+
+## Step 4: Apply changes (one at a time)
+
+Before applying the first change, record the refactoring decision:
+
+```xml
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>record_decision</tool_name>
+  <arguments>{
+    "directory": "$DIRECTORY",
+    "title": "Refactor $TARGET_FUNCTION via $STRATEGY",
+    "rationale": "$PRIMARY_REASON from the plan's Why section",
+    "consequences": "Callers unchanged; complexity distributed across extracted helpers",
+    "affectedFiles": ["$TARGET_FILE"]
+  }</arguments>
+</use_mcp_tool>
+```
+
+Also call `record_decision` for any unexpected architectural choice that emerges mid-refactor (new module boundary discovered, shared interface change required, dependency introduced).
+
+**Before each change**, re-read `.openlore/refactor-plan.md` to confirm:
+- Which change you are on
+- Exactly what to extract, where to put it, and which call sites to update
+
+**Editing tool rule**: Always prefer a targeted edit tool (`replace_in_file`,
+`str_replace_based_edit`, `apply_diff`, or equivalent) over a full-file
+rewrite tool (`write_to_file`). Only use `write_to_file` if the file is under
+100 lines in total. If a change seems to require `write_to_file` on a larger
+file, stop and split it into smaller targeted edits instead.
+
+**Model capability note**: If using a small model (Mistral Small, Phi, Gemma,
+or any model under 13B parameters), enforce an additional constraint: each edit
+must touch a contiguous block of at most 50 lines. If the intended change
+exceeds this, split it into multiple smaller extractions and apply them one
+by one.
+
+For each change in the plan:
+
+1. **Read the source file** around the lines to extract (do not rely on memory).
+
+2. **Apply the edit**:
+   - Extract or move the identified block
+   - Place it in the target file and target class specified in the plan
+   - If the target file is new, create it with only the extracted code
+   - Update all call sites listed in the plan
+
+3. **Verify the diff** before running tests:
+   ```bash
+   git diff --stat   # only the expected files should appear
+   git diff          # scan deleted lines (-) and confirm each removal is
+                     # intentional — moved to a new function or file,
+                     # not silently dropped.
+                     # If deleted lines >> added lines with no new file
+                     # created, code was likely lost — abort immediately.
+   ```
+
+4. **Run the test suite** (use the command from the plan). If any test fails,
+   restore the file right away:
+   ```bash
+   git checkout HEAD -- <file>
+   ```
+   Do NOT accumulate broken state before restoring.
+
+5. **Mark the change as done** in `.openlore/refactor-plan.md` by appending
+   `✅` to the change heading, then proceed to the next one.
+
+Repeat until all changes in the plan are marked ✅.
+
+## Step 5: Verify improvement
+
+Re-analyse to confirm the priority score dropped for the refactored function.
+
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>analyze_codebase</tool_name>
+  <arguments>{"directory": "$DIRECTORY", "force": true}</arguments>
+</use_mcp_tool>
+
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>get_refactor_report</tool_name>
+  <arguments>{"directory": "$DIRECTORY"}</arguments>
+</use_mcp_tool>
+
+Check each acceptance criterion from the plan:
+- Priority score dropped below the target
+- Function is no longer in the top-5 list
+- Full test suite passes
+
+If not, investigate why and iterate (add a new change to the plan if needed).
+
+Run the full test suite one final time to confirm the refactored state is clean.
+
+## Step 6 (optional — requires openlore generate to have been run)
+
+**Important**: this step proposes irreversible changes (deletions, renames).
+Do not apply anything without explicit user confirmation at each sub-step.
+
+### 6a. Dead code: orphan functions
+
+Check for functions not covered by any spec requirement.
+
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>get_mapping</tool_name>
+  <arguments>{"directory": "$DIRECTORY", "orphansOnly": true}</arguments>
+</use_mcp_tool>
+
+Present the orphan list (kind `function` or `class` only). For each one, check:
+- Is it exported and potentially consumed by external code?
+- Is it re-exported from an index file?
+- Was it simply missed by the LLM in Stage 3?
+
+Only after the user has reviewed and confirmed each entry, propose deletion or
+a documentation comment marking it as intentionally uncovered.
+
+**Do not delete anything without the user explicitly approving each function.**
+
+### 6b. Naming alignment: spec vocabulary vs actual names
+
+Find functions whose names diverge from the business vocabulary in the spec.
+
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>get_mapping</tool_name>
+  <arguments>{"directory": "$DIRECTORY"}</arguments>
+</use_mcp_tool>
+
+Build a table of mismatches (requirement name vs function name) and present it
+to the user for review before touching any code:
+
+| Current name | Proposed name | File | Confidence |
+|---|---|---|---|
+
+Only renames with `confidence: "llm"` should be proposed automatically.
+Flag `confidence: "heuristic"` entries for manual verification first.
+
+**Wait for explicit user approval of the full rename table before applying
+any change. Apply renames one file at a time and run tests after each.**