add claude-obsidian

2026-05-28 10:57:16 +09:00
parent 1b07531a45
commit 72dad72703
205 changed files with 41703 additions and 80 deletions
@@ -0,0 +1,160 @@
+# Contributing to claude-obsidian
+
+Thanks for your interest in improving this plugin. claude-obsidian is a small, focused project; contributions that match its philosophy land quickly.
+
+## Philosophy
+
+Three constraints shape every change:
+
+1. **Read before write.** Every contribution starts by reading the affected files, their tests, and their callers. Removals break assumptions as often as additions.
+2. **Smallest unit that works.** No speculative abstraction. Complexity is earned, not anticipated. Three real callers minimum before an abstraction lands.
+3. **Failure is the spec.** Every new failure mode needs explicit handling. Untrusted input, network calls, and state changes need an explicit blast-radius answer.
+
+The full kernel lives in [`/best-practices`](https://github.com/AgriciDaniel/best-practices) (composable Claude Code skill). The pre-commit verifier agent at [`agents/verifier.md`](agents/verifier.md) enforces it for non-trivial changes.
+
+## Workflow
+
+### 1. Open an issue first (for non-trivial changes)
+
+For typo fixes, doc clarifications, or single-line changes, skip straight to a PR. For anything bigger:
+
+- Open an issue using the bug-report or feature-request template
+- Describe the problem, the proposed change, and the blast radius
+- Wait for a thumbs-up before investing time
+
+### 2. Fork + branch
+
+Contributions are accepted on the public canonical repo. Fork [`AgriciDaniel/claude-obsidian`](https://github.com/AgriciDaniel/claude-obsidian) on GitHub, then:
+
+```bash
+git clone https://github.com/<your-username>/claude-obsidian.git
+cd claude-obsidian
+git checkout -b your-feature-name
+```
+
+> ℹ️ The public repo (`AgriciDaniel/claude-obsidian`) is the canonical source of truth. Raise all PRs against it. AI Marketing Hub Pro members working from the early-access mirror (`AI-Marketing-Hub/claude-obsidian`) should target the public canonical too, so contributions land in one place.
+
+Branch names: `fix/...`, `feat/...`, `docs/...`, `refactor/...`.
+
+### 3. Set up locally
+
+The plugin runs anywhere Claude Code runs. For development:
+
+```bash
+# Run the hermetic test suite — required before submitting a PR
+make test
+
+# Optionally provision the v1.7 retrieval pipeline (requires consent for API egress)
+bash bin/setup-retrieve.sh
+
+# Optionally pick a methodology mode for testing the v1.8 routing
+bash bin/setup-mode.sh
+```
+
+### 4. Make the change
+
+Follow the six-cut kernel:
+- Read every file you're touching
+- Name new identifiers like the next reader is hostile
+- Smallest unit that works
+- Delete more than you add (when superseding)
+- Evidence over intuition (tests for new behavior)
+- Failure-mode + undo plan documented
+
+If you add a new skill, agent, script, or hook, also add a test under `tests/`. The 9 hermetic test suites are the project's safety net.
+
+### 5. Run the tests
+
+```bash
+make test
+```
+
+All 9 suites must pass (~1240 assertions). Tests are hermetic: no network, no ollama, no Anthropic API. If your change adds a network call, gate it behind a `--consent`/`--allow-egress`/env-var pattern matching `scripts/contextual-prefix.py` or `scripts/tiling-check.py`.
+
+### 6. Run the verifier (optional but recommended)
+
+For multi-file changes:
+
+```bash
+# After git add, before git commit, dispatch the verifier agent
+# (Claude Code: invoke agents/verifier.md on the staged diff)
+```
+
+The verifier applies the six-cut + agent kernel to your staged diff and returns findings in BLOCKER / HIGH / MEDIUM / LOW tiers. Address BLOCKER + HIGH before committing.
+
+### 7. Commit
+
+Commit message convention (Conventional Commits):
+
+```
+<type>(<scope>): <short description>
+
+<longer body if needed>
+```
+
+Types: `feat`, `fix`, `docs`, `chore`, `refactor`, `test`, `perf`, `style`.
+
+Example:
+```
+fix(wiki-mode): close path-traversal in route_path safe_name
+
+Sanitize routing input via safe_name() before string-concat into
+the vault-relative path. Adds 9 hermetic test assertions for traversal
+vectors. Closes audit finding S1.
+```
+
+### 8. Update CHANGELOG.md
+
+Add an entry under `## [Unreleased]` (create the section if needed). Follow the [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format:
+
+```markdown
+## [Unreleased]
+
+### Added
+- Description of new feature
+
+### Fixed
+- Description of bug fix
+```
+
+The maintainer will move your entry to a versioned section at release time.
+
+### 9. Open a PR
+
+Use the PR template. Required fields:
+- What changed
+- Why
+- How it was tested (paste `make test` output if relevant)
+- Audit/verifier results if applicable
+
+PRs are reviewed against the kernel. Expect feedback on naming, scope, and failure-mode coverage.
+
+## Testing standards
+
+- **Hermetic.** No network, no external services, no user-specific environment.
+- **Fast.** The full suite runs in under a minute.
+- **Deterministic.** Same input → same output, every time.
+- **Documented.** Every test asserts a named behavior, not a coincidence.
+
+If you can't make your test hermetic, ask in the issue whether a mocked alternative is acceptable.
+
+## What we will NOT merge
+
+- Code without tests for new behavior
+- Speculative abstractions (no real callers yet)
+- Network calls without an explicit consent gate
+- Path construction from user input without sanitization (see `scripts/wiki-mode.py:safe_name`)
+- Skills/agents that shell out without documenting the failure mode
+- Anything that breaks the existing test suite without a documented reason
+
+## Security
+
+Found a vulnerability? Do NOT open a public issue. See [SECURITY.md](SECURITY.md) for disclosure.
+
+## License
+
+By contributing, you agree your contributions are licensed under the [MIT License](LICENSE).
+
+## Code of Conduct
+
+Participation is governed by the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md).