chore: add Claude Code safeguards and track CLAUDE.md

.claude/settings.json

@@ -0,0 +1,132 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "permissions": {
+    "defaultMode": "default",
+    "deny": [
+      "Bash(gh pr merge*)",
+      "Bash(gh pr review --approve*)",
+      "Bash(gh pr review -a*)",
+      "Bash(gh pr close*)",
+
+      "Bash(git push * main)",
+      "Bash(git push * main *)",
+      "Bash(git push * master)",
+      "Bash(git push * master *)",
+      "Bash(git push --force *)",
+      "Bash(git push * --force *)",
+      "Bash(git push -f *)",
+      "Bash(git push * -f *)",
+      "Bash(git push * +*)",
+      "Bash(git reset --hard*)",
+      "Bash(git clean -f*)",
+      "Bash(git branch -D *)",
+      "Bash(git checkout -- .)",
+      "Bash(git restore .)",
+
+      "Bash(rm -rf *)",
+      "Bash(rm -r *)",
+      "Bash(sudo *)",
+      "Bash(chmod 777 *)",
+      "Bash(curl * | sh*)",
+      "Bash(curl * | bash*)",
+      "Bash(wget * | sh*)",
+      "Bash(wget * | bash*)",
+
+      "Edit(~/.ssh/**)",
+      "Edit(~/.aws/**)",
+      "Edit(~/.gnupg/**)",
+      "Edit(~/.config/gh/**)",
+      "Write(~/.ssh/**)",
+      "Write(~/.aws/**)",
+      "Write(~/.gnupg/**)",
+      "Write(~/.config/gh/**)"
+    ],
+    "allow": [
+      "Read",
+      "Glob",
+      "Grep",
+      "WebFetch",
+      "WebSearch",
+      "Task",
+
+      "Edit",
+      "Write",
+
+      "Bash(git status*)",
+      "Bash(git log*)",
+      "Bash(git diff*)",
+      "Bash(git add *)",
+      "Bash(git commit *)",
+      "Bash(git checkout *)",
+      "Bash(git switch *)",
+      "Bash(git branch*)",
+      "Bash(git fetch*)",
+      "Bash(git pull*)",
+      "Bash(git stash*)",
+      "Bash(git show *)",
+      "Bash(git rev-parse *)",
+      "Bash(git remote *)",
+      "Bash(git merge *)",
+      "Bash(git rebase *)",
+      "Bash(git cherry-pick *)",
+      "Bash(git push --force-with-lease *)",
+      "Bash(git push *)",
+
+      "Bash(cargo build*)",
+      "Bash(cargo test*)",
+      "Bash(cargo check*)",
+      "Bash(cargo clippy*)",
+      "Bash(cargo fmt*)",
+      "Bash(cargo doc*)",
+      "Bash(cargo run*)",
+      "Bash(cargo clean*)",
+      "Bash(cargo tree*)",
+      "Bash(cargo metadata*)",
+      "Bash(cargo bench*)",
+
+      "Bash(make *)",
+      "Bash(make)",
+
+      "Bash(gh pr view *)",
+      "Bash(gh pr list*)",
+      "Bash(gh pr diff *)",
+      "Bash(gh pr checks *)",
+      "Bash(gh pr status*)",
+      "Bash(gh issue view *)",
+      "Bash(gh issue list*)",
+      "Bash(gh issue create *)",
+      "Bash(gh api *)",
+
+      "Bash(docker build *)",
+      "Bash(docker run *)",
+      "Bash(docker compose *)",
+      "Bash(docker ps*)",
+      "Bash(docker images*)",
+      "Bash(docker logs *)",
+
+      "Bash(ls *)",
+      "Bash(ls)",
+      "Bash(pwd)",
+      "Bash(which *)",
+      "Bash(echo *)",
+      "Bash(wc *)",
+      "Bash(sort *)",
+      "Bash(head *)",
+      "Bash(tail *)",
+      "Bash(mkdir *)",
+      "Bash(cp *)",
+      "Bash(mv *)",
+      "Bash(cat *)",
+      "Bash(date*)",
+      "Bash(env)",
+      "Bash(printenv *)",
+      "Bash(basename *)",
+      "Bash(dirname *)",
+      "Bash(realpath *)",
+      "Bash(touch *)",
+      "Bash(file *)",
+
+      "Bash(rm /tmp/*)"
+    ]
+  }
+}

.gitignore

@@ -1,6 +1,4 @@
 .idea/
 target/
 bin/
-CLAUDE.md
 .output.txt
-/.claude/settings.json

CLAUDE.md

@@ -0,0 +1,118 @@
+                                    AGENT SAFEGUARDS (non-negotiable)
+
+Operating principles
+1) Prefer clear code over comments.
+    - Use comments only for: non-obvious reasoning, security invariants, protocol quirks, or “why” that code cannot express.
+    - Prefer descriptive names, small functions, and explicit types over commentary.
+
+2) Solve root cause, not band-aids.
+    - Do not add retries/timeouts/logging to hide failures unless the root cause is addressed or explicitly impossible to fix.
+    - If a workaround is necessary, document the root cause and the exact reason it can’t be fixed now.
+
+3) Use idioms of the language and ecosystem.
+    - Follow standard style guides, conventions, directory layout, and tooling.
+    - Avoid clever patterns that fight the ecosystem. Prefer boring, maintainable solutions.
+
+Quality gates
+4) Tests must run after each modification.
+    - After any functional change, run the relevant test suite locally (or in CI steps) and ensure it passes.
+    - If tests cannot run (missing dependency, environment), add or update a runnable test harness or clearly state what is required.
+    - Never leave the repo in a state where tests are known failing.
+
+5) Documentation for all features.
+    - Every new feature must have usage docs + one runnable example.
+    - Docs must include intent, flags/config, and failure modes.
+    - Prefer docs that answer user questions (“How do I…”) and include copy/paste snippets.
+
+6) Update CHANGELOG with all changes.
+    - Every user-visible change must be added to CHANGELOG.md under “Unreleased”.
+    - Use categories: Added / Changed / Fixed / Security / Deprecated / Removed.
+    - Mention migration steps if behavior changes.
+
+Robustness & correctness
+7) Include error handling everywhere it matters.
+    - Never ignore errors; propagate with context.
+    - Wrap/annotate errors so the caller has actionable info.
+    - Ensure exit codes/return values are correct and consistent.
+
+8) Test edge cases and invariants.
+    - Add tests for: empty inputs, invalid inputs, boundary values, timeouts, large payloads (reasonable), and concurrency/ordering if relevant.
+    - Include at least one test for each bug fixed to prevent regressions.
+
+Security & safety (important for agentic tooling)
+9) No harmful actions by default.
+    - Do not delete data, rotate secrets, publish releases, or mutate external systems unless explicitly requested.
+    - Treat external calls (network, cloud APIs) as “dangerous”: require explicit opt-in via config/flags.
+
+10) Least privilege and safe defaults.
+- Minimize permissions, capabilities, scopes, and access tokens.
+- For Kubernetes artifacts: runAsNonRoot, readOnlyRootFilesystem, allowPrivilegeEscalation=false, drop ALL capabilities unless justified.
+
+11) No secret leakage.
+- Never print tokens, passwords, or full credential material to logs.
+- Redact known secret patterns; avoid echoing env vars that might contain secrets.
+
+12) Deterministic builds and reproducibility.
+- Prefer pinned versions, lockfiles, and deterministic packaging.
+- Avoid “download latest at build time” unless necessary.
+
+Change management rules
+13) Small, reviewable diffs.
+- Prefer incremental changes with clear commit boundaries.
+- If a refactor is needed, do it in a separate commit/PR before feature changes.
+
+14) Respect existing standards and tooling.
+- Use the repo's existing lint/format/test tools (Makefile/package scripts/cargo test/etc.).
+- If tooling is missing, add it in a minimal conventional way.
+
+15) Provide a “How to verify” section in PR descriptions/output.
+- Include exact commands: build, lint, unit tests, integration tests (if any).
+
+Agent execution constraints (for local runners / GH actions)
+16) Only modify files that are in-scope for the task.
+- Do not reformat unrelated files.
+- Do not introduce new dependencies unless justified.
+
+17) When uncertain, choose the safer option and make it explicit.
+- Prefer failing fast with actionable errors over silent fallback.
+- If ambiguity remains, implement a guardrail and document the decision.
+
+18) When really uncertain, ask for help.
+- Avoid making assumptions without asking for confirmation.
+
+19) When running locally, prefer the mcp edit tool to direct file edits.
+- If issues arise where files seem unedited, alert the user before continuing.
+
+20) Prefer bash commands/scripts to python3 when investigating.
+
+Definition of implement issue
+- Find the issue in github issues.
+- If not found, inform the user.
+- If found:
+    - Fetch from origin
+    - Create a branch with the issue number in the name from origin/main.
+    - Implement the issue.
+    - Run all e2e tests.
+    - If during implementation, obvious errors were found in the originating issue, also add a comment to the issue about the fix.
+    - If running from Claude Code or Claude Desktop:
+      - Do NOT create a PR automatically.
+      - Instead, present a summary of changes and let the user decide when to create the PR.
+    - Otherwise (e.g. GitHub Copilot, Junie, or other automated agents):
+      - Create a PR with the issue number in the title.
+      - Make sure the PR passes CI.
+
+Definition of done
+- Code compiles without warnings.
+- Code is linted.
+- Code is formatted.
+- Tests pass.
+- Docs updated.
+- CHANGELOG updated.
+- Edge cases tested.
+- Security posture maintained.
+- Output includes a concise summary of changes + how to verify.
+- For rust code:
+  - All unsafe code is annotated.
+  - Use explicit lifetimes where necessary.
+  - Use clippy lints.
+