docs: public-readiness community files (SECURITY, CONTRIBUTING, CoC)

CODE_OF_CONDUCT.md

@@ -0,0 +1,133 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+**ernest@thedataexperts.us**.
+
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

CONTRIBUTING.md

@@ -0,0 +1,134 @@
+# Contributing to conclave
+
+Thanks for helping improve conclave — a bring-your-own-keys multi-model council
+for the CLI and as a Python library. Contributions are held to a clear bar:
+tests green, the **BYO-keys** posture preserved, and the design specs in `docs/`
+kept authoritative. This guide gets you set up and explains the rules that keep
+the project trustworthy.
+
+By participating you agree to the [Code of Conduct](CODE_OF_CONDUCT.md). Never
+report security vulnerabilities as public issues or PRs — follow
+[`SECURITY.md`](SECURITY.md).
+
+---
+
+## Dev setup
+
+conclave requires **Python ≥ 3.11**. Use a project-local virtual environment.
+
+```bash
+# from a clone of this repo
+python -m venv .venv
+.venv/bin/pip install -e ".[dev]"
+
+# the CLI is then available as:
+.venv/bin/conclave --help
+```
+
+`uv` works too if you prefer it (`uv venv .venv && uv pip install --python
+.venv/bin/python -e ".[dev]"`).
+
+conclave never needs real API keys to develop or test against — the suite mocks
+the httpx transport, so it runs fully offline. You only need real keys (set as
+environment variables) to make live calls.
+
+---
+
+## Running tests
+
+```bash
+# full suite
+.venv/bin/python -m pytest -q
+
+# a single file or test
+.venv/bin/python -m pytest tests/test_council.py -q
+.venv/bin/python -m pytest tests/test_modes.py::test_debate_dropout -q
+```
+
+The suite is **offline and key-free**: `tests/conftest.py` mocks the httpx
+transport so no network call or credential is ever made. A change is not done
+until `.venv/bin/python -m pytest -q` is fully green. CI runs the same suite on
+Python 3.11 / 3.12 / 3.13, plus `ruff` (lint + format) and a coverage floor and
+a `gitleaks` secret scan — all five checks must pass to merge.
+
+---
+
+## The BYO-keys contract (read before touching internals)
+
+conclave's core promise is that a user's API keys are **never stored, logged, or
+serialized** — they are read from the environment by **variable name**, at call
+time, and used only to make the request. If your change touches any of the
+following, it must preserve that contract:
+
+- **Key resolution** (`registry.py`, `providers.py`) — keys are looked up by env
+  var name at call time. Never attach a key value to an object, a log record, a
+  `ModelAnswer`, or a `CouncilResult`. Key **presence** logic may be exposed;
+  key **values** never.
+- **Error capture** (`providers.py`, `adapters/base.py`) — provider error strings
+  can contain credentials echoed back by the upstream API. They MUST pass through
+  `redact()` before landing in `ModelAnswer.error` or any log. A change that adds
+  a new error path must route it through `redact()`.
+- **The `redact()` scrubber** (`adapters/base.py`) — it strips bearer tokens,
+  `sk-`/`x-api-key` shapes, and known env-var values. Detection must **never
+  weaken on a real secret** to reduce noise. Add coverage; do not drop it.
+- **`CouncilResult` / `ModelAnswer` serialization** (`models.py`) — these are the
+  stable downstream surface (the mcp-warden dev-time consumer keys on them). No
+  field may carry a credential, and the shape must stay backward-compatible
+  unless the change is intentional and version-bumped.
+
+Practical rules:
+
+- **No real secrets in the tree, ever.** Tests use obviously-synthetic,
+  clearly-fake placeholders. The repo runs a `gitleaks` scan on every push and PR.
+- **Adding a provider is one adapter registration.** Follow the existing pattern
+  in `adapters/` — register one adapter per provider family. An OpenAI-compatible
+  endpoint needs **no code**: it is configured under the `endpoints:` section of
+  `~/.conclave/config.yml`. Don't add a bespoke code path for something the
+  config seam already covers.
+- **`call_model` never raises.** The whole provider highway is partial-failure
+  resilient — a member that errors is captured as a failed `ModelAnswer`, not an
+  exception that aborts the council. Preserve that.
+
+---
+
+## The PDD is the source of truth
+
+`docs/PRODUCT_DESIGN_DOCUMENT.md` is the **canonical** product and architecture
+spec; the 3-core docs (`README.md`, `SYSTEM_CONTEXT_DIAGRAM.md`,
+`DOCUMENTATION_INDEX.md`) sit on top of it. When docs disagree, the PDD wins, and
+your PR must reconcile them. A behavior or surface change updates the relevant doc
+in the same PR.
+
+---
+
+## Proposing a feature
+
+Modes, providers, and output options are welcome. The path that gets a change
+merged:
+
+1. **Open an issue first** describing the use case and the proposed surface
+   (CLI flag / library API / config key). Roadmap items live as labeled issues.
+2. **Check the PDD.** If your change shifts scope, non-goals, or the provider bar
+   (§12), say how — the PDD decision history is authoritative.
+3. **Implement** following existing patterns (the provider highway, the mode
+   orchestration in `modes.py`, the `Council` API in `council.py`).
+4. **Test** it: cover the happy path, partial failure, and — for anything in the
+   key/error path — that no credential can leak.
+
+---
+
+## Pull request expectations
+
+Before you open a PR, confirm:
+
+- [ ] **Tests pass**: `.venv/bin/python -m pytest -q` is green.
+- [ ] **BYO-keys preserved.** No key value is stored, logged, or serialized; new
+      error paths route through `redact()`.
+- [ ] **No secrets.** No real credentials anywhere in the tree; fixtures use
+      obviously-fake placeholders. `gitleaks` is clean.
+- [ ] **Lint clean.** `ruff check` and `ruff format --check` pass.
+- [ ] **Docs in sync.** README/CLI reference updated if user-facing behavior or
+      flags changed; the PDD and 3-core docs stay accurate.
+- [ ] **Scoped commits** with a clear message describing the *why*.
+
+Thank you for keeping the council honest.

SECURITY.md

@@ -0,0 +1,93 @@
+# Security Policy
+
+conclave is a **bring-your-own-keys** multi-model council. It calls foundation-model
+APIs with the user's own credentials, read from the environment by **variable name
+only**. The most security-sensitive surface in the project is therefore key
+handling: a weakness that causes a real API key to be stored, logged, serialized,
+or echoed back to the user breaks the core trust promise. We treat reports against
+that surface as the highest priority.
+
+## Reporting a vulnerability
+
+**Do not open a public GitHub issue, pull request, or discussion for a security
+vulnerability.** Public disclosure before a fix is available puts every user's
+credentials at risk.
+
+Report privately through **either** channel (GitHub Security Advisories is
+preferred because it keeps the report, the fix, and the CVE in one place):
+
+1. **GitHub Security Advisories** — go to the repository's **Security** tab and
+   click **"Report a vulnerability"**
+   (<https://github.com/ernestprovo23/conclave/security/advisories/new>). This
+   opens a private advisory visible only to you and the maintainers.
+2. **Email** — `ernest@thedataexperts.us`. Use a clear subject line such as
+   `[conclave security]`. If you want to encrypt, say so in a first plaintext
+   email and we will arrange a key.
+
+### What to include
+
+A good report lets us reproduce and triage fast:
+
+- The conclave version or commit SHA.
+- The surface involved (`conclave ask` / `conclave providers`, or the library
+  entry points `Council.ask` / `debate` / `adversarial`), the mode, and the
+  relevant flags or config.
+- A minimal repro: the `~/.conclave/config.yml` (with key **names**, never
+  values), the provider/endpoint, and the input that triggers it. Strip or fake
+  any real credentials first.
+- The expected vs. actual behavior and the security impact — e.g. "a real key
+  appears unredacted in `ModelAnswer.error`", "a key value is written to a log
+  line", "`CouncilResult` JSON serialization leaks a credential", "the CLI prints
+  a key value".
+
+Reports that demonstrate a **credential leak** — a real key escaping into any
+result field, log, serialized payload, or terminal output — are the highest
+priority. The key-handling contract is: keys are read from the environment by
+name at call time, never stored on objects, never logged, never serialized; and
+provider error strings are scrubbed by `redact()` before they reach a result.
+
+## Supported versions
+
+Security fixes are issued for the latest minor series. Older series are not
+patched — upgrade to a supported release.
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 0.3.x   | :white_check_mark: |
+| < 0.3   | :x:                |
+
+> Pre-1.0 note: the public surface is still evolving. The supported series will
+> advance with each minor release; only the most recent `0.x` minor receives
+> security patches.
+
+## Response window
+
+We aim to:
+
+- **Acknowledge** your report within **3 business days**.
+- Provide an **initial assessment** (accepted / needs-info / not-a-vuln, with a
+  severity estimate) within **7 business days**.
+- Ship a fix or a documented mitigation for accepted, validated reports within
+  **30 days** of acknowledgement for high/critical severity, and on a best-effort
+  basis for lower severities.
+
+These are targets for a small maintainer team, not contractual SLAs. If a report
+stalls, a polite nudge to `ernest@thedataexperts.us` is welcome.
+
+## Disclosure & credit
+
+We follow coordinated disclosure. We will work with you on a disclosure timeline,
+publish a GitHub Security Advisory (and request a CVE where warranted) once a fix
+is available, and credit you in the advisory unless you ask to remain anonymous.
+
+## Scope notes for this repository
+
+- conclave never persists credentials. If you find a path where a key is written
+  to disk, a log, a result object, or stdout/stderr, that is in scope.
+- Reports about the upstream model providers themselves (OpenAI, Anthropic,
+  Google, xAI, Perplexity) or about third-party dependencies (httpx, pydantic,
+  typer) are best filed upstream — but tell us too if conclave's *use* of them is
+  exploitable.
+- conclave is a council aggregator, not a security control. The *content* a model
+  returns is not adjudicated for safety; that is out of scope. A leak of the
+  user's own credentials is the security boundary we defend.