diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000..dbcfa9d --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,9 @@ +# Default owners — every PR auto-requests review from this team. +# Replace @Wizwam/platform-maintainers with the actual GitHub team handle. +* @Wizwam/platform-maintainers + +# Path-scoped owners (uncomment and edit as the team grows): +# /admin/ @Wizwam/admin-owners +# /docs/ @Wizwam/docs +# /.github/ @Wizwam/platform-maintainers +# /lib/ @Wizwam/platform-maintainers diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..9e803c0 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,48 @@ +--- +name: Bug report +about: Something is broken or behaves incorrectly +title: "fix: " +labels: ["bug", "triage"] +assignees: [] +--- + +## Severity + +- [ ] **P0** — production down, data loss, security exposure (page on-call now) +- [ ] **P1** — core feature broken, no workaround, blocking users/agents +- [ ] **P2** — degraded but workaround exists +- [ ] **P3** — minor / cosmetic + +## Affected users / agents + + + +## What happened + + + +## Steps to reproduce + +1. +2. +3. + +## Expected behaviour + + + +## Environment + +- Service / app: +- Version / commit SHA: +- Host (browser, OS, deploy target): + +## Logs / screenshots + +```text + +``` + +## Suspected cause (optional) + + diff --git a/.github/ISSUE_TEMPLATE/chore.md b/.github/ISSUE_TEMPLATE/chore.md new file mode 100644 index 0000000..ab5cb01 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/chore.md @@ -0,0 +1,19 @@ +--- +name: Chore +about: Maintenance work — deps, refactor, docs, tooling, CI +title: "chore: " +labels: ["chore"] +assignees: [] +--- + +## What + + + +## Why now + + + +## Done when + +- [ ] diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..b052292 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,8 @@ +blank_issues_enabled: false +contact_links: + - name: Wizwam Trust Charter + url: https://github.com/Wizwam/charter + about: Governance, ten commandments, and how decisions get made. + - name: Security disclosure + url: mailto:security@wizwam.com + about: Report a vulnerability privately. Do not open a public issue. diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..964ec18 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,39 @@ +--- +name: Feature request +about: Propose new behaviour or capability +title: "feat: " +labels: ["feature", "triage"] +assignees: [] +--- + +## User story + +> As a **[role — human user / operator / agent / tenant]**, +> I want **[capability]**, +> so that **[outcome / value]**. + +## Problem + + + +## Proposed solution + + + +## Alternatives considered + + + +## Acceptance criteria + +- [ ] +- [ ] +- [ ] + +## Out of scope + + + +## Charter / policy notes (optional) + + diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..589b97a --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,56 @@ + + + +## Summary + + + +## Linked issue + +Closes # + +## Type of change + +- [ ] `feat` — new behaviour +- [ ] `fix` — bug fix +- [ ] `chore` — maintenance / deps / tooling +- [ ] `docs` — documentation only +- [ ] `refactor` — internal change, no behaviour change +- [ ] `test` — tests only + +## How to test + + + +1. +2. + +## Screenshots / recordings (UI changes) + + + +## Risk & rollback + +- **Blast radius:** local / single service / cross-service / data migration +- **Rollback plan:** revert this PR / requires data fix / forward-fix only +- **Breaking change?** No / Yes — describe the API/behaviour break and the migration path +- **Performance impact:** None expected / measured (attach numbers) / unknown — needs review + +## Checklist + +- [ ] Title follows Conventional Commits +- [ ] Linked issue references with `Closes #` +- [ ] Tests added or updated (or reason given for none) +- [ ] Docs updated (README, CLAUDE.md, AGENTS.md, runbooks) if behaviour changed +- [ ] No secrets, tokens, or `.env` files committed +- [ ] CI is green + +## Charter notes (if applicable) + + diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..c2708ef --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,35 @@ +version: 2 +updates: + - package-ecosystem: npm + directory: "/" + schedule: + interval: weekly + day: monday + time: "06:00" + timezone: America/Toronto + open-pull-requests-limit: 5 + commit-message: + prefix: "chore(deps)" + include: scope + labels: + - chore + - dependencies + groups: + minor-and-patch: + update-types: + - minor + - patch + + - package-ecosystem: github-actions + directory: "/" + schedule: + interval: weekly + day: monday + time: "06:00" + timezone: America/Toronto + commit-message: + prefix: "chore(ci)" + include: scope + labels: + - chore + - ci diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..217f5a4 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,109 @@ +# Contributing to Wizwam + +This file documents the **universal workflow** used across every Wizwam repo. Every repo under [github.com/Wizwam](https://github.com/orgs/Wizwam/repositories) follows the same flow so contributors — human or AI (Claude Code, GitHub Copilot, OpenAI Codex) — can move between repos without relearning conventions. + +## The flow + +``` +Issue (#123) → Branch (feat/123-slug) → Commits → PR → Review → Squash-merge → Issue auto-closes +``` + +Three layers, three artefacts: + +| Layer | What | Where | +|---|---|---| +| **Intent** | What we want to build / fix | GitHub Issue (uses an issue template) | +| **Work** | The diff in progress | A branch, named after the issue | +| **Delivery** | Proposed change for review | Pull Request (uses the PR template) | + +## 1. Open an issue first + +Every change starts with an issue. Use the templates: + +- **Bug** → `bug_report.md` (title prefix `fix:`) +- **Feature** → `feature_request.md` (title prefix `feat:`) +- **Maintenance** → `chore.md` (title prefix `chore:`) + +Only skip the issue for one-line typo fixes. + +## 2. Branch naming + +``` +/- +``` + +Examples: + +- `feat/42-voicedna-export` +- `fix/87-approval-timeout` +- `chore/bump-anthropic-sdk` +- `docs/contributing-flow` + +`` matches Conventional Commits: `feat`, `fix`, `chore`, `docs`, `refactor`, `test`. + +## 3. Commits — Conventional Commits + +``` +(): + + + + +``` + +Examples: + +``` +feat(voicedna): add CSV export endpoint +fix(approvals): handle 30s broker timeout +chore(deps): bump @anthropic-ai/sdk to 0.39 +docs(readme): clarify install steps +``` + +Why: GitHub renders these nicely, every modern AI tool understands them, and changelog generators can read them automatically. + +## 4. Pull Request + +- Use the `PULL_REQUEST_TEMPLATE.md` — it auto-loads. +- PR title = the squash-merge commit message → must follow Conventional Commits. +- Body must include `Closes #` so the issue auto-closes on merge. +- CI must be green before merge. +- At least one approving review from a CODEOWNER. + +## 5. Merging + +- **Default:** squash-merge. Keeps `main` history linear and readable. +- **Exception:** long-lived feature branches with meaningful commit history may use a merge commit, by maintainer decision. +- After merge: branch is auto-deleted, issue auto-closes. + +## Labels (standard set) + +| Label | Meaning | +|---|---| +| `bug` | Something is broken | +| `feature` | New capability | +| `chore` | Maintenance | +| `docs` | Documentation only | +| `triage` | Needs maintainer review | +| `good-first-issue` | Onboarding-friendly | +| `blocked` | Waiting on something external | +| `security` | Security-relevant — handle privately first | + +## Working with AI agents + +This repo includes both `CLAUDE.md` (Claude Code instructions) and `AGENTS.md` (OpenAI Codex / Copilot instructions). When you ask any agent to make a change, ask it to: + +1. Open or reference an issue. +2. Create a branch using the convention above. +3. Use Conventional Commits. +4. Open a PR using the template. + +That way the same workflow applies regardless of which tool produced the diff. + +## Security + +Do **not** open public issues for vulnerabilities. Email `security@wizwam.com`. See `SECURITY.md` for the full policy. + +## Governance + +Substantial decisions (architecture, data handling, third-party integrations) reference the [Wizwam Trust Charter](https://github.com/Wizwam/charter). Cite the relevant section in the PR description when applicable. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..b540651 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,22 @@ +# Security Policy + +## Reporting a vulnerability + +Email **security@wizwam.com** with: + +- A description of the issue +- Steps to reproduce +- The affected version / commit SHA +- Your assessment of impact + +Please do **not** open a public GitHub issue for security reports. + +## What to expect + +- Acknowledgement within 3 business days. +- A coordinated disclosure timeline agreed with the reporter. +- Credit in the release notes (unless you prefer to remain anonymous). + +## Supported versions + +Only the `main` branch and the most recent tagged release receive security fixes.