Contributing

Contributing to RAGAPPv3 (KnowledgeVault)

The human-facing version of this process is CONTRIBUTING.md; the agent entry point is AGENTS.md. This skill is the actionable checklist. For the actual commit/push/PR mechanics (staging, force-with-lease, draft PRs, review follow-up), defer to .claude/skills/commit-pr/SKILL.md — do not duplicate it here.

1. Branch setup

• Base branch is master. Branch from the latest origin/master.
• Branch names: short, prefixed slugs, e.g. fix/tag-cascade, feat/bulk-export. Agent runners may use a runner prefix (claude/…, codex/…) per commit-pr.

git fetch origin master
git checkout -b fix/<short-slug> origin/master

2. Commit message format (Conventional Commits)

type(scope): lowercase description — no trailing period.

Allowed type values in this repo (per CONTRIBUTING.md):

Examples:

• fix(tags): cascade-delete tag rows when a vault is removed
• feat(export): add bulk vault export endpoint
• test(auth): cover refresh-token rotation negative paths

Stage explicit paths. Do not commit IDE files, local settings, .env, or generated artifacts.

There is no conventional-commit CI linter and no PR-title check job in this repo — but master history and the human reviewers expect the format, so follow it.

3. Run the CI gates locally (four jobs, all must pass)

CI (.github/workflows/ci.yml) is PR-triggered against master and has exactly four jobs. Reproduce them so your PR goes green on the first try.

Backend (from backend/)

ruff check .
# CI runs only this targeted subset:
pytest --tb=short -v tests/test_path_prefix.py tests/test_auth_routes.py tests/test_main_catchall.py
# ...plus the tests for the area you changed, e.g.:
pytest -q tests/test_tags_routes.py

Python 3.11. CI pins 3.11. On a newer local interpreter some tests fail with RuntimeError: There is no current event loop — a local-interpreter artifact, not a regression. Use a 3.11 venv. (See running-tests / writing-tests.)

Frontend (from frontend/)

npm run typecheck
npm run lint        # zero-warning gate: eslint src --max-warnings 0
npm test            # vitest run
npm run build       # tsc && vite build (CI also runs two subpath builds)

Quality contracts (from repo root)

python scripts/check_config_contract.py
python scripts/check_pr_scope_drift.py
python scripts/check_sast_baseline.py

check_pr_scope_drift.py flags drift such as auth tests changed without matching auth runtime/doc changes, and CI/tooling changes without a contract update — fix the underlying drift rather than gaming the diff.

SAST (from repo root; bandit is in backend/requirements-dev.txt)

python scripts/run_bandit.py
# Fails only on NEW findings vs backend/security/bandit-baseline.json.
# To accept a new pre-existing finding intentionally, regenerate with
#   python scripts/run_bandit.py --update-baseline
# and justify the newly-suppressed finding IDs in the PR.

For the authoritative, always-current CI-mirror command list, run the ci-compatibility-audit skill before pushing.

4. Testing expectations

New behavior ships with tests that assert real behavior:

• Backend: status and response body and DB state change.
• Frontend: callback args / DOM, not just "it rendered".

Cover negative paths (403/422, cross-vault isolation, cascade deletes). Security-sensitive code gets *_adversarial companion tests. See writing-tests and docs/engineering/testing.md.

5. Open the PR

• Base branch: master. Default to a draft PR unless the user asks for ready-for-review.
• PR body includes ## Summary (1–3 bullets: what + why) and ## Test plan (a checklist of commands run and their results).
• Never git push --force to a shared branch; use --force-with-lease to rewrite your own PR branch.

For the full publication flow — scoped staging, validation per change type, review-finding handling, push safety, and PR body template — load .claude/skills/commit-pr/SKILL.md and follow it.

What this repo does NOT have

Do not invent or look for these — they belong to other repos:

• ❌ release-please, CHANGELOG.md automation, .release-please-manifest.json
• ❌ docs/releases/pending/ fragments or any mandatory release-note file
• ❌ biome (lint is eslint; format is part of lint)
• ❌ bun / bun:test (backend is pytest; frontend is Vitest)
• ❌ dist-check / committed build output
• ❌ a per-OS test matrix (CI is Ubuntu-only)
• ❌ a PR-title / conventional-commit CI linter
• ❌ .swarm/ evidence artifacts

Checklist

• Branch created from latest origin/master with a prefixed slug
• Commits follow type(scope): lowercase description
• Backend: ruff check . + CI subset + changed-area tests pass (from backend/)
• Frontend: typecheck, lint, test, build pass (from frontend/)
• Quality contracts: both scripts/check_*.py pass (from repo root)
• New/updated tests assert real behavior and cover negative paths
• PR targets master, is a draft by default, has ## Summary + ## Test plan
• Publication done via commit-pr