chore: sync test → main (quality gate, branching strategy, docs)

.github/workflows/claude-quality-gate.yml

@@ -0,0 +1,110 @@
+name: Claude Quality Gate
+
+on:
+  pull_request:
+    branches: [main]
+    types: [opened, synchronize, reopened]
+
+permissions:
+  contents: read
+  pull-requests: write
+  issues: write
+  id-token: write
+
+jobs:
+  # Agent 1 — verify tests exist for all changed code
+  test-coverage-agent:
+    name: Test Coverage Agent
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          prompt: |
+            You are a test quality agent for the ptop3 project.
+
+            Review the diff of this PR (compare HEAD to the base branch) and:
+            1. List every new or modified function/method in ptop3/ source files.
+            2. Check tests/ to confirm each one has a corresponding test.
+            3. For any function missing a test, write the missing test(s) following the project rules:
+               - Mock /proc/* files with tmp_path fixtures
+               - Mock curses — never test TUI rendering directly
+               - Patch os.geteuid for root-required paths
+               - Tests must pass on Python 3.10–3.13
+            4. If all functions are covered, post a short confirmation comment.
+            5. If you added tests, create a commit on this PR branch with message "test: add missing tests for <summary>"
+
+            Project test style is in tests/conftest.py and existing test files.
+            Quality rules are in .github/instructions/code-review.instructions.md.
+
+  # Agent 2 — verify CHANGELOG and docs are updated
+  docs-changelog-agent:
+    name: Docs & Changelog Agent
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          prompt: |
+            You are a documentation quality agent for the ptop3 project.
+
+            Review the diff of this PR and:
+
+            1. CHANGELOG check:
+               - If any user-facing behavior changed (new feature, bug fix, CLI flag, keybinding),
+                 verify CHANGELOG.md has an entry under ## [Unreleased].
+               - If missing, add the appropriate entry under the correct section
+                 (Added / Changed / Fixed / Security / Deprecated / Removed).
+               - Do NOT bump version numbers.
+
+            2. README check:
+               - If new keybindings, CLI flags, or entry points were added, verify README.md documents them.
+               - If missing, add the documentation.
+
+            3. Docstring check:
+               - For any new public function in ptop3/ that lacks a docstring, add a one-line docstring.
+
+            If you made changes, commit them with message "docs: update changelog/readme for <summary>".
+            If everything is already documented, post a short confirmation comment.
+
+  # Agent 3 — code quality and security review
+  code-review-agent:
+    name: Code Review Agent
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          prompt: |
+            You are a code quality and security agent for the ptop3 project.
+
+            Review the diff of this PR against the standards in
+            .github/instructions/code-review.instructions.md and check for:
+
+            1. Style violations: bare except, print() in library code, typing.Dict/List/Optional,
+               shell=True in subprocess, string path concatenation instead of pathlib.
+            2. Security issues: unsanitized input to subprocess, hardcoded secrets,
+               missing root check before writing /proc/sys/vm/drop_caches or calling swapoff/swapon,
+               missing visudo validation before sudoers writes.
+            3. GitHub Actions: missing permissions blocks, missing skip-existing on TestPyPI steps.
+            4. Module-specific rules from the instructions file.
+
+            For each issue found:
+            - Post an inline PR review comment at the exact file+line.
+            - If the fix is straightforward (style, missing guard), apply it directly and commit
+              with message "fix: <short description>".
+            - If the fix requires design decisions, comment only — do not auto-fix.
+
+            If no issues are found, post a brief approval comment summarising what was checked.

.github/workflows/publish-testpypi.yml

@@ -2,7 +2,7 @@ name: Publish to TestPyPI
 
 on:
   push:
-    branches: [main]
+    branches: [test]
   workflow_dispatch:
 
 permissions:

CLAUDE.md

@@ -0,0 +1,41 @@
+# ptop3 — Claude Code Context
+
+`ptop3` is a Linux TUI process monitor (htop-like) that groups processes by application.
+It uses `curses` for the UI, `psutil` for process data, and ships two privileged scripts
+(`ptop3-drop-caches`, `ptop3-swap-clean`) that run via passwordless sudo.
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `ptop3/monitor.py` | Core TUI + data aggregation |
+| `ptop3/sudo_config.py` | Passwordless sudo setup |
+| `ptop3/scripts/drop_caches.py` | Kernel cache clearing |
+| `ptop3/scripts/swap_clean.py` | Swap cleanup |
+| `tests/` | Pytest suite — all 4 Python versions |
+| `CHANGELOG.md` | User-facing change log |
+| `.github/instructions/code-review.instructions.md` | Full style & quality guide |
+
+## Code Standards
+
+- Python 3.10+: use `X | None`, `list[str]`, `match`, builtin generics — no `typing.Dict/List/Optional`
+- Ruff: line-length 100, rules E/F/I/UP — run `ruff check ptop3/` before committing
+- No bare `except:`, no `print()` in library code, no `shell=True` in subprocess calls
+- File paths via `pathlib.Path` — never string concatenation
+
+## Testing
+
+- Run: `pytest --cov=ptop3 --cov-report=term-missing`
+- Every new function must have a test; mock `/proc/*` files with `tmp_path`; mock `curses`
+- Tests must not require root — patch `os.geteuid` for privileged paths
+
+## CHANGELOG
+
+Every PR with user-facing changes must add an entry under `## [Unreleased]`.
+Sections: `Added`, `Changed`, `Fixed`, `Security`, `Deprecated`, `Removed`.
+Do **not** bump versions manually — that's handled by `bump-my-version` in the release workflow.
+
+## Commits
+
+Conventional format: `feat:`, `fix:`, `docs:`, `ci:`, `chore:`, `refactor:`, `test:`
+CI must be green on all 4 Python versions (3.10–3.13) before merging.

codecov.yml

@@ -0,0 +1,10 @@
+coverage:
+  status:
+    project:
+      default:
+        target: auto
+        threshold: 1%
+
+codecov:
+  notify:
+    after_n_builds: 4  # match matrix size (3.10, 3.11, 3.12, 3.13)