holycodex 0.2.1

package/plugin/skills/lsp-setup/scripts/verify-lsp.ts

@@ -0,0 +1,166 @@
+#!/usr/bin/env bun
+// verify-lsp.ts <file> [--timeout=ms] — perform a real LSP diagnostics roundtrip
+// for <file> through the lsp-tools-mcp engine and report ok/fail with error text.
+// The engine source is located by walking up from this script and the cwd, so
+// run it inside the HolyCodex repository (where packages/lsp-core/src exists).
+
+import { existsSync, statSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import process from "node:process";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const ENGINE_TOOLS = "packages/lsp-core/src/tools.ts";
+const ENGINE_CONTEXT = "packages/lsp-core/src/request-context.ts";
+const ENGINE_MANAGER = "packages/lsp-core/src/lsp/manager.ts";
+const DEFAULT_TIMEOUT_MS = 60_000;
+
+interface ToolExecutionResult {
+  readonly content: ReadonlyArray<{ readonly type: "text"; readonly text: string }>;
+  readonly isError?: boolean;
+  readonly details?: unknown;
+}
+
+interface DiagnosticsDetails {
+  readonly mode: "file" | "directory";
+  readonly totalDiagnostics: number;
+  readonly error?: string;
+  readonly errorKind?: "missing_dependency" | "no_files" | "invalid_path";
+}
+
+interface ToolsModule {
+  readonly executeLspDiagnostics: (
+    params: Record<string, unknown>,
+    signal?: AbortSignal,
+  ) => Promise<ToolExecutionResult>;
+}
+
+interface ContextModule {
+  readonly runWithRequestContext: <T>(
+    context: { cwd?: string; env?: Record<string, string> },
+    fn: () => T,
+  ) => T;
+}
+
+interface ManagerModule {
+  readonly disposeDefaultLspManager: () => Promise<void>;
+}
+
+function findUp(relativeTarget: string): string | null {
+  const starts = [dirname(fileURLToPath(import.meta.url)), process.cwd()];
+  for (const start of starts) {
+    let current = start;
+    while (true) {
+      const candidate = join(current, relativeTarget);
+      if (existsSync(candidate)) return candidate;
+      const parent = dirname(current);
+      if (parent === current) break;
+      current = parent;
+    }
+  }
+  return null;
+}
+
+function buildEnv(): Record<string, string> {
+  const env: Record<string, string> = {};
+  for (const [key, value] of Object.entries(process.env)) {
+    if (value !== undefined) env[key] = value;
+  }
+  return env;
+}
+
+function isDiagnosticsDetails(value: unknown): value is DiagnosticsDetails {
+  return (
+    typeof value === "object" && value !== null && "mode" in value && "totalDiagnostics" in value
+  );
+}
+
+async function loadModule<T>(relativeTarget: string): Promise<T> {
+  const path = findUp(relativeTarget);
+  if (path === null) {
+    throw new EngineNotFoundError(relativeTarget);
+  }
+  return (await import(pathToFileURL(path).href)) as T;
+}
+
+class EngineNotFoundError extends Error {
+  constructor(public readonly target: string) {
+    super(
+      `lsp-tools-mcp engine not found (looked for ${target}). Run verify-lsp.ts inside the HolyCodex repository.`,
+    );
+    this.name = "EngineNotFoundError";
+  }
+}
+
+function parseTimeout(args: readonly string[]): number {
+  const flag = args.find((arg) => arg.startsWith("--timeout="));
+  if (flag === undefined) return DEFAULT_TIMEOUT_MS;
+  const parsed = Number.parseInt(flag.slice("--timeout=".length), 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_TIMEOUT_MS;
+}
+
+async function run(filePath: string, timeoutMs: number): Promise<number> {
+  const tools = await loadModule<ToolsModule>(ENGINE_TOOLS);
+  const context = await loadModule<ContextModule>(ENGINE_CONTEXT);
+  const manager = await loadModule<ManagerModule>(ENGINE_MANAGER);
+  const absolute = isAbsolute(filePath) ? filePath : resolve(process.cwd(), filePath);
+
+  try {
+    const signal = AbortSignal.timeout(timeoutMs);
+    const result = await context.runWithRequestContext(
+      { cwd: process.cwd(), env: buildEnv() },
+      () => tools.executeLspDiagnostics({ filePath: absolute, severity: "all" }, signal),
+    );
+    const details = isDiagnosticsDetails(result.details) ? result.details : null;
+    const text = result.content.map((part) => part.text).join("\n");
+
+    if (details?.errorKind === "missing_dependency") {
+      process.stdout.write(`FAIL ${absolute}: language server not installed\n${text}\n`);
+      return 1;
+    }
+    if (
+      result.isError === true ||
+      details?.errorKind === "invalid_path" ||
+      details?.errorKind === "no_files"
+    ) {
+      process.stdout.write(`FAIL ${absolute}: ${details?.error ?? text}\n`);
+      return 1;
+    }
+
+    const count = details?.totalDiagnostics ?? 0;
+    process.stdout.write(
+      `OK ${absolute}: LSP roundtrip succeeded (${count} diagnostic(s))\n${text}\n`,
+    );
+    return 0;
+  } finally {
+    await manager.disposeDefaultLspManager();
+  }
+}
+
+async function main(): Promise<void> {
+  const args = process.argv.slice(2);
+  const filePath = args.find((arg) => !arg.startsWith("--"));
+  if (filePath === undefined) {
+    process.stderr.write("Usage: bun verify-lsp.ts <file> [--timeout=ms]\n");
+    process.exit(2);
+  }
+  if (!existsSync(filePath) || !statSync(filePath).isFile()) {
+    process.stderr.write(`verify-lsp: not a file: ${filePath}\n`);
+    process.exit(2);
+  }
+
+  try {
+    const code = await run(filePath, parseTimeout(args));
+    process.exit(code);
+  } catch (error) {
+    if (error instanceof EngineNotFoundError) {
+      process.stderr.write(`SKIP: ${error.message}\n`);
+      process.exit(3);
+    }
+    process.stderr.write(
+      `FAIL ${filePath}: ${error instanceof Error ? error.message : String(error)}\n`,
+    );
+    process.exit(1);
+  }
+}
+
+await main();

package/plugin/skills/plan/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: plan
+description: Write a concise executable plan. Use only when the user explicitly asks for a plan before implementation.
+---
+
+# Plan
+
+On activation, first user-visible line must be:
+
+**PLAN MODE ACTIVATED**
+
+Main agent writes plan. No subagent, reviewer, evidence directory, execution waves, commit ritual, or ceremony unless user asks.
+
+Inspect enough repo context first. Then give ordered steps. Each step names relevant files or surface, exact change, expected outcome, smallest proof. Mark dependencies and user decisions only when material. Preserve architecture and scope. Stop when plan is executable.

package/plugin/skills/plan-review/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: plan-review
+description: Review and repair an existing plan once. Use only when the user explicitly asks to review, critique, validate, or improve a plan.
+---
+
+# Plan Review
+
+On activation, first user-visible line must be:
+
+**PLAN REVIEW ACTIVATED**
+
+One pass. Check plan against request and repo facts. Find only real blockers: wrong seam, missing dependency, unsafe mutation, unverifiable step, incompatible contract, omitted required scope. Repair directly. Keep good parts. No reviewer agent, scoring theater, evidence folder, or second review loop. Stop after corrected executable plan.

package/plugin/skills/programming/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: programming
+description: Strict Python, Rust, TypeScript, and Go implementation. Use whenever creating or changing .py, .pyi, .rs, .ts, .tsx, .mts, .cts, or .go files.
+---
+
+# Programming
+
+Use for `.py`, `.pyi`, `.rs`, `.ts`, `.tsx`, `.mts`, `.cts`, `.go`, or matching project manifest.
+
+Before code, read language `references/<language>/README.md`; load only linked topic needed. Read `references/logging.md` only when touching logs. Rust unsafe/FFI also loads all `references/rust-ub/`.
+
+## Core
+
+- Best code: none, existing helper, standard API, native feature, installed dependency, one line, then new code.
+- Trace real flow and callers. Fix shared root seam once.
+- Parse untrusted input once at boundary. Interior stays typed.
+- Make illegal states unrepresentable. Distinct primitives get distinct types.
+- Immutable default. No parameter mutation without explicit purpose.
+- Exhaustive variant handling.
+- No untyped escape, ignored diagnostics, non-null assertion, unchecked cast, panic/unwrap in library path.
+- Typed errors. Catch only expected errors; unknown errors propagate to boundary.
+- Existing project stack and logger win.
+- No helper for one caller. No speculative abstraction.
+
+## Test
+
+Public behavior red first. Confirm intended failure. Minimum green. Refactor. Use real object or fake before mock. Deterministic fixture; no sleep. At least one end-to-end user outcome for a new feature. Run smallest test in loop.
+
+## Size
+
+After write, measure pure LOC. Under 200 healthy; 200–250 warn; over 250 split unless generated table or documented indivisible state machine. Function over three independent parameters needs named domain input or specific reason.
+
+## Finish
+
+Run project formatter, linter, strict type checker, targeted tests, then proportional broader gate. Review: one responsibility; typed boundary; exhaustive variants; no escape hatch; no defensive duplicate layer; no one-off helper; regression test exists; no redundant post-action verification; positive names; logging matches project.

package/plugin/skills/programming/references/code-smells.md

@@ -0,0 +1,3 @@
+# Code smells
+
+Reject duplicate validation, one-call helpers, boolean mode flags, primitive obsession, variant `if` chains, catch-and-rethrow noise, speculative fallback, hidden mutation, global state, wide interfaces, oversized modules, comments narrating code, and tests coupled to private structure. Fix only smell in task scope; lock behavior first.

package/plugin/skills/programming/references/go/README.md

@@ -0,0 +1,3 @@
+# Go
+
+Preserve module stack. Greenfield: current Go, gofmt/gofumpt, `go vet`, golangci-lint, tests with race detector when concurrency touched. Accept context first for cancellable work. Concrete inputs, narrow consumer-owned interfaces, explicit zero-value semantics. Wrap errors with `%w`; use `errors.Is/As`. Close owned resources. No panic for expected failure, goroutine without owner/stop path, copied mutex, hidden global state, `interface{}` escape, or sleep-based test. Table tests only when cases share one contract. Run format, vet/lint, targeted tests; `-race` for concurrent code.

package/plugin/skills/programming/references/logging.md

@@ -0,0 +1,3 @@
+# Logging
+
+Use existing structured logger. Log once at ownership boundary, not every layer. Include stable event name and useful IDs; exclude secrets, tokens, raw personal data, huge payloads. Error logs retain typed cause and operation. Debug logs must not be required for correctness. Avoid string interpolation when logger supports fields.

package/plugin/skills/programming/references/python/README.md

@@ -0,0 +1,3 @@
+# Python
+
+Preserve workspace toolchain; greenfield prefers `uv`, Python 3.12+, Ruff, basedpyright, pytest. Type every public boundary. Parse external data with Pydantic v2 or existing schema layer. Prefer frozen dataclasses/models, protocols, pathlib, context managers, explicit async ownership, structured concurrency. No `Any`, bare `except`, mutable default, import side effect, silent fallback, or blocking I/O in async path. Use typed domain errors; preserve causes with `raise ... from`. Test public behavior with deterministic fixtures. Run formatter/lint, strict typecheck, targeted pytest.

package/plugin/skills/programming/references/rust/README.md

@@ -0,0 +1,3 @@
+# Rust
+
+Preserve crate choices. Greenfield: stable edition, rustfmt, Clippy warnings denied, cargo test. Model states with enums/newtypes; borrow before clone; iterator when clearer. Libraries return typed `thiserror` errors; applications may add `anyhow` context at boundary. No `unwrap`, `expect`, panic, ignored `Result`, needless clone, blocking call in async runtime, or unbounded task. Use cancellation-aware structured tasks. Test public behavior; add property tests only for real invariants. Unsafe/FFI also loads `../rust-ub/README.md`. Run fmt, check, Clippy, targeted tests; Miri when unsafe touched.

package/plugin/skills/programming/references/rust-ub/README.md

@@ -0,0 +1,3 @@
+# Rust unsafe / FFI
+
+Minimize unsafe surface; safe wrapper owns invariant. State aliasing, alignment, initialization, lifetime, provenance, thread, unwind, and ownership assumptions beside boundary. Validate foreign pointer/length before slice; define allocator and deallocation owner; use `repr(C)` only where ABI requires. No reference from possibly null/misaligned pointer, mutable alias, unchecked integer-to-pointer guess, or unwind across FFI. Add boundary tests. Run Miri first and after fix; use sanitizer/loom when memory or concurrency model requires it.

package/plugin/skills/programming/references/typescript/README.md

@@ -0,0 +1,3 @@
+# TypeScript
+
+Preserve workspace runtime/package manager. Strict `tsc`; project formatter/linter/test runner. `unknown` at boundaries, then narrow or schema-parse. Prefer discriminated unions, `readonly`, `satisfies`, type-only imports, named exports. No `any`, ignored diagnostic, non-null assertion, unchecked cast, enum, empty catch, or swallowed error. Async work must expose cancellation/timeout where caller needs it. React: semantic HTML, stable keys, minimal effects; derive state instead of syncing it. Test public behavior with Vitest/project runner. Run formatter, typecheck, targeted tests.

package/plugin/skills/refactor/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: refactor
+description: Behavior-preserving structural change with tests and semantic navigation. Use when asked to refactor, restructure, extract, simplify, or modernize code.
+---
+
+# Refactor
+
+Scope one smell or seam. No feature, formatting sweep, rename drift, or cleanup bundle.
+
+1. Map target responsibility, callers, references, tests, public contract.
+2. State invariant that must remain true.
+3. Add or run behavior-locking test before move.
+4. Use LSP references/rename for symbols. Use AST rewrite for repeated syntax shape.
+5. Move one responsibility at time. Keep compatibility only when contract requires it.
+6. Run smallest test after each semantic move.
+7. Delete obsolete path only after all callers move.
+8. Run strict diagnostics and proportional suite.
+
+Good split follows ownership, lifecycle, policy, or dependency boundary. Bad split creates pass-through files, one-call helpers, generic `utils`, or cycles.
+
+Stop and reassess if public API changes, tests cannot distinguish behavior, concurrent user edits overlap, or required migration exceeds request.

package/plugin/skills/remove-ai-slops/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: remove-ai-slops
+description: Remove AI-authored code smells while preserving behavior. Use when asked to clean generated code, remove AI slop, or simplify branch changes without feature work.
+---
+
+# Remove AI Slops
+
+Lock behavior first. Work only branch changes or explicit files. No broad repo cleanup.
+
+Categories: dead wrapper/helper; redundant guard or fallback; broad catch; vague narrative comment; duplicated path; needless object annotation; variant `if` chain; oversized mixed module; repeated post-action verification; inefficient equivalent work.
+
+For each category:
+
+1. Find exact instances.
+2. Add regression test when behavior lacks coverage.
+3. Confirm red where change fixes a bug; otherwise confirm behavior lock passes.
+4. Remove smallest smell set.
+5. Run targeted test and diagnostics.
+
+Do not collapse distinct semantics, remove required compatibility, change error strings, reorder observable effects, or “simplify” security checks without proof. Finish with formatter, linter, strict types, targeted suite, and diff review.

package/plugin/skills/rules/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: rules
+description: Explain or inspect HolyCodex scoped rule loading and cache. Use for rule locations, matching, injection, deduplication, limits, or cache behavior.
+---
+
+# Rules
+
+Automatic when plugin enabled. Static rules load on session start and user prompt. File rules load after matching edit. Post-compact clears session cache.
+
+Sources: `CONTEXT.md`, `.holycodex/rules/**/*.md`, `.codex/rules/**/*.md`, `.github/instructions/**/*.md`, `.github/copilot-instructions.md`. Never load or reinject `AGENTS.md`.
+
+Frontmatter: `alwaysApply: true` for static rule; `globs` string or list for path match. Body after frontmatter is injected. Native and plugin rules dedupe by normalized content hash. Per-rule cap 8,000 chars; event cap 24,000 chars.
+
+Environment: `HOLYCODEX_RULES_DISABLED=1`, `HOLYCODEX_RULES_MAX_RULE_CHARS`, `HOLYCODEX_RULES_MAX_RESULT_CHARS`.
+
+When debugging rules, report discovered files, parsed metadata, target path, match result, dedupe/cache result. Do not expose unrelated rule content.

package/plugin/skills/security-research/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: security-research
+description: Exploitability-led security audit with optional narrow research. Use for repository security reviews, threat analysis, vulnerability validation, or attack paths.
+---
+
+# Security Research
+
+Main agent owns scope, threat surface, dedupe, proof, severity, report. No Team Mode. At most two independent lanes when useful: `explorer` for one internal surface; `librarian` for named standards or dependency facts. No duplicate hunters, recursive delegation, reviewer loop, or full-history fork.
+
+## Rules
+
+- Name target: repo, diff, path, release, or threat surface.
+- Map entry points, attacker input, trust boundaries, sensitive assets, sinks, privilege transitions.
+- No severity without reachable attack path.
+- High or critical needs safe local PoC or decisive static proof plus concrete preconditions and impact.
+- CWE classifies weakness. Severity measures exploitability and impact. Keep separate.
+- Generic hardening is not finding.
+- Never attack real or third-party systems. Use local fixture, toy payload, dry run, or static proof.
+
+## Flow
+
+1. Baseline: scope, branch/diff, sensitive paths, tests, constraints.
+2. Threat surface: attacker capability, controlled input, boundary, sink, asset.
+3. Candidates: title, path/function, attack path, impact, CWE candidate, evidence, safe proof idea.
+4. Deduplicate by root cause and attack path.
+5. Validate strongest candidate. Reproduce, falsify, or downgrade. Record exact command and observed output.
+6. Calibrate severity from proven preconditions, reachability, privilege, user action, scope, confidentiality, integrity, availability.
+7. Give minimum fix and public-seam regression test.
+
+## Report
+
+Lead with `PASS`, `PASS WITH FINDINGS`, or `BLOCK`.
+
+For each surviving finding: severity, title, CWE, affected path/function, attacker capability, attack path, proof, impact, minimum fix, regression check.
+
+Also list downgraded and rejected candidates with reason. End with residual risk: untested surfaces and why.
+
+Use CWE, OWASP WSTG/ASVS, and CVSS v4 only when relevant. Cite exact source. Do not claim precise CVSS score without scoring every metric.

package/plugin/skills/tdd/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: tdd
+description: Public-seam vertical red-green-refactor development. Use when the user requests test-first work, TDD, regression tests, or integration tests.
+---
+
+# TDD
+
+Find established seam before asking user. Ask only if materially different contracts remain.
+
+## Slice
+
+1. Pick one observable outcome.
+2. Red: test public seam. Run it. Confirm failure matches missing behavior, not setup error.
+3. Green: minimum production code. No second case yet.
+4. Refactor only with green test.
+5. Repeat vertical slice.
+
+Given/When/Then: known fixture; one action; only observable result caused by action.
+
+Reject private-method tests, tautology, snapshot abuse, broad mocking, sleeps, wall-clock dependence, implementation-coupled assertions, deleted failing tests.
+
+Test doubles order: real object; in-memory fake; test container or sandbox; wire fake; narrow mock last. Fake must honor real contract.
+
+Fixtures deterministic and isolated. Coverage proportional to risk. Run smallest test during loop; broader gates at completion. See `tests.md` and `mocking.md` only when needed.

package/plugin/skills/tdd/mocking.md

@@ -0,0 +1,60 @@
+# When to Mock
+
+Mock at **system boundaries** only:
+
+- External APIs (payment, email, etc.)
+- Databases (sometimes - prefer test DB)
+- Time/randomness
+- File system (sometimes)
+
+Don't mock:
+
+- Your own classes/modules
+- Internal collaborators
+- Anything you control
+
+## Designing for Mockability
+
+At system boundaries, design interfaces that are easy to mock:
+
+**1. Use dependency injection**
+
+Pass external dependencies in rather than creating them internally:
+
+```typescript
+// Easy to mock
+function processPayment(order, paymentClient) {
+  return paymentClient.charge(order.total);
+}
+
+// Hard to mock
+function processPayment(order) {
+  const client = new StripeClient(process.env.STRIPE_KEY);
+  return client.charge(order.total);
+}
+```
+
+**2. Prefer SDK-style interfaces over generic fetchers**
+
+Create specific functions for each external operation instead of one generic function with conditional logic:
+
+```typescript
+// GOOD: Each function is independently mockable
+const api = {
+  getUser: (id) => fetch(`/users/${id}`),
+  getOrders: (userId) => fetch(`/users/${userId}/orders`),
+  createOrder: (data) => fetch("/orders", { method: "POST", body: data }),
+};
+
+// BAD: Mocking requires conditional logic inside the mock
+const api = {
+  fetch: (endpoint, options) => fetch(endpoint, options),
+};
+```
+
+The SDK approach means:
+
+- Each mock returns one specific shape
+- No conditional logic in test setup
+- Easier to see which endpoints a test exercises
+- Type safety per endpoint

package/plugin/skills/tdd/tests.md

@@ -0,0 +1,77 @@
+# Good and Bad Tests
+
+## Good Tests
+
+**Integration-style**: Test through real interfaces, not mocks of internal parts.
+
+```typescript
+// GOOD: Tests observable behavior
+test("user can checkout with valid cart", async () => {
+  const cart = createCart();
+  cart.add(product);
+  const result = await checkout(cart, paymentMethod);
+  expect(result.status).toBe("confirmed");
+});
+```
+
+Characteristics:
+
+- Tests behavior users/callers care about
+- Uses public API only
+- Survives internal refactors
+- Describes WHAT, not HOW
+- One logical assertion per test
+
+## Bad Tests
+
+**Implementation-detail tests**: Coupled to internal structure.
+
+```typescript
+// BAD: Tests implementation details
+test("checkout calls paymentService.process", async () => {
+  const mockPayment = jest.mock(paymentService);
+  await checkout(cart, payment);
+  expect(mockPayment.process).toHaveBeenCalledWith(cart.total);
+});
+```
+
+Red flags:
+
+- Mocking internal collaborators
+- Testing private methods
+- Asserting on call counts/order
+- Test breaks when refactoring without behavior change
+- Test name describes HOW not WHAT
+- Verifying through external means instead of interface
+
+```typescript
+// BAD: Bypasses interface to verify
+test("createUser saves to database", async () => {
+  await createUser({ name: "Alice" });
+  const row = await db.query("SELECT * FROM users WHERE name = ?", ["Alice"]);
+  expect(row).toBeDefined();
+});
+
+// GOOD: Verifies through interface
+test("createUser makes user retrievable", async () => {
+  const user = await createUser({ name: "Alice" });
+  const retrieved = await getUser(user.id);
+  expect(retrieved.name).toBe("Alice");
+});
+```
+
+**Tautological tests**: Expected value restates the implementation, so the test passes by construction.
+
+```typescript
+// BAD: Expected value is recomputed the way the code computes it
+test("calculateTotal sums line items", () => {
+  const items = [{ price: 10 }, { price: 5 }];
+  const expected = items.reduce((sum, i) => sum + i.price, 0);
+  expect(calculateTotal(items)).toBe(expected);
+});
+
+// GOOD: Expected value is an independent, known literal
+test("calculateTotal sums line items", () => {
+  expect(calculateTotal([{ price: 10 }, { price: 5 }])).toBe(15);
+});
+```