holycodex 0.5.2 → 0.6.1-dev.29547206710.2

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

@@ -1,166 +0,0 @@
-#!/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

@@ -1,24 +0,0 @@
----
-name: plan
-description: Use when the user asks for a plan or implementation requires unresolved architecture, cross-cutting coordination, irreversible decisions, high risk, or material ambiguity; do not use for multiple obvious steps, simple direct work, status, or explanation. Produces one repo-grounded reviewed plan with approval and optional goal gates; unlike plan-review, it owns the full planning sequence.
----
-
-# Plan
-
-On activation, first user-visible line must be:
-
-**PLAN MODE ACTIVATED**
-
-Main agent owns planning. No subagent, reviewer agent, evidence directory, execution waves, commit ritual, or ceremony unless user asks.
-
-## Required sequence
-
-1. Load `plan`; inspect enough task and repo context.
-2. Write the complete initial plan. Each ordered step names the relevant file or surface, exact change, expected outcome, and smallest proof; mark only material dependencies, risks, and user decisions.
-3. Only after the initial plan exists, load `plan-review`. Never preload, parallelize, or imply its review.
-4. Use `plan-review` once to revise or rewrite the initial plan. Keep initial and reviewed phases distinct.
-5. Present the reviewed executable plan and ask for approval. Do not implement before approval.
-6. After approval, ask whether the user wants to define a goal.
-7. Only after explicit agreement, load `define-goal`; otherwise implement the approved plan.
-
-Preserve architecture and requested scope. Stop planning after approval and the optional goal choice; no repeated review or polishing loop.

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

@@ -1,22 +0,0 @@
----
-name: plan-review
-description: Use when a complete initial implementation plan needs feasibility, scope, sequencing, risk, or verification repair, including the required review phase of the plan skill; do not use before initial drafting or as a recurring reviewer. Produces one repaired executable plan; unlike plan it does not own drafting or approval.
----
-
-# Plan Review
-
-On activation, first user-visible line must be:
-
-**PLAN REVIEW ACTIVATED**
-
-Input must include the request, complete initial plan, and enough repo facts. If no initial plan exists, stop and return control to `plan`; never draft its first plan.
-
-One pass:
-
-1. Test feasibility and compatibility with repo architecture and user constraints.
-2. Find missing steps, dependencies, risks, ambiguities, unsafe mutations, weak completion criteria, and unverifiable outcomes.
-3. Remove unnecessary work, ceremony, scope expansion, duplicate checks, and poor sequencing.
-4. Strengthen each step's target, change, dependency, proof, and stop condition.
-5. Revise or rewrite directly; preserve sound content. Output one complete reviewed plan, not comments or scores.
-
-No reviewer agent, evidence folder, second review loop, or implementation. Stop after the corrected executable plan; `plan` owns presentation and approval.

package/plugin/skills/programming/SKILL.md

@@ -1,33 +0,0 @@
----
-name: programming
-description: Use when a task edits Python, Rust, TypeScript, Go, or their matching manifests; do not use for prose-only edits or unsupported languages. Applies language-specific correctness, typing, size, and verification rules; debugging or refactor may additionally own the workflow.
----
-
-# Programming
-
-Before editing `.py`, `.pyi`, `.rs`, `.ts`, `.tsx`, `.mts`, `.cts`, `.go`, or matching manifests, read `references/<language>/README.md`. Load `references/logging.md` only for logs and all `references/rust-ub/` for Rust unsafe or FFI.
-
-## 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
-
-Defect: add a public-seam regression test first and confirm the intended failure. Explicit test-first request or clearly defined new behavior without adequate proof: test public seam first, confirm failure, implement minimum green, then refactor. Existing tests may lock small covered changes. Do not force red-green for prose, configuration-only work, trivial mechanical edits, or behavior already adequately covered. Use real object or fake before mock. Deterministic fixture; no sleep. Add an end-to-end user outcome for new behavior when proportional. 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

@@ -1,3 +0,0 @@
-# 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

@@ -1,3 +0,0 @@
-# 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

@@ -1,3 +0,0 @@
-# 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

@@ -1,3 +0,0 @@
-# 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

@@ -1,3 +0,0 @@
-# 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

@@ -1,3 +0,0 @@
-# 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

@@ -1,3 +0,0 @@
-# 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

@@ -1,21 +0,0 @@
----
-name: refactor
-description: Use when a task needs behavior-preserving restructuring, extraction, simplification, modernization, or cleanup of one named seam; do not use for features, bug fixes, formatting sweeps, or broad AI-slop cleanup. Produces a behavior-locked structural change; unlike remove-ai-slops it targets one seam or smell.
----
-
-# 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

@@ -1,20 +0,0 @@
----
-name: remove-ai-slops
-description: Use when a task asks to remove AI-generated code smells from an explicit diff or file scope without behavior changes; do not use for general refactors, features, bug fixes, or repository-wide cleanup. Produces behavior-locked removal of proven smell instances; unlike refactor it may cover several categories in fixed scope.
----
-
-# 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

@@ -1,16 +0,0 @@
----
-name: rules
-description: Use when a task asks how HolyCodex rules are discovered, matched, injected, deduplicated, limited, cached, or why rule loading is wrong; do not use merely because repository instructions exist or for skill routing. Produces an evidence-backed rule trace without exposing unrelated content; unlike general debugging it owns this pipeline.
----
-
-# 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` accepts quoted or unquoted scalar, inline array, or multiline array. 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

@@ -1,38 +0,0 @@
----
-name: security-research
-description: Use when an authorized task needs repository security review, threat analysis, vulnerability validation, or attack-path and exploitability proof; do not use for generic review, ordinary debugging, unsupported hardening claims, or real-system attacks. Produces evidence-calibrated findings and minimum fixes; unlike debugging it evaluates attacker reachability and impact.
----
-
-# 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.