Onboarding docs + handoff guide

.gitattributes

@@ -0,0 +1,15 @@
+# Default: normalize line endings in the repo checkout.
+* text=auto
+
+# Unix-style scripts and CI configs
+*.sh text eol=lf
+.github/**/*.yml text eol=lf
+
+# Python sources
+*.py text eol=lf
+
+# Markdown and docs
+*.md text eol=lf
+
+# Windows batch files (if any)
+*.bat text eol=crlf

.github/CODEOWNERS

@@ -0,0 +1,6 @@
+# See https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
+#
+# Uncomment and set one or more GitHub usernames or @org/team-name entries.
+# Teams must exist in the org and have visibility to this repository.
+#
+* @wpak-ai

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,59 @@
+name: Bug report
+description: File a bug report to help us improve paperscout
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to fill out this bug report.
+        **Do not** use this form for security vulnerabilities — follow **[SECURITY.md](../SECURITY.md)** (private reporting).
+
+  - type: textarea
+    id: summary
+    attributes:
+      label: Summary
+      description: What went wrong, in one short paragraph?
+    validations:
+      required: true
+
+  - type: textarea
+    id: repro
+    attributes:
+      label: Steps to reproduce
+      description: How can a maintainer reproduce the issue?
+      placeholder: |
+        1. …
+        2. …
+        3. …
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: Version / commit
+      description: Git SHA or release tag, if known
+    validations:
+      required: false
+
+  - type: textarea
+    id: env
+    attributes:
+      label: Environment
+      description: OS, Python version, Docker vs bare metal, etc.
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,2 @@
+blank_issues_enabled: true
+contact_links: []

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,34 @@
+name: Feature request
+description: Suggest an idea for paperscout
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem / motivation
+      description: What user or operator problem does this solve?
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: What would you like to see happen?
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+    validations:
+      required: false
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional context
+      description: Links, screenshots, Slack behavior, etc.
+    validations:
+      required: false

.github/dependabot.yml

@@ -0,0 +1,13 @@
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 10
+
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 10

.github/pull_request_template.md

@@ -0,0 +1,12 @@
+## Summary
+
+<!-- What does this PR change and why? -->
+
+## Test plan
+
+- [ ] `./run check` (or `make check`)
+- [ ] `pre-commit run --all-files`
+
+## Related issues
+
+<!-- Link issues: Fixes #123 -->

.github/workflows/ci.yml

@@ -7,6 +7,29 @@ on:
     branches: [main, develop]
 
 jobs:
+  lint:
+    name: Lint (pre-commit)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Cache pre-commit environments
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pre-commit
+          key: pre-commit-${{ runner.os }}-${{ hashFiles('.pre-commit-config.yaml') }}
+
+      - name: Run pre-commit
+        run: pre-commit run --all-files
+
   test:
     name: Test (Python ${{ matrix.python-version }})
     runs-on: ubuntu-latest

.github/workflows/codeql.yml

@@ -0,0 +1,33 @@
+name: CodeQL
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+  schedule:
+    - cron: "0 12 * * 1"
+
+jobs:
+  analyze:
+    name: Analyze (Python)
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write
+      actions: read
+      contents: read
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v3
+        with:
+          languages: python
+
+      - name: Autobuild
+        uses: github/codeql-action/autobuild@v3
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v3

.pre-commit-config.yaml

@@ -0,0 +1,17 @@
+# See https://pre-commit.com
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+        args: ["--maxkb=800"]
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.9.6
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format

.vscode/settings.json

@@ -1,3 +1,3 @@
 {
     "python-envs.pythonProjects": []
-}
+}

CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- Open-source hygiene: contributing guide, security policy, code of conduct, onboarding and handoff docs, pre-commit (Ruff), GitHub issue templates, Dependabot, CodeQL, CODEOWNERS template, and `.gitattributes`.
+
+## [0.1.0] - 2026-05-05
+
+### Added
+
+- Initial public release as tracked in `pyproject.toml` (WG21 paper tracking, Slack integration, PostgreSQL storage, Docker deploy, CI/CD workflows).

CONTRIBUTING.md

@@ -0,0 +1,72 @@
+# Contributing to paperscout
+
+Thank you for your interest in improving paperscout. This document describes how we work, how to run checks locally, and how releases are cut.
+
+## Where to start
+
+- **[docs/onboarding.md](docs/onboarding.md)** — clone, database, `.env`, tests, and running the app locally.
+- **[docs/handoff.md](docs/handoff.md)** — maintainer-oriented design notes and operational gotchas.
+- **[README.md](README.md)** — product behavior, Slack setup, deployment, and environment variable tables.
+
+## Workflow
+
+1. **Fork** the repository (if you lack direct push access) and **clone** your fork.
+2. Create a **feature branch** from the active integration branch (currently `develop`; confirm repo default/protection rules before opening).
+3. Make focused commits with clear messages.
+4. Open a **pull request** against the designated target branch (`develop` or `main`, per current release flow). Use the PR template; link related issues when applicable.
+5. Ensure **CI is green** (tests + coverage + lint hooks — see below).
+
+### Code owners
+
+[`.github/CODEOWNERS`](.github/CODEOWNERS) routes review requests. If GitHub reports unknown owners, maintainers should update that file with real `@username` or `@org/team` entries and ensure the team exists and has repository access.
+
+## Local checks
+
+Install the package in editable mode with dev dependencies:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate   # Windows Git Bash: source .venv/Scripts/activate
+pip install -e ".[dev]"
+```
+
+### Tests and coverage
+
+```bash
+./run check          # pytest + coverage, fails under 90% line coverage (matches CI)
+# or: make check
+```
+
+CI runs `pre-commit run --all-files` for pushes/PRs on configured branches (currently `main` and `develop`; see `.github/workflows/ci.yml`).
+
+### Lint and format (Ruff + pre-commit)
+
+We use **[pre-commit](https://pre-commit.com/)** with **[Ruff](https://docs.astral.sh/ruff/)** for linting and formatting.
+
+```bash
+pre-commit install
+pre-commit run --all-files
+```
+
+CI runs `pre-commit run --all-files` on every push and pull request (see the `lint` job in `.github/workflows/ci.yml`).
+
+## Expectations for changes
+
+- **Tests** — Add or update tests for behavior changes. Keep coverage at or above the project floor (**90%**).
+- **Docs** — Update README, onboarding, or handoff when you change operator-visible behavior, env vars, or deployment steps.
+- **Style** — Let Ruff format the tree; avoid unrelated drive-by reformatting of untouched files in the same PR when possible.
+
+## Releases
+
+We follow **[Semantic Versioning](https://semver.org/)** and **[Keep a Changelog](https://keepachangelog.com/)** principles.
+
+1. **Version** — Bump `version` in [`pyproject.toml`](pyproject.toml) (e.g. `0.1.0` → `0.2.0`).
+2. **Changelog** — Move items from `## [Unreleased]` to a new section `## [x.y.z] - YYYY-MM-DD` in [`CHANGELOG.md`](CHANGELOG.md).
+3. **Tag** — Create an annotated tag: `git tag -a v0.2.0 -m "Release v0.2.0"` and push it: `git push origin v0.2.0`.
+4. **GitHub Release** — On GitHub, create a **Release** from that tag and paste the changelog section for that version into the release notes.
+
+Optional follow-ups (not required today): PyPI publishing workflow, signed tags, or automated release notes.
+
+## Questions
+
+Use **GitHub Issues** for bugs and feature ideas (see issue templates). For organizational or access questions, contact the **CppAlliance** maintainers responsible for this repository (replace with a concrete contact when publishing internally).

README.md

@@ -7,6 +7,10 @@ WG21 C++ paper tracker with ISO draft probing and Slack notifications.
 
 A Python project that probes the isocpp.org paper system for unpublished D-paper drafts, monitors for new paper assignments at the frontier, and notifies a Slack channel when watched authors publish.
 
+**Docs:** [Developer onboarding](docs/onboarding.md) (clone → DB → tests → run) · [Maintainer handoff](docs/handoff.md) · [Contributing](CONTRIBUTING.md) · [Changelog](CHANGELOG.md) · [Security](SECURITY.md) · [Code of conduct](CODE_OF_CONDUCT.md)
+
+If you only need to run tests or a local instance, start with **onboarding** before the Slack app sections below.
+
 ## Features
 
 - **Per-user watchlists** -- each user manages their own list of authors and paper numbers via DM; the scout sends a personal DM when a match is found
@@ -226,6 +230,7 @@ All parameters are configurable via environment variables or a `.env` file. See
 | Variable                | Default | Description                                            |
 | ----------------------- | ------- | ------------------------------------------------------ |
 | `POLL_INTERVAL_MINUTES` | `30`    | Main polling cycle interval                            |
+| `POLL_OVERRUN_COOLDOWN_SECONDS` | `300` | Minimum sleep after a poll cycle that overran the interval (avoids tight loops when work or errors stretch a cycle) |
 | `ENABLE_BULK_WG21`      | `true`  | Fetch wg21.link/index.json each cycle                  |
 | `ENABLE_BULK_OPENSTD`   | `true`  | Reserved for open-std.org scraping (not yet scheduled) |
 | `ENABLE_ISO_PROBE`      | `true`  | Run isocpp.org HEAD probing each cycle                 |

SECURITY.md

@@ -0,0 +1,25 @@
+# Security policy
+
+## Supported versions
+
+| Version | Supported          |
+| ------- | ------------------ |
+| `main`  | Yes — latest fixes |
+| Tags    | Best-effort — use the latest tag for production |
+
+Older branches may not receive backports unless agreed with maintainers.
+
+## Reporting a vulnerability
+
+**Please do not** file a public GitHub issue for undisclosed security vulnerabilities.
+
+Instead:
+
+1. Use **[GitHub private vulnerability reporting](https://docs.github.com/en/code-security/security-advisories/guidance-on-reporting-and-writing-information-about-vulnerabilities/privately-reporting-a-security-vulnerability)** for this repository (if enabled by org settings), **or**
+2. Email or contact the **CppAlliance / repository maintainers** through an internal channel your organization documents for security.
+
+Maintainers will acknowledge receipt as soon as practical, investigate, and coordinate a fix and disclosure timeline with you.
+
+## Scope
+
+This policy covers the **paperscout** application code, Docker image, and GitHub workflows in this repository. Infrastructure (servers, PostgreSQL host hardening, Slack workspace policy) is out of scope here but should follow your organization’s security baseline — see [`deploy/SERVER_SETUP.md`](deploy/SERVER_SETUP.md) for deployment hardening notes.