diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..b0bf8a8 --- /dev/null +++ b/.editorconfig @@ -0,0 +1,21 @@ +root = true + +[*] +charset = utf-8 +end_of_line = lf +insert_final_newline = true +trim_trailing_whitespace = true + +[*.{md,mdx}] +trim_trailing_whitespace = false + +[*.py] +indent_style = space +indent_size = 4 + +[*.{js,jsx,ts,tsx,json,yml,yaml,css,scss}] +indent_style = space +indent_size = 2 + +[Makefile] +indent_style = tab diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000..92bf797 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,10 @@ +# Default reviewer for repository changes. +* @CognitiveCodeAI + +# High-assurance areas. +/backend/app/acl/ @CognitiveCodeAI +/backend/app/auth/ @CognitiveCodeAI +/backend/app/qa/ @CognitiveCodeAI +/backend/app/services/highlighting.py @CognitiveCodeAI +/backend/alembic/ @CognitiveCodeAI +/.github/ @CognitiveCodeAI diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..04778cf --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,72 @@ +name: Bug report +description: Report reproducible behavior that is not working as expected +title: "[bug]: " +labels: + - bug +body: + - type: markdown + attributes: + value: | + Thanks for helping improve NPR. Do not include client documents, credentials, personal data, protected health information, or privileged legal material. + - type: textarea + id: summary + attributes: + label: What happened? + description: Describe the problem and its impact. + validations: + required: true + - type: textarea + id: expected + attributes: + label: What did you expect? + validations: + required: true + - type: textarea + id: reproduce + attributes: + label: Steps to reproduce + description: Provide the smallest safe reproduction you can. + placeholder: | + 1. Start the stack with ... + 2. Upload or query a synthetic document ... + 3. Observe ... + validations: + required: true + - type: dropdown + id: area + attributes: + label: Affected area + options: + - Ingestion or parsing + - Retrieval or ranking + - Answer generation or citations + - Evidence highlighting + - ACL, authentication, or tenant isolation + - Frontend + - Infrastructure or deployment + - Documentation + - Not sure + validations: + required: true + - type: textarea + id: environment + attributes: + label: Environment + description: Include OS, Python, Node, browser, deployment type, and relevant service versions. + validations: + required: true + - type: textarea + id: logs + attributes: + label: Sanitized logs or screenshots + description: Redact secrets and sensitive document content. + render: text + - type: checkboxes + id: checks + attributes: + label: Safety check + options: + - label: I removed secrets, private documents, and personal or regulated data. + required: true + - label: This is not a security vulnerability. Security reports belong in a private advisory. + required: true diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..3c47333 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,11 @@ +blank_issues_enabled: false +contact_links: + - name: Questions and usage help + url: https://github.com/CognitiveCodeAI/rag-main-2/discussions + about: Use Discussions for setup help, architecture questions, and show-and-tell. + - name: Report a security vulnerability privately + url: https://github.com/CognitiveCodeAI/rag-main-2/security/advisories/new + about: Do not disclose vulnerabilities in a public issue. + - name: Commercial support + url: https://cognitivecode.ai + about: Contact Cognitive Code for implementation and commercial support. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..0dc82d3 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,54 @@ +name: Feature request +description: Propose an improvement grounded in a concrete user need +title: "[idea]: " +labels: + - enhancement +body: + - type: textarea + id: problem + attributes: + label: What problem are you trying to solve? + description: Describe the workflow, user, and current limitation. + validations: + required: true + - type: textarea + id: outcome + attributes: + label: Desired outcome + description: Describe observable behavior rather than only an implementation. + validations: + required: true + - type: textarea + id: alternatives + attributes: + label: Alternatives considered + description: Note workarounds or designs you evaluated. + - type: dropdown + id: area + attributes: + label: Primary area + options: + - Ingestion or parsing + - Retrieval or ranking + - Answer generation or citations + - Evidence highlighting + - ACL, authentication, or tenant isolation + - Frontend + - Infrastructure or operations + - Documentation or developer experience + validations: + required: true + - type: textarea + id: safety + attributes: + label: Safety, privacy, and compatibility considerations + description: Identify effects on sensitive documents, permissions, provenance, APIs, migrations, or existing deployments. + validations: + required: true + - type: textarea + id: evidence + attributes: + label: Success criteria + description: Explain how this feature should be tested or measured. + validations: + required: true diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..e1b4e22 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,42 @@ +## What changed? + +Describe the user-visible and technical changes. + +## Why? + +Explain the problem, motivation, and linked issue (`Closes #123`) where applicable. + +## Risk and safety + +- What can fail? +- Does this affect ACLs, authentication, tenant isolation, citations, provenance, highlighting, migrations, external APIs, or stored data? +- What is the rollback path? + +## Validation + +- [ ] Relevant backend tests pass. +- [ ] Frontend tests, lint, type checking, and build pass when applicable. +- [ ] Integration tests cover affected service boundaries. +- [ ] Migrations were rehearsed in both directions when applicable. +- [ ] Documentation and configuration examples are updated. +- [ ] No secrets, client documents, personal data, or generated sensitive artifacts are included. + +List exact commands and results: + +```text +commands and results +``` + +## Evidence-sensitive checklist + +Complete when the change affects answers or source review: + +- [ ] Unsupported claims fail closed or abstain. +- [ ] Citations resolve only to authorized packed context. +- [ ] Wrong document, version, page, hash, or quote cannot be labeled verified. +- [ ] Approximate or unavailable evidence is clearly distinguished. +- [ ] Representative single-hop and multi-hop behavior was checked. + +## Notes for reviewers + +Call out the files, decisions, tradeoffs, or follow-up work that deserve extra attention. diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 9967df1..467b296 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -4,14 +4,20 @@ on: push: branches: ["main", "master"] pull_request: + workflow_dispatch: permissions: contents: read +concurrency: + group: ci-${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + jobs: backend-quality: name: Backend Quality runs-on: ubuntu-latest + timeout-minutes: 20 steps: - name: Checkout @@ -48,6 +54,7 @@ jobs: backend-integration: name: Backend Integration (security gate) runs-on: ubuntu-latest + timeout-minutes: 30 # Pin the connection config to the docker-compose defaults so the job does # not depend on a backend/.env (absent in CI) or any ambient runner env. @@ -96,7 +103,8 @@ jobs: - name: Initialize databases and storage working-directory: backend run: | - export PATH="$(python -c 'import sys,os;print(os.path.dirname(sys.executable))'):$PATH" + python_bin_dir="$(python -c 'import sys,os;print(os.path.dirname(sys.executable))')" + export PATH="${python_bin_dir}:$PATH" python -m scripts.setup.setup_postgres python -m scripts.setup.setup_minio python -m scripts.setup.setup_milvus @@ -125,6 +133,7 @@ jobs: frontend-quality: name: Frontend Quality runs-on: ubuntu-latest + timeout-minutes: 20 steps: - name: Checkout @@ -160,6 +169,7 @@ jobs: dependency-audit: name: Dependency Audit (non-blocking) runs-on: ubuntu-latest + timeout-minutes: 15 continue-on-error: true steps: diff --git a/.gitignore b/.gitignore index 5073edd..7fc69ef 100644 --- a/.gitignore +++ b/.gitignore @@ -144,5 +144,10 @@ test docs/ openapi.json nul +# Local evaluation, browser, and research artifacts +/output/ +/tmp/ +/.playwright-cli/ + # Claude Code local settings (machine-specific) .claude/settings.local.json diff --git a/CHANGELOG.md b/CHANGELOG.md index 07da1c3..8e7ff08 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,10 +14,17 @@ and this project aims to follow [Semantic Versioning](https://semver.org/spec/v2 - `CONTRIBUTING.md` - `SECURITY.md` - `.github/workflows/ci.yml` +- Professional repository governance: + - Code of Conduct, support, maintainer, and release guides + - structured bug and feature issue forms + - pull-request template and CODEOWNERS + - EditorConfig for consistent cross-platform formatting ### Changed - CI now validates backend unit tests and frontend lint/build on pull requests and pushes to default branches. +- CI now supports manual runs, cancels superseded branch runs, and applies job timeouts. +- README now presents verified setup requirements, project status, CI badges, navigation, and community links. ## [1.0.0] - YYYY-MM-DD diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..195713e --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,23 @@ +# Code of Conduct + +NPR adopts the [Contributor Covenant, version 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/) as its Code of Conduct. + +We are committed to a welcoming, respectful, and harassment-free community for everyone, regardless of background, identity, experience level, or area of expertise. Be constructive, assume good faith, and remember that this project handles software intended for evidence-sensitive workflows. + +## Expected behavior + +- Communicate respectfully and focus criticism on ideas and code. +- Welcome questions and help contributors learn the system safely. +- Protect confidential, personal, legal, clinical, and security-sensitive information. +- Disclose conflicts of interest that could affect a technical or governance decision. +- Respect maintainers' decisions about safety, scope, and release readiness. + +## Unacceptable behavior + +Harassment, discrimination, threats, doxxing, deliberate disclosure of confidential material, sustained disruption, and knowingly unsafe or misleading contributions are not acceptable. + +## Enforcement + +Report conduct concerns confidentially to [larry@cognitivecode.ai](mailto:larry@cognitivecode.ai). Maintainers will review reports promptly and discreetly and may edit or remove content, reject contributions, restrict participation, or take other proportionate action. + +_Attribution: adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1._ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7a690f0..8102722 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,76 +1,130 @@ -# Contributing +# Contributing to NPR -Thanks for helping improve NPR RAG. +Thank you for helping improve Near-Perfect RAG. NPR is designed for evidence-sensitive document workflows, so correctness, provenance, privacy, and clear validation matter as much as feature velocity. -## Development Setup +By participating, you agree to follow the [Code of Conduct](CODE_OF_CONDUCT.md). -1. Fork and clone the repository. -2. Run one of the setup scripts from repo root: - - Linux/macOS: `./setup.sh` - - Windows (PowerShell): `./setup.ps1` -3. Start the app: - - `python run.py` +## Before you begin -Key local endpoints: +- Use [GitHub Discussions](https://github.com/CognitiveCodeAI/rag-main-2/discussions) for questions and design exploration. +- Use the structured issue forms for reproducible bugs and concrete feature requests. +- Follow [SECURITY.md](SECURITY.md) for vulnerabilities; never disclose them in a public issue. +- Never upload client documents, privileged legal material, protected health information, personal data, or credentials. + +## Development setup + +Prerequisites: + +- Docker Desktop or Docker Engine with Compose +- Python 3.12 +- Node.js 20.9 or newer +- npm +- an OpenAI API key for embeddings, answer generation, and default OCR paths + +Clone and initialize: + +```bash +git clone https://github.com/CognitiveCodeAI/rag-main-2.git +cd rag-main-2 +./dev init +./dev up +``` + +Useful endpoints: - Frontend: `http://localhost:3000` -- API docs: `http://localhost:8000/docs` -- Health: `http://localhost:8000/health?check_services=true` +- API documentation: `http://localhost:8000/docs` +- Health check: `http://localhost:8000/health?check_services=true` + +See [SETUP.md](SETUP.md) for manual setup, troubleshooting, and platform notes. + +## Branch and pull-request workflow + +1. Create a focused branch from the latest `main`. +2. Keep unrelated changes in separate pull requests. +3. Use a concise conventional commit where practical, such as `feat:`, `fix:`, `docs:`, `test:`, `refactor:`, or `chore:`. +4. Complete the pull-request template, including risks, rollback, and exact test evidence. +5. Resolve review feedback and keep CI green. +6. Do not force-push shared branches or bypass repository safety rules. -## Branch and PR Workflow +## Code standards -- Create a feature branch from `main`. -- Keep changes focused and small when possible. -- Open a pull request with: - - What changed - - Why it changed - - How you tested it - - Any follow-up work +### Backend -## Code Standards +- Keep behavior deterministic where safety or auditability depends on it. +- Prefer explicit types, bounded work, actionable errors, and fail-closed handling. +- Add positive and negative tests for behavior changes. +- Preserve tenant and node ACL filtering before content reaches downstream models. +- Treat graph scores and model output as relevance signals, not verified truth. -### Backend (Python) +Run the default backend suite: -- Keep functions focused and testable. -- Prefer explicit error handling and actionable messages. -- Add comments only where intent is non-obvious. -- Add or update tests for behavior changes. +```bash +cd backend +venv/bin/python -m pytest -q +``` -Run backend checks: +Integration tests are opt-in and require the documented infrastructure: ```bash cd backend -pytest tests/test_acl_unit.py -q +RUN_INTEGRATION_TESTS=1 venv/bin/python -m pytest -q ``` -### Frontend (Next.js) +### Frontend -- Follow existing component and naming patterns. -- Keep UI changes accessible and responsive. -- Ensure lint and build pass before opening a PR. +- Follow existing React, TypeScript, accessibility, and component patterns. +- Preserve keyboard navigation, visible focus, meaningful labels, and responsive layouts. +- Do not label evidence verified unless the backend returned a verified record. Run frontend checks: ```bash cd frontend +npm test npm run lint +npx tsc --noEmit npm run build ``` -## Documentation Requirements +### Migrations + +- Use the next Alembic revision number and provide both `upgrade` and `downgrade` where safe. +- Test a clean migration to `head` and the affected downgrade/upgrade cycle. +- Document operational sequencing, data backfills, and rollback limitations. + +## High-assurance review requirements + +Changes involving authentication, ACLs, tenant isolation, retrieval, answer generation, citations, evidence highlighting, or document provenance must include: + +- exact allowed and denied cases; +- wrong-document, wrong-version, wrong-page, or stale-hash negative controls where applicable; +- proof that unavailable evidence is not promoted to verified; +- representative regression coverage; +- a safe fallback and rollback path; +- documentation that separates synthetic evaluation from production validation. + +## Documentation + +When behavior, setup, configuration, APIs, or operations change: + +- update `README.md`, `SETUP.md`, or the relevant runbook; +- keep commands copy/paste-ready and consistent with CI; +- update `CHANGELOG.md` under `Unreleased` for user-visible changes; +- remove stale instructions in the same pull request. + +## Reporting a bug -When behavior, setup, or APIs change: +Use the bug form and include: -- Update `README.md` and/or `SETUP.md`. -- Keep examples copy/paste-ready. -- Remove stale instructions in the same PR. +- environment and service versions; +- minimal safe reproduction steps; +- expected and actual behavior; +- sanitized logs or screenshots; +- the affected document type using synthetic data whenever possible. -## Reporting Bugs +## Review and release expectations -Please include: +Maintainers may request additional security, provenance, load, or domain evaluation before accepting a change. Passing unit tests does not by itself authorize a feature for legal, clinical, or other high-stakes production use. -- Environment (OS, Python version, Node version) -- Steps to reproduce -- Expected behavior -- Actual behavior -- Logs/screenshots if relevant +See [MAINTAINING.md](MAINTAINING.md) and [RELEASING.md](RELEASING.md) for stewardship and release policy. diff --git a/MAINTAINING.md b/MAINTAINING.md new file mode 100644 index 0000000..8cea969 --- /dev/null +++ b/MAINTAINING.md @@ -0,0 +1,52 @@ +# Maintaining NPR + +This guide covers repository stewardship. Application setup and deployment are documented separately in [SETUP.md](SETUP.md) and [backend/docs/DEPLOYMENT_GUIDE.md](backend/docs/DEPLOYMENT_GUIDE.md). + +## Maintainer responsibilities + +- Keep `main` releasable and require passing CI for merged changes. +- Protect document provenance, tenant isolation, citation integrity, and fail-closed behavior. +- Triage security reports privately and follow [SECURITY.md](SECURITY.md). +- Keep setup, deployment, support, and release documentation current. +- Avoid representing synthetic evaluation results as production legal or clinical validation. +- Preserve a reversible rollout path for migrations and feature flags. + +## Pull-request workflow + +1. Keep each pull request focused on one coherent change. +2. Require a clear problem statement, risk assessment, and validation evidence. +3. Confirm all required GitHub Actions checks pass. +4. Require explicit review of migrations, ACL behavior, external API use, and provenance changes. +5. Prefer squash merging unless commit history materially improves auditability. +6. Delete merged branches automatically. + +Direct force pushes and branch deletion are blocked on `main`. Emergency changes still use a pull request so CI and the audit trail remain intact. + +## Issue triage + +- Confirm the report contains reproducible evidence and no confidential data. +- Apply a type label (`bug`, `enhancement`, `docs`, `security`, or `chore`) and priority where justified. +- Move support questions to Discussions. +- Handle suspected vulnerabilities through private advisories. +- Close stale or superseded issues with a concise explanation. + +## Dependency and security maintenance + +- Review Dependabot pull requests weekly. +- Treat critical and high-severity findings as release blockers unless a documented risk acceptance applies. +- Keep GitHub secret scanning, push protection, and Dependabot security updates enabled. +- Never commit production secrets, client documents, or generated data containing sensitive material. + +## High-assurance changes + +Changes touching ACLs, citations, highlighting, ingestion provenance, authentication, or tenant boundaries require: + +- positive and negative tests; +- fail-closed behavior for missing or conflicting provenance; +- relevant integration coverage; +- a documented rollback path; +- representative human review before a production default-on decision. + +## Releases + +Use [RELEASING.md](RELEASING.md) and [RELEASE_CHECKLIST.md](RELEASE_CHECKLIST.md). Git tags and GitHub Releases describe code already merged to `main`; they are not a substitute for deployment approval. diff --git a/README.md b/README.md index 9250d80..3141641 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,40 @@ -# NPR - Near-Perfect RAG +
-A production-grade Retrieval-Augmented Generation (RAG) system designed for high-accuracy document question answering with evidence-based citations. +Cognitive Code logo -Developed by Larry Stewart at Cognitive Code ([cognitiveCode.ai](https://cognitiveCode.ai)). +# NPR — Near-Perfect RAG -## Overview +**Auditable document question answering with evidence-first retrieval, explicit citations, and reproducible traces.** + +Built by [Larry Stewart](https://github.com/LarryStewart2022) at [Cognitive Code](https://cognitivecode.ai). + +

+ CI status + MIT License + Python 3.12 + Next.js 16 + Controlled pilot status +

+ +

+ Quick start · + Architecture · + Testing · + Documentation · + Contributing · + Discussions +

+ +
+ +> [!IMPORTANT] +> **Project status: controlled pilot.** NPR has strong automated test and provenance foundations, but it is not represented as broadly production-ready for legal, clinical, or other high-stakes use. Production promotion requires deployment-specific security review, ACL enablement, representative domain validation, and operational load testing. + +

+ NPR dashboard showing document ingestion, chat, search, service health, and vector collections +

+ +## Why NPR NPR (Near-Perfect RAG) is a full-stack RAG system that retrieves relevant document evidence and generates answers with explicit citations. The system prioritizes: @@ -44,25 +74,25 @@ NPR (Near-Perfect RAG) is a full-stack RAG system that retrieves relevant docume | Component | Technology | |-----------|------------| -| Backend API | FastAPI (Python 3.11+) | -| Frontend | Next.js | +| Backend API | FastAPI on Python 3.12 | +| Frontend | Next.js 16 + React 19 | | Vector Database | Milvus | | Relational DB | PostgreSQL | | Object Storage | MinIO (S3-compatible) | | Task Queue | Celery + Redis | | Embeddings | OpenAI text-embedding-3-large | -| LLM (Chat) | Configurable (Ollama/OpenAI) | +| LLM (Chat) | OpenAI-backed grounded answer generation | ## Quick Start ```bash -git clone rag-system -cd rag-system +git clone https://github.com/CognitiveCodeAI/rag-main-2.git +cd rag-main-2 ./dev init ./dev up ``` -`./dev init` validates prerequisites (Docker, Python 3.10+, Node 18+, npm) and creates/syncs `backend/.env` from `backend/.env.example` without overwriting existing values. +`./dev init` validates prerequisites (Docker, Python 3.12, Node 20.9+, and npm) and creates or synchronizes `backend/.env` from `backend/.env.example` without overwriting existing values. `./dev up` runs first-time bootstrap when needed, starts local infrastructure, then starts backend, frontend, and celery. @@ -174,6 +204,10 @@ rag/ - [Deployment Guide](backend/docs/DEPLOYMENT_GUIDE.md) - Production deployment - [System Specification](lighthouse.md) - Full architecture spec - [Prompting Guide](PROMPTING_GUIDE.md) - Prompt engineering practices +- [Security Policy](SECURITY.md) - Private vulnerability reporting and scope +- [Support](SUPPORT.md) - Questions, issues, and commercial support +- [Maintainer Guide](MAINTAINING.md) - Review, triage, and repository stewardship +- [Release Guide](RELEASING.md) - Versioning and release procedure ## Configuration @@ -191,16 +225,19 @@ Key settings: ## Testing ```bash -cd backend +# Preferred repository-wide test entry point +./dev test -# Run all tests -pytest - -# Run specific test suite -pytest tests/qa/ -v - -# Run with coverage -pytest --cov=app tests/ +# Backend directly +cd backend +venv/bin/python -m pytest -q + +# Frontend directly +cd ../frontend +npm test +npm run lint +npx tsc --noEmit +npm run build ``` ## Development @@ -228,10 +265,16 @@ cd backend python tests/eval/update_benchmark_contract.py ``` +## Contributing + +Contributions are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md), follow the [Code of Conduct](CODE_OF_CONDUCT.md), and use the repository's issue and pull-request templates. Questions belong in [GitHub Discussions](https://github.com/CognitiveCodeAI/rag-main-2/discussions); vulnerabilities belong in a [private security advisory](https://github.com/CognitiveCodeAI/rag-main-2/security/advisories/new). + ## License -This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. +NPR is available under the [MIT License](LICENSE). -## Contributing +--- -See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. +
+ Built by Cognitive Code · Support · Security · Releases +
diff --git a/RELEASE_CHECKLIST.md b/RELEASE_CHECKLIST.md index 35045a9..de271d4 100644 --- a/RELEASE_CHECKLIST.md +++ b/RELEASE_CHECKLIST.md @@ -10,6 +10,7 @@ Use this checklist before every public release. A release is ready only when all - [ ] No secrets, local artifacts, or proprietary files are included. - [ ] Security disclosure process exists and is documented. - [ ] Changelog has a clear release summary. +- [ ] Protected-main rules, secret scanning, push protection, and Dependabot security updates are enabled. ## 1. Documentation Quality @@ -50,9 +51,12 @@ Acceptance evidence: Owner: Maintainer - [ ] Backend unit tests pass: - - [ ] `cd backend && pytest tests/test_acl_unit.py -q` + - [ ] `cd backend && venv/bin/python -m pytest -q` +- [ ] Security-critical infrastructure integration tests pass in CI. - [ ] Frontend lint and build pass: + - [ ] `cd frontend && npm test` - [ ] `cd frontend && npm run lint` + - [ ] `cd frontend && npx tsc --noEmit` - [ ] `cd frontend && npm run build` - [ ] Complex logic has concise comments explaining intent (not obvious line-by-line commentary). - [ ] Dead code, TODO placeholders, and debug prints are removed or converted to tracked issues. @@ -80,6 +84,8 @@ Acceptance evidence: Owner: Maintainer - [ ] `CONTRIBUTING.md` explains setup, coding standards, and PR process. +- [ ] `CODE_OF_CONDUCT.md`, `SUPPORT.md`, `MAINTAINING.md`, and `RELEASING.md` are current. +- [ ] Issue forms, pull-request template, and CODEOWNERS resolve correctly on GitHub. - [ ] `CHANGELOG.md` includes release notes in a consistent format. - [ ] Clear issue and PR descriptions used for all release changes. - [ ] Version/tag strategy decided before publishing (for example: `v1.0.0`). diff --git a/RELEASING.md b/RELEASING.md new file mode 100644 index 0000000..b5afd2f --- /dev/null +++ b/RELEASING.md @@ -0,0 +1,46 @@ +# Releasing NPR + +NPR follows [Semantic Versioning](https://semver.org/) and maintains user-facing changes in [CHANGELOG.md](CHANGELOG.md). + +The repository is currently in controlled-pilot status. Do not create a production-stable release until the release checklist, security gates, representative-domain validation, and operational readiness requirements are satisfied. + +## Release preparation + +1. Start from a clean checkout of the exact `main` commit to be released. +2. Confirm [CHANGELOG.md](CHANGELOG.md) has a dated version entry with only shipped behavior. +3. Complete [RELEASE_CHECKLIST.md](RELEASE_CHECKLIST.md). +4. Run the complete backend and frontend checks through `./dev test` and verify GitHub Actions is green. +5. Rehearse migrations on a production-like database, including rollback where supported. +6. Verify ACL, provenance, citation, highlighting, and unsupported-answer safety gates. +7. Confirm backups, restore procedures, monitoring, alerting, and deployment rollback are ready. +8. Obtain domain approval for any legal or clinical pilot claims. + +## Versioning + +- **Patch**: backward-compatible bug or security fixes. +- **Minor**: backward-compatible features or optional API additions. +- **Major**: incompatible API, storage, or operational changes. + +Pre-1.0 releases may use `v0.x.y` while the public contract and production operations mature. + +## Tag and publish + +After the release commit is merged and CI passes: + +```bash +git switch main +git pull --ff-only origin main +git tag -s vX.Y.Z -m "NPR vX.Y.Z" +git push origin vX.Y.Z +gh release create vX.Y.Z --verify-tag --generate-notes --title "NPR vX.Y.Z" +``` + +Use an annotated tag if signed tags are not configured. Review generated notes before publishing, and add upgrade, migration, rollback, and known-limitation guidance. + +## After publishing + +- Verify installation and startup from the published tag. +- Confirm health checks and a representative end-to-end query. +- Monitor error rate, latency, fallback rate, and evidence-verification failures. +- Announce only capabilities that are enabled and validated in the released configuration. +- Open follow-up issues for deferred work and prepare an incident response if rollback thresholds are crossed. diff --git a/SECURITY.md b/SECURITY.md index ce7bcb7..ba8d481 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -6,7 +6,8 @@ Security fixes are applied to the latest version on `main`. | Version | Supported | | ------- | --------- | -| Latest (`main`) | Yes | +| Latest tagged release | Yes | +| `main` | Development support | | Older releases | Best effort | ## Reporting a Vulnerability @@ -15,7 +16,7 @@ Please do not open public issues for security vulnerabilities. Use one of these private channels: -- Open a private GitHub Security Advisory in this repository. +- Open a [private GitHub Security Advisory](https://github.com/CognitiveCodeAI/rag-main-2/security/advisories/new). - If advisories are unavailable, contact the maintainer directly via the email listed on the repository owner profile. Include: @@ -25,12 +26,32 @@ Include: - Impact assessment - Any suggested mitigation +Do not include real client documents, protected health information, privileged +legal material, personal data, or production credentials. Use synthetic data +and the minimum proof needed to demonstrate the issue. + +## In scope + +Security reports may include authentication or authorization bypasses, +cross-tenant disclosure, prompt-injection paths that escape documented safety +boundaries, citation or provenance tampering, unsafe file handling, secret +exposure, dependency vulnerabilities with a demonstrated impact, and remote +code execution. + +General support requests, model-quality disagreements without a security +boundary violation, and reports against unsupported third-party deployments +belong in [GitHub Discussions](https://github.com/CognitiveCodeAI/rag-main-2/discussions). + ## Response Expectations - Initial acknowledgement: within 72 hours - Triage status update: within 7 days - Fix timeline: depends on severity and complexity +Please allow a reasonable remediation window before public disclosure. We will +coordinate attribution and advisory publication with the reporter when +appropriate. + ## Disclosure After a fix is available, we may publish a security advisory with: diff --git a/SUPPORT.md b/SUPPORT.md new file mode 100644 index 0000000..88766c9 --- /dev/null +++ b/SUPPORT.md @@ -0,0 +1,26 @@ +# Support + +## Questions and usage help + +Use [GitHub Discussions](https://github.com/CognitiveCodeAI/rag-main-2/discussions) for setup questions, architecture discussions, deployment guidance, and show-and-tell. Search existing discussions and documentation before starting a new thread. + +Useful starting points: + +- [README](README.md) +- [Setup guide](SETUP.md) +- [Quick start](backend/docs/QUICK_START.md) +- [Deployment guide](backend/docs/DEPLOYMENT_GUIDE.md) + +Community support is provided on a best-effort basis. Public support channels are not appropriate for confidential client documents, personal data, protected health information, privileged legal material, API keys, or production credentials. + +## Bugs and feature requests + +Use the repository's structured [issue forms](https://github.com/CognitiveCodeAI/rag-main-2/issues/new/choose). Include a minimal reproduction and redact sensitive information. + +## Security vulnerabilities + +Do not report vulnerabilities publicly. Follow [SECURITY.md](SECURITY.md) and open a [private security advisory](https://github.com/CognitiveCodeAI/rag-main-2/security/advisories/new). + +## Commercial and implementation services + +For commercial support or implementation work, contact [Cognitive Code](https://cognitivecode.ai).