Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
56 lines (40 loc) · 4.64 KB

CONTRIBUTING.md

File metadata and controls

56 lines (40 loc) · 4.64 KB

Contributing to Lich

An @enchanter-ai product.

Thanks for your interest in contributing. This document captures the conventions every sibling in the enchanter-ai ecosystem follows. Read CLAUDE.md before opening your first PR — it's the binding behavioral contract for the plugin.

Ground rules

  1. Zero external runtime deps. Hooks: bash + jq only. Scripts: Python 3.8+ stdlib only. If you need a new dep, open an issue first — the bar for adding one is high. Exception candidate under evaluation: tree-sitter Wasm for TypeScript parsing, tracked for Phase 2.
  2. Named algorithms. Every engine has an ID (M1–M7) and an academic-style name: [Method] [Domain] [Action] or [Inventor] [Structure]. Derivations live in docs/science/README.md. Active engines at launch: M1 Cousot Interval Propagation, M2 Falleri Structural Diff, M5 Bounded Subprocess Dry-Run, M6 Bayesian Preference Accumulation, M7 Zheng Pairwise Rubric Judgment.
  3. Managed agent tiers. Opus orchestrates / judges disagreement. Sonnet executes loops and default judging. Haiku validates shape and budget-fallback. Never route a Haiku task to Opus.
  4. Emu-style marketplace. Each sub-plugin ships .claude-plugin/plugin.json + {agents,commands,hooks,skills,state}/ + README.md.
  5. Diagrams from source-of-truth. docs/architecture/*.mmd + index.html are regenerated by docs/architecture/generate.py. Do not hand-edit. The full architecture narrative is at docs/architecture/lich-architecture.md.
  6. Non-duplication across siblings. Hydra owns security CWE taxonomy (R3) — Lich consumes hydra/plugins/vuln-detector/state/audit.jsonl findings as attention weights, never re-scans. Crow owns change classification (V1, V2) — Lich consumes, never peer-classifies.
  7. Honest numbers. M6 posteriors expose (α, β), not point estimates. M7 reports Cohen's Kappa per axis. M5 distinguishes confirmed-bug / timeout-without-confirmation / sandbox-error / input-synthesis-failed — never collapsed into a single binary.

Dev setup

git clone https://github.com/enchanter-ai/lich
cd lich
bash install.sh                                  # pre-flight checks, clone to ~/.claude/plugins/
cd docs/assets && npm install                    # renderer toolchain (mmdc + puppeteer + mathjax)
cd ../../ && bash tests/run-all.sh               # smoke tests

Before opening a PR

  1. Run the generator. python docs/architecture/generate.py — regenerates the four .mmd diagrams + index.html. Commit the result.
  2. Run the tests. bash tests/run-all.sh — every sub-plugin's tests/ dir must return zero.
  3. Verify the conduct modules are current. shared/vis/conduct/*.md are the universal behavioral contract. Compare against upstream (enchanter-ai/wixie); if they've drifted, rebase before proceeding.
  4. Check the brand standard. Every engine named with an M[1-9] ID. Every agent tiered. No sibling-identifier leaks (Myers-Diff, Jaccard-Cosine, Aho-Corasick, Markov Drift, etc. — these belong to siblings, not Lich). No hand-edited diagrams.
  5. Verify non-duplication. If your PR adds security-taint detection, Hydra R3 is the owner — send the PR there. If it adds change classification, Crow V1/V2 owns that.
  6. Verify M5 sandbox caps. Any PR that touches plugins/lich-sandbox/ must retain or strengthen the resource caps (RLIMIT_CPU, RLIMIT_AS, RLIMIT_NOFILE, RLIMIT_FSIZE, signal.alarm). Relaxation requires a documented security review.

Commit conventions

Conventional Commits. Scope by sub-plugin slug:

feat(lich-core): add interval widening threshold for language-specific bounds
fix(lich-sandbox): enforce RLIMIT_NOFILE before subprocess.run
feat(lich-preference): add quarterly re-prompt for disabled rules
docs(shared): update conduct/precedent.md with a new failure code
refactor(docs): move diagram config into mermaid.config.json

Scopes: sub-plugin slug (lich-core, lich-sandbox, lich-preference, lich-rubric, lich-python, lich-typescript, lich-verdict, full), shared, docs, tests, or repo for top-level.

Reporting issues

Open at https://github.com/enchanter-ai/lich/issues. Include: plugin version (from .claude-plugin/marketplace.json#metadata.version), Claude Code version, platform (POSIX or Windows — relevant for M5), repro steps, expected vs. actual.

Code of conduct

Be kind. Debate ideas, not people. The @enchanter-ai ecosystem is built on mutual trust that each sibling respects the others' contracts and event-bus boundaries — don't smuggle Hydra's job into Lich, don't smuggle Crow's classification into Lich. The siblings compose because each stays in its lane.
⚡