chore: add PR hygiene checks, update issue templates

.github/workflows/pr-hygiene.yml

@@ -0,0 +1,87 @@
+name: PR hygiene checks
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+permissions:
+  contents: read
+  pull-requests: read
+
+jobs:
+  validate:
+    name: Validate PR hygiene
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '18'
+
+      - name: Get changed files
+        id: changed
+        run: |
+          base_ref="${{ github.event.pull_request.base.ref }}"
+          git fetch origin "$base_ref"
+          files=$(git diff --name-only "origin/$base_ref"...HEAD || true)
+          printf "%s\n" "$files" > changed_files.txt
+          echo "list<<EOF" >> $GITHUB_OUTPUT
+          printf "%s\n" "$files" >> $GITHUB_OUTPUT
+          echo "EOF" >> $GITHUB_OUTPUT
+
+      - name: Check for skip label
+        id: skip
+        run: |
+          labels='${{ toJson(github.event.pull_request.labels) }}'
+          echo "$labels" | grep -qi 'hygiene-skip' && echo "skip=true" >> $GITHUB_OUTPUT || echo "skip=false" >> $GITHUB_OUTPUT
+
+      - name: Require changelog changed
+        if: ${{ steps.skip.outputs.skip != 'true' }}
+        run: |
+          files="${{ steps.changed.outputs.list }}"
+          echo "$files" > /tmp/changed.txt
+          if ! grep -Eiq '(^|/)(CHANGELOG|changelog)(\.md)?$' /tmp/changed.txt; then
+            echo "No changelog update detected (expect CHANGELOG.md or docs/changelog)."
+            exit 1
+          fi
+
+      - name: Require package.json changed and version bump
+        if: ${{ steps.skip.outputs.skip != 'true' }}
+        run: |
+          files="${{ steps.changed.outputs.list }}"
+          echo "$files" > /tmp/changed.txt
+          if ! grep -q 'package.json' /tmp/changed.txt; then
+            echo "No package.json changed in this PR — skipping package version check."
+            exit 0
+          fi
+          base_ref="${{ github.event.pull_request.base.ref }}"
+          set -e
+          while read -r p; do
+            # normalize path
+            file=$(echo "$p" | tr -d '\r')
+            echo "Checking package.json: $file"
+            git show "origin/$base_ref:$file" > /tmp/base_pkg.json || true
+            git show "HEAD:$file" > /tmp/head_pkg.json || true
+            node -e "const fs=require('fs'); const b=fs.existsSync('/tmp/base_pkg.json')?require('/tmp/base_pkg.json'):{version:null}; const h=fs.existsSync('/tmp/head_pkg.json')?require('/tmp/head_pkg.json'):{}; if(!h.version){console.error('head package.json has no version'); process.exit(1);} if(!b.version||b.version===h.version){console.error('package.json version unchanged for $file'); process.exit(1);} console.log('version changed for $file')"
+          done < <(grep -Eo '(^|/)[^ ]*package.json' /tmp/changed.txt || true)
+
+      - name: Require at least one approving review
+        uses: actions/github-script@v6
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const pr = context.payload.pull_request;
+            const { data: reviews } = await github.rest.pulls.listReviews({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              pull_number: pr.number
+            });
+            const approved = reviews.some(r => r.state === 'APPROVED');
+            if (!approved) {
+              core.setFailed('Pull Request has no approved review yet.');
+            }

CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## [Unreleased]
+
+### Added 
+- Added CODEOWNERS file to define code ownership and review responsibilities.
+- Added dependabot.yml to automate dependency updates for npm and GitHub Actions.
+- Added README.md with an overview of the .github repository and its purpose.
+- Added pr-hygiene.yml workflow to automate PR hygiene checks and enforce best practices.
+

CODEOWNERS

@@ -0,0 +1,2 @@
+
+* @hypersign-protocol/reviewers

CONTRIBUTING.md

@@ -0,0 +1,24 @@
+Thanks for contributing — this file explains how we work and what we expect from PRs.
+
+Quick guidelines
+- Use small, focused PRs. One change, one responsibility.
+- Use Conventional Commits for commit messages when possible.
+- Add tests for new behavior and update docs for public-facing changes.
+
+Before opening a PR
+- Fill the PR template completely and link the related issue or design doc.
+- Add a short, one-line release note for the changelog if this change will appear in a release.
+
+Reviewing and merging
+- Assign reviewers from the `@hypersign-protocol/reviewers` Code Owners team.
+- Address feedback and wait for an approving review before merging.
+- CI must be green and required status checks must pass.
+
+Safety checks
+- Do not commit secrets or credentials. Use the org secret store for secrets.
+- If your change has security implications, follow the process in `SECURITY.md`.
+
+Releases
+- Update `CHANGELOG.md` and bump package versions when releasing packages.
+
+If you have questions about policy (approvals, release windows, or exemptions), ask the maintainers or the security/compliance owners.

ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,29 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: bug
+assignees: ''
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Click on '...'
+3. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots or logs**
+If applicable, add screenshots or paste logs.
+
+**Environment (please complete the following information):**
+- OS: [e.g. Ubuntu 22.04]
+- Version: [repo/package version]
+
+**Additional context**
+Add any other context about the problem here.

ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,19 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: enhancement
+assignees: ''
+---
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**User story**
+As a [role], I want [feature] so that [benefit].
+
+**Alternatives considered**
+Describe alternatives you've considered.
+
+**Notes**
+Any additional context or screenshots.

PULL_REQUEST_TEMPLATE.md

@@ -1,29 +1,106 @@
-## 🎯 Purpose
-Why is this change needed? (problem it solves or value it adds)
+## Title
+Provide a short, descriptive title of the change (50 characters max recommended).
 
 ---
 
-## 📝 Changes
-- Brief list of main updates
+## Summary
+One-paragraph summary describing what the change does and why. Link related issue(s) or design docs.
 
 ---
 
-## 🔄 Type
-- [ ] 🚀 Feature
-- [ ] 🐛 Fix
-- [ ] 📝 Docs
-- [ ] ♻️ Refactor
-- [ ] ✅ Tests
-- [ ] 🔧 Config / CI
+## Background / Motivation
+Explain the context, problem being solved, and any alternatives considered. Include links to design docs, issues, or RFCs.
 
 ---
 
-## 🧪 Testing
-How did you test this? (unit/integration/manual)
+## Scope of Changes
+- Files / modules affected (high level)
+- Public API changes (if any)
+- Database / schema / migration impact (if any)
 
 ---
 
-## ✅ Checklist
-- [ ] Code follows Hypermine standards
-- [ ] Tests/docs updated if needed
-- [ ] Verified locally
+## Type
+- [ ] Feature
+- [ ] Bugfix
+- [ ] Docs
+- [ ] Refactor
+- [ ] Tests
+- [ ] Performance
+- [ ] Build / CI / Config
+
+---
+
+## Implementation
+Describe the approach taken, key design decisions, and why.
+
+---
+
+## Testing & QA
+- Units / integration tests added: describe coverage and important test cases
+- Manual / exploratory test steps for QA
+- CI matrix: platforms/versions validated
+
+---
+
+## Migration / Rollout Plan
+- Data migrations and downtime expectations
+- Backwards compatibility notes
+- Feature flags and staged rollout instructions
+
+---
+
+## Security / Privacy Considerations
+List any security implications, new secrets, or compliance-related items.
+
+---
+
+## Performance Impact
+Any benchmark results or expected performance regressions/improvements.
+
+---
+
+## Release Notes (for changelog)
+One-line summary suitable for release notes / CHANGELOG.
+
+---
+
+## Checklist (required)
+- [ ] Linked issue or ticket present (link: )
+- [ ] Target branch is correct
+- [ ] PR description explains the why, not just the what
+- [ ] Code compiles and tests pass locally
+- [ ] Unit and integration tests added where applicable
+- [ ] Documentation updated (README, docs site, comments)
+- [ ] CHANGELOG.md (or repo-specific changelog) updated with an entry
+- [ ] `package.json` / package version updated if publishing a release
+- [ ] No secrets or credentials committed
+- [ ] Security review completed if required
+- [ ] Performance benchmarks included if applicable
+- [ ] Migration steps included if applicable
+
+---
+
+## Reviewer Guidance
+List the specific areas you want reviewers to focus on (e.g., security, migration, public API, edge cases). Provide commands or steps to run the project locally to validate the change:
+
+```bash
+# checkout PR branch
+git checkout $BRANCH
+# run tests
+npm ci && npm test
+# run lint
+npm run lint
+```
+
+---
+
+## Acceptance Criteria
+Define the minimal conditions that must be true for this PR to be merged (e.g., tests pass, performance threshold met, migration completed).
+
+---
+
+## Approvals
+- [ ] At least one approving review from code owners
+- [ ] CI status checks are green
+- [ ] Any required manual QA sign-off

README.md

@@ -1,2 +1,20 @@
 # .github
-Community repo for contributing to @Hypersign-protocol
+
+Organization-level templates for Hypersign Protocol.
+Purpose
+Centralize templates, CODEOWNERS, security reporting, and PR hygiene automation for enterprise repositories.
+
+Included (key items)
+- `PULL_REQUEST_TEMPLATE.md` — PR template
+- `CONTRIBUTING.md` — contributor guide
+- `SECURITY.md` — private reporting (replace `SECURITY_CONTACT`)
+- `CODEOWNERS` — team ownership
+- `.github/workflows/pr-hygiene.yml` — PR hygiene checks
+
+Adoption
+- Copy the relevant files into a repository to adopt these policies.
+- Require the `PR hygiene checks` workflow in branch protection to enforce policy.
+
+Contact
+- For template or automation issues, contact `@hypersign-protocol/reviewers`.
+

dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+- package-ecosystem: "npm"
+  directory: "/"
+  schedule:
+    interval: "weekly"
+- package-ecosystem: "github-actions"
+  directory: "/"
+  schedule:
+    interval: "weekly"