Prepare WhyThis for public OSS publication

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,49 @@
+name: Bug report
+description: Report incorrect archaeology, indexing, or CLI behavior
+title: "[Bug]: "
+body:
+  - type: markdown
+    attributes:
+      value: "Thanks for reporting a bug. Do not include secrets, private repository data, or vulnerability details here."
+  - type: input
+    id: version
+    attributes:
+      label: WhyThis version or commit
+      placeholder: "v0.x.y or commit SHA"
+    validations:
+      required: true
+  - type: textarea
+    id: problem
+    attributes:
+      label: What happened?
+      description: Describe the observed result and what you expected instead.
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Minimal reproduction
+      description: Include the command and, when possible, a small synthetic Git history that demonstrates the issue.
+    validations:
+      required: true
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: OS, Go version, Git version, harness (if any), and shallow/full clone status.
+    validations:
+      required: true
+  - type: textarea
+    id: output
+    attributes:
+      label: Sanitized output
+      render: shell
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Checks
+      options:
+        - label: I removed credentials and private repository content.
+          required: true
+        - label: This is not a security vulnerability.
+          required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Security policy
+    url: https://github.com/Rayfts/WhyThis/security/policy
+    about: Please read the security policy before reporting sensitive vulnerabilities.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,34 @@
+name: Feature request
+description: Propose a new archaeology, evidence, or integration capability
+title: "[Feature]: "
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What maintenance or code-archaeology problem are you trying to solve?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed behavior
+      description: Describe the CLI/API/TUI behavior or evidence source you want.
+    validations:
+      required: true
+  - type: textarea
+    id: provenance
+    attributes:
+      label: Provenance model
+      description: If this adds evidence, how can WhyThis show where it came from and distinguish fact from inference?
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Checks
+      options:
+        - label: I checked for an existing issue describing the same request.
+          required: true

.github/pull_request_template.md

@@ -0,0 +1,19 @@
+## Summary
+
+Describe the change and the archaeology/maintenance problem it solves.
+
+## Evidence impact
+
+Does this alter FACT / INFERENCE / UNKNOWN classification, provenance, risk scoring, Git traversal, indexing, or harness capability claims? Explain or write `None`.
+
+## Validation
+
+List tests, fixture histories, benchmarks, or commands used to validate the change.
+
+## Checklist
+
+- [ ] I kept deterministic evidence separate from AI interpretation.
+- [ ] New evidence retains provenance and a reproducible locator/revision.
+- [ ] I added or updated tests for behavior changes.
+- [ ] I did not invent undocumented harness behavior.
+- [ ] I updated relevant docs or changelog entries.

CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+This file records notable user-facing changes to WhyThis. The project is currently pre-1.0, so CLI and evidence-format details may evolve while the deterministic archaeology model stabilizes.
+
+## Unreleased
+
+No tagged public release has been declared yet. Future features, fixes, evidence-model changes, compatibility changes, and security-relevant behavior changes should be summarized here before release.
+
+## Initial public foundation
+
+The current foundation includes deterministic Git archaeology, incremental SQLite indexing, GitHub enrichment, explainable historical-risk analysis, a local API/TUI, FACT / INFERENCE / UNKNOWN separation, and the initial coding-agent adapter set. Earlier development history is preserved in Git.

CODE_OF_CONDUCT.md

@@ -1,5 +1,25 @@
 # Code of Conduct
 
-We expect project participation to be professional, respectful and focused on improving the software. Harassment, threats, discriminatory abuse, doxxing and deliberate disruption are not acceptable in project spaces.
+WhyThis is an open-source engineering project. We want discussion, review, and collaboration to remain useful, respectful, and safe for everyone participating.
 
-Maintainers may remove content or restrict participation when needed to protect contributors and the project. Security reports should use the private process described in `SECURITY.md`.
+## Expected behavior
+
+- Discuss code, evidence, and ideas on their merits.
+- Give specific, actionable feedback and assume good faith where reasonable.
+- Respect different experience levels, backgrounds, and communication styles.
+- Keep disagreement focused on the work rather than the person.
+- Protect private information and security-sensitive material.
+
+## Unacceptable behavior
+
+Harassment, threats, discriminatory or sexualized language, doxxing, personal attacks, intimidation, deliberate disruption, or publishing another person's private information without permission are not acceptable.
+
+## Scope
+
+This policy applies to issues, pull requests, reviews, discussions, project-managed community spaces, and direct interactions connected to WhyThis.
+
+## Enforcement
+
+Maintainers may edit or remove abusive content, close or lock threads, reject contributions, or restrict participation when behavior materially harms contributors or the project. Responses should be proportionate and focused on restoring productive participation.
+
+For concerns that should not be handled publicly, use a private repository contact mechanism when available. Do not place personal, confidential, or security-sensitive information in a public issue.

CONTRIBUTING.md

@@ -1,30 +1,42 @@
-# Contributing
+# Contributing to WhyThis
 
-Thanks for helping improve WhyThis.
+Thanks for helping improve WhyThis. Useful contributions include Git-history retrieval, evidence modeling, indexing, GitHub enrichment, TUI/API work, harness adapters, performance improvements, fixtures, and documentation.
 
-## Development
+The project's central rule is simple: **never answer “why” without showing the evidence.**
 
-Use Go 1.27 or newer and Git. Then run:
+## Development setup
+
+WhyThis requires Go 1.27+ and the native `git` executable.
 
 ```bash
-go mod download
 make fmt
 make vet
 make test
 make race
+make bench
+```
+
+For focused development, normal Go commands are also fine:
+
+```bash
+go test ./...
+go vet ./...
+go build ./cmd/whythis
 ```
 
-Before opening a pull request, add or update tests for archaeology behavior. Prefer synthetic repositories whose history is intentionally constructed and whose expected evidence can be asserted exactly.
+## Design rules
 
-## Evidence integrity rules
+1. Git/GitHub-derived observations are **FACTS**; agent interpretation is **INFERENCE**.
+2. Unknown history stays **UNKNOWN**. Do not turn absence of evidence into a confident explanation.
+3. Prefer native Git behavior for blame, rename tracking, ancestry, pickaxe, and line history rather than reimplementing semantics loosely.
+4. Historical-risk scores must remain deterministic, explainable, and independent of LLM output.
+5. New evidence nodes/edges must preserve provenance and a stable locator/revision where possible.
+6. Harness adapters may synthesize evidence but must not become the source of historical facts.
+7. Do not invent third-party flags or capabilities; cite upstream source/docs in adapter changes.
+8. Add fixtures or regression tests for archaeology edge cases such as renames, reverts, deleted files, merges, shallow history, and rebases.
 
-- Keep Go source files at or below 300 lines; split by responsibility when they grow beyond that boundary.
-- Do not add a FACT unless a deterministic collector can point to its provenance.
-- Do not parse an LLM response into deterministic evidence.
-- Keep Git process execution inside `internal/gitx`.
-- If a harness integration changes, cite current upstream source/docs in `docs/harnesses.md` and add capability tests.
-- Do not silently ignore shallow history, GitHub rate limits, parse failures or missing credentials.
+## Pull requests
 
-## Changes
+Keep PRs focused and explain the evidence path affected. Include tests for behavior changes, benchmark notes for expensive history/indexing changes, and documentation updates when CLI/API output or evidence semantics change.
 
-Keep commits focused. Public behavior and new evidence relations should be documented. Security-sensitive changes should follow `SECURITY.md`.
+Security-sensitive changes should follow `SECURITY.md`. By contributing, you agree to follow `CODE_OF_CONDUCT.md` and the Apache-2.0 license terms.

SECURITY.md

@@ -1,11 +1,22 @@
-# Security policy
+# Security Policy
 
-Please report security vulnerabilities privately through GitHub's security advisory flow for this repository when available. Do not open a public issue containing exploit details, credentials or sensitive repository history.
+WhyThis reads repository history, optionally queries GitHub, and can pass collected evidence to external coding-agent harnesses. Treat repositories, commit messages, issue text, review text, and harness output as untrusted input.
 
-## Scope
+## Reporting a vulnerability
 
-Security-relevant areas include command construction, path handling, GitHub token handling, HTTP server exposure, SQLite/cache integrity, harness process isolation, prompt/evidence leakage and unsafe parsing of untrusted repository metadata.
+Do not publish exploit details, credentials, private repository contents, or token-exposure bugs in a public issue.
 
-WhyThis does not require a GitHub token for local Git analysis. Tokens are read from environment variables and must never be written into evidence, logs or cache keys. Harness synthesis may transmit the evidence included in a prompt to the configured model/provider; users are responsible for ensuring that repository history is appropriate to send to that provider.
+If GitHub private vulnerability reporting is enabled, use **Security → Report a vulnerability**. Otherwise, open a minimal non-sensitive issue requesting a private reporting channel.
 
-The local HTTP API binds to loopback by default and currently has no authentication. Do not expose it directly to an untrusted network.
+Include the affected commit/version, operating system, minimal reproduction, impact, and whether the issue can expose repository data, GitHub credentials, local files, or execute unintended commands.
+
+## Security boundaries
+
+- Harness output is inference, never historical evidence.
+- Harness synthesis should use temporary working directories and should not require write access to the analyzed repository.
+- GitHub tokens should be narrowly scoped and are used only when enrichment is requested/configured.
+- The local HTTP API binds to loopback by default. Authentication is not currently provided; do not expose it directly to untrusted networks.
+- Do not place secrets in prompts, commit messages, issue bodies, exported evidence, screenshots, or fixtures.
+- Repository text rendered in the TUI/API must be treated as data, not instructions.
+
+A security fix that changes evidence interpretation should include tests proving that provenance and FACT / INFERENCE / UNKNOWN separation are preserved.

SUPPORT.md

@@ -0,0 +1,30 @@
+# Support
+
+WhyThis is a pre-1.0 open-source project. Support is community-driven and best-effort; there is no guaranteed response time or commercial SLA.
+
+## Before opening an issue
+
+Check the README and documents under `docs/`, then run:
+
+```bash
+whythis doctor
+whythis harnesses
+```
+
+For harness-specific questions, include the harness name/version and `whythis capabilities <id>` output when safe to share.
+
+## Bugs
+
+Use the bug-report form. Include the WhyThis commit/version, Git version, Go version, OS, the target command, and a small repository/history that demonstrates the problem when possible. Sanitized command output is useful; private repository content should not be posted accidentally.
+
+## Feature requests
+
+Use the feature-request form and describe the archaeology or maintenance problem first. For new evidence sources, explain how provenance can be preserved and how the feature behaves without an AI harness.
+
+## Security
+
+Do not report vulnerabilities through a normal issue. Follow `SECURITY.md`.
+
+## Questions
+
+Focused usage questions are welcome as GitHub issues when the README/docs do not already answer them. Keep one topic per issue so answers remain searchable.