docs: document NIPs and PR template usage

.github/copilot-instructions.md

@@ -1,8 +1,99 @@
 # Repository Instructions for Copilot
 
-- Follow the Nostr protocol (NIP-xx) specifications.
-  - Spec index: https://github.com/nostr-protocol/nips
-  - Each NIP is at `https://github.com/nostr-protocol/nips/blob/master/XX.md` (e.g. NIP-01 → https://github.com/nostr-protocol/nips/blob/master/01.md)
+## NIPs
+
+- https://github.com/nostr-protocol/nips/blob/master/01.md
+- https://github.com/nostr-protocol/nips/blob/master/02.md
+- https://github.com/nostr-protocol/nips/blob/master/03.md
+- https://github.com/nostr-protocol/nips/blob/master/04.md
+- https://github.com/nostr-protocol/nips/blob/master/05.md
+- https://github.com/nostr-protocol/nips/blob/master/06.md
+- https://github.com/nostr-protocol/nips/blob/master/07.md
+- https://github.com/nostr-protocol/nips/blob/master/08.md
+- https://github.com/nostr-protocol/nips/blob/master/09.md
+- https://github.com/nostr-protocol/nips/blob/master/10.md
+- https://github.com/nostr-protocol/nips/blob/master/11.md
+- https://github.com/nostr-protocol/nips/blob/master/12.md
+- https://github.com/nostr-protocol/nips/blob/master/13.md
+- https://github.com/nostr-protocol/nips/blob/master/14.md
+- https://github.com/nostr-protocol/nips/blob/master/15.md
+- https://github.com/nostr-protocol/nips/blob/master/16.md
+- https://github.com/nostr-protocol/nips/blob/master/17.md
+- https://github.com/nostr-protocol/nips/blob/master/18.md
+- https://github.com/nostr-protocol/nips/blob/master/19.md
+- https://github.com/nostr-protocol/nips/blob/master/20.md
+- https://github.com/nostr-protocol/nips/blob/master/21.md
+- https://github.com/nostr-protocol/nips/blob/master/22.md
+- https://github.com/nostr-protocol/nips/blob/master/23.md
+- https://github.com/nostr-protocol/nips/blob/master/24.md
+- https://github.com/nostr-protocol/nips/blob/master/25.md
+- https://github.com/nostr-protocol/nips/blob/master/26.md
+- https://github.com/nostr-protocol/nips/blob/master/27.md
+- https://github.com/nostr-protocol/nips/blob/master/28.md
+- https://github.com/nostr-protocol/nips/blob/master/29.md
+- https://github.com/nostr-protocol/nips/blob/master/30.md
+- https://github.com/nostr-protocol/nips/blob/master/31.md
+- https://github.com/nostr-protocol/nips/blob/master/32.md
+- https://github.com/nostr-protocol/nips/blob/master/33.md
+- https://github.com/nostr-protocol/nips/blob/master/34.md
+- https://github.com/nostr-protocol/nips/blob/master/35.md
+- https://github.com/nostr-protocol/nips/blob/master/36.md
+- https://github.com/nostr-protocol/nips/blob/master/37.md
+- https://github.com/nostr-protocol/nips/blob/master/38.md
+- https://github.com/nostr-protocol/nips/blob/master/39.md
+- https://github.com/nostr-protocol/nips/blob/master/40.md
+- https://github.com/nostr-protocol/nips/blob/master/42.md
+- https://github.com/nostr-protocol/nips/blob/master/44.md
+- https://github.com/nostr-protocol/nips/blob/master/45.md
+- https://github.com/nostr-protocol/nips/blob/master/46.md
+- https://github.com/nostr-protocol/nips/blob/master/47.md
+- https://github.com/nostr-protocol/nips/blob/master/48.md
+- https://github.com/nostr-protocol/nips/blob/master/49.md
+- https://github.com/nostr-protocol/nips/blob/master/50.md
+- https://github.com/nostr-protocol/nips/blob/master/51.md
+- https://github.com/nostr-protocol/nips/blob/master/52.md
+- https://github.com/nostr-protocol/nips/blob/master/53.md
+- https://github.com/nostr-protocol/nips/blob/master/54.md
+- https://github.com/nostr-protocol/nips/blob/master/55.md
+- https://github.com/nostr-protocol/nips/blob/master/56.md
+- https://github.com/nostr-protocol/nips/blob/master/57.md
+- https://github.com/nostr-protocol/nips/blob/master/58.md
+- https://github.com/nostr-protocol/nips/blob/master/59.md
+- https://github.com/nostr-protocol/nips/blob/master/60.md
+- https://github.com/nostr-protocol/nips/blob/master/61.md
+- https://github.com/nostr-protocol/nips/blob/master/62.md
+- https://github.com/nostr-protocol/nips/blob/master/64.md
+- https://github.com/nostr-protocol/nips/blob/master/65.md
+- https://github.com/nostr-protocol/nips/blob/master/66.md
+- https://github.com/nostr-protocol/nips/blob/master/68.md
+- https://github.com/nostr-protocol/nips/blob/master/69.md
+- https://github.com/nostr-protocol/nips/blob/master/70.md
+- https://github.com/nostr-protocol/nips/blob/master/71.md
+- https://github.com/nostr-protocol/nips/blob/master/72.md
+- https://github.com/nostr-protocol/nips/blob/master/73.md
+- https://github.com/nostr-protocol/nips/blob/master/75.md
+- https://github.com/nostr-protocol/nips/blob/master/77.md
+- https://github.com/nostr-protocol/nips/blob/master/78.md
+- https://github.com/nostr-protocol/nips/blob/master/7D.md
+- https://github.com/nostr-protocol/nips/blob/master/84.md
+- https://github.com/nostr-protocol/nips/blob/master/86.md
+- https://github.com/nostr-protocol/nips/blob/master/87.md
+- https://github.com/nostr-protocol/nips/blob/master/88.md
+- https://github.com/nostr-protocol/nips/blob/master/89.md
+- https://github.com/nostr-protocol/nips/blob/master/90.md
+- https://github.com/nostr-protocol/nips/blob/master/92.md
+- https://github.com/nostr-protocol/nips/blob/master/94.md
+- https://github.com/nostr-protocol/nips/blob/master/96.md
+- https://github.com/nostr-protocol/nips/blob/master/98.md
+- https://github.com/nostr-protocol/nips/blob/master/99.md
+- https://github.com/nostr-protocol/nips/blob/master/A0.md
+- https://github.com/nostr-protocol/nips/blob/master/B0.md
+- https://github.com/nostr-protocol/nips/blob/master/B7.md
+- https://github.com/nostr-protocol/nips/blob/master/C0.md
+- https://github.com/nostr-protocol/nips/blob/master/C7.md
+
+## Guidelines
+
 - All changes must include unit tests and update relevant docs.
 - Use clear names and remove unused imports.
 - Prefer readable, maintainable code over clever shortcuts.

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

@@ -34,6 +34,9 @@ jobs:
             const files = await github.paginate(
               github.rest.pulls.listFiles, { owner, repo, pull_number: pr.number }
             );
+            const commits = await github.paginate(
+              github.rest.pulls.listCommits, { owner, repo, pull_number: pr.number }
+            );
             const extsCode = ['.js','.ts','.tsx','.jsx','.py','.rb','.go','.rs','.java','.kt','.cs','.php','.c','.cc','.cpp','.m','.mm','.swift','.scala','.sh','.yml','.yaml','.json','.toml'];
             const extsTests = ['.spec.','.test.','/tests/','/__tests__/'];
             const codeTouched = files.some(f =>
@@ -42,10 +45,12 @@ jobs:
               extsTests.some(tok => f.filename.includes(tok)));
             // 1) Scope ≤ 300 lines (from GitHub blog checklist)
             const scopeOK = totalChanged <= 300;
-            // 2) Title = verb + object (simple verb list heuristic)
+            // 2) Title and commits follow type: description (verb + object)
             const title = prData.title.trim();
-            const verbs = ['Add','Fix','Update','Refactor','Remove','Implement','Document','Docs','Test','Build','Improve','Feat','Enable','Disable','Migrate'];
-            const titleOK = new RegExp(`^(${verbs.join('|')})\\b.+`).test(title);
+            const types = ['feat','fix','docs','refactor','test','chore','ci','build','perf','style'];
+            const naming = `^(${types.join('|')}):\\s+[A-Z][^\\s]*\\s+.+`;
+            const titleOK = new RegExp(naming).test(title);
+            const commitsOK = commits.every(c => new RegExp(naming).test(c.commit.message.split('\\n')[0]));
             // 3) Description “why now?” + links to issue
             const body = (prData.body || '').trim();
             const hasIssueLink = /#[0-9]+|https?:\/\/github\.com\/.+\/issues\/[0-9]+/i.test(body);
@@ -73,7 +78,7 @@ jobs:
               `| Pass | Check |`,
               `|:----:|:------|`,
               row(`Scope ≤ 300 changed lines (current: ${totalChanged})`, scopeOK, scopeOK ? '' : 'Consider splitting into smaller PRs (stacking).'),
-              row(`Title starts with a verb + object (e.g., "Refactor auth middleware")`, titleOK),
+              row(`Title and commits use type: description (verb + object)`, titleOK && commitsOK),
               row(`Description answers "why now?" and links an issue`, descOK, hasIssueLink ? '' : 'Add a linked issue (#123) or URL.'),
               row(`Highlight breaking changes with **BREAKING** or ⚠️ BREAKING`, breakingOK, containsBreakingWord && !breakingFlagPresent ? 'Add explicit BREAKING flag.' : ''),
               row(`Request specific feedback (e.g., "Concurrency strategy OK?")`, feedbackOK),
@@ -85,7 +90,7 @@ jobs:
             // Determine blocking result (fail if any required check fails)
             const failures = [];
             if (!scopeOK) failures.push('Scope > 300 lines');
-            if (!titleOK) failures.push('Title not verb + object');
+            if (!titleOK || !commitsOK) failures.push('Naming format invalid');
             if (!descOK) failures.push('Description lacks why/issue link');
             if (!breakingOK) failures.push('Missing explicit BREAKING flag');
             if (!feedbackOK) failures.push('No specific feedback requested');

AGENTS.md

@@ -1,5 +1,97 @@
 # Repo Guidelines
 
+## NIPs
+
+- https://github.com/nostr-protocol/nips/blob/master/01.md
+- https://github.com/nostr-protocol/nips/blob/master/02.md
+- https://github.com/nostr-protocol/nips/blob/master/03.md
+- https://github.com/nostr-protocol/nips/blob/master/04.md
+- https://github.com/nostr-protocol/nips/blob/master/05.md
+- https://github.com/nostr-protocol/nips/blob/master/06.md
+- https://github.com/nostr-protocol/nips/blob/master/07.md
+- https://github.com/nostr-protocol/nips/blob/master/08.md
+- https://github.com/nostr-protocol/nips/blob/master/09.md
+- https://github.com/nostr-protocol/nips/blob/master/10.md
+- https://github.com/nostr-protocol/nips/blob/master/11.md
+- https://github.com/nostr-protocol/nips/blob/master/12.md
+- https://github.com/nostr-protocol/nips/blob/master/13.md
+- https://github.com/nostr-protocol/nips/blob/master/14.md
+- https://github.com/nostr-protocol/nips/blob/master/15.md
+- https://github.com/nostr-protocol/nips/blob/master/16.md
+- https://github.com/nostr-protocol/nips/blob/master/17.md
+- https://github.com/nostr-protocol/nips/blob/master/18.md
+- https://github.com/nostr-protocol/nips/blob/master/19.md
+- https://github.com/nostr-protocol/nips/blob/master/20.md
+- https://github.com/nostr-protocol/nips/blob/master/21.md
+- https://github.com/nostr-protocol/nips/blob/master/22.md
+- https://github.com/nostr-protocol/nips/blob/master/23.md
+- https://github.com/nostr-protocol/nips/blob/master/24.md
+- https://github.com/nostr-protocol/nips/blob/master/25.md
+- https://github.com/nostr-protocol/nips/blob/master/26.md
+- https://github.com/nostr-protocol/nips/blob/master/27.md
+- https://github.com/nostr-protocol/nips/blob/master/28.md
+- https://github.com/nostr-protocol/nips/blob/master/29.md
+- https://github.com/nostr-protocol/nips/blob/master/30.md
+- https://github.com/nostr-protocol/nips/blob/master/31.md
+- https://github.com/nostr-protocol/nips/blob/master/32.md
+- https://github.com/nostr-protocol/nips/blob/master/33.md
+- https://github.com/nostr-protocol/nips/blob/master/34.md
+- https://github.com/nostr-protocol/nips/blob/master/35.md
+- https://github.com/nostr-protocol/nips/blob/master/36.md
+- https://github.com/nostr-protocol/nips/blob/master/37.md
+- https://github.com/nostr-protocol/nips/blob/master/38.md
+- https://github.com/nostr-protocol/nips/blob/master/39.md
+- https://github.com/nostr-protocol/nips/blob/master/40.md
+- https://github.com/nostr-protocol/nips/blob/master/42.md
+- https://github.com/nostr-protocol/nips/blob/master/44.md
+- https://github.com/nostr-protocol/nips/blob/master/45.md
+- https://github.com/nostr-protocol/nips/blob/master/46.md
+- https://github.com/nostr-protocol/nips/blob/master/47.md
+- https://github.com/nostr-protocol/nips/blob/master/48.md
+- https://github.com/nostr-protocol/nips/blob/master/49.md
+- https://github.com/nostr-protocol/nips/blob/master/50.md
+- https://github.com/nostr-protocol/nips/blob/master/51.md
+- https://github.com/nostr-protocol/nips/blob/master/52.md
+- https://github.com/nostr-protocol/nips/blob/master/53.md
+- https://github.com/nostr-protocol/nips/blob/master/54.md
+- https://github.com/nostr-protocol/nips/blob/master/55.md
+- https://github.com/nostr-protocol/nips/blob/master/56.md
+- https://github.com/nostr-protocol/nips/blob/master/57.md
+- https://github.com/nostr-protocol/nips/blob/master/58.md
+- https://github.com/nostr-protocol/nips/blob/master/59.md
+- https://github.com/nostr-protocol/nips/blob/master/60.md
+- https://github.com/nostr-protocol/nips/blob/master/61.md
+- https://github.com/nostr-protocol/nips/blob/master/62.md
+- https://github.com/nostr-protocol/nips/blob/master/64.md
+- https://github.com/nostr-protocol/nips/blob/master/65.md
+- https://github.com/nostr-protocol/nips/blob/master/66.md
+- https://github.com/nostr-protocol/nips/blob/master/68.md
+- https://github.com/nostr-protocol/nips/blob/master/69.md
+- https://github.com/nostr-protocol/nips/blob/master/70.md
+- https://github.com/nostr-protocol/nips/blob/master/71.md
+- https://github.com/nostr-protocol/nips/blob/master/72.md
+- https://github.com/nostr-protocol/nips/blob/master/73.md
+- https://github.com/nostr-protocol/nips/blob/master/75.md
+- https://github.com/nostr-protocol/nips/blob/master/77.md
+- https://github.com/nostr-protocol/nips/blob/master/78.md
+- https://github.com/nostr-protocol/nips/blob/master/7D.md
+- https://github.com/nostr-protocol/nips/blob/master/84.md
+- https://github.com/nostr-protocol/nips/blob/master/86.md
+- https://github.com/nostr-protocol/nips/blob/master/87.md
+- https://github.com/nostr-protocol/nips/blob/master/88.md
+- https://github.com/nostr-protocol/nips/blob/master/89.md
+- https://github.com/nostr-protocol/nips/blob/master/90.md
+- https://github.com/nostr-protocol/nips/blob/master/92.md
+- https://github.com/nostr-protocol/nips/blob/master/94.md
+- https://github.com/nostr-protocol/nips/blob/master/96.md
+- https://github.com/nostr-protocol/nips/blob/master/98.md
+- https://github.com/nostr-protocol/nips/blob/master/99.md
+- https://github.com/nostr-protocol/nips/blob/master/A0.md
+- https://github.com/nostr-protocol/nips/blob/master/B0.md
+- https://github.com/nostr-protocol/nips/blob/master/B7.md
+- https://github.com/nostr-protocol/nips/blob/master/C0.md
+- https://github.com/nostr-protocol/nips/blob/master/C7.md
+
 ## Description
 nostr-java is a java implementation of the nostr protocol. The specification is available on github, here: https://github.com/nostr-protocol/nips
 The URL format for the NIPs is https://github.com/nostr-protocol/nips/blob/master/XX.md where XX is the NIP number. For example, the specification for NIP-01 is available at the URL https://github.com/nostr-protocol/nips/blob/master/01.md etc.
@@ -23,7 +115,19 @@ The URL format for the NIPs is https://github.com/nostr-protocol/nips/blob/maste
 
 ## Pull Requests
 
+- Use the pull request template at `.github/pull_request_template.md` and fill out all sections.
 - Summarize the changes made and describe how they were tested.
 - Include any limitations or known issues in the description.
 - Add a "Network Access" section summarizing blocked domains if network requests were denied.
-- Ensure all new features, modules, or dependencies are properly documented in the `README.md` file.
+- Ensure all new features, modules, or dependencies are properly documented in the `README.md` file.
+## PR Quality Gate
+
+- PR summaries must reference modified files with file path citations (e.g. `F:path/to/file.java†L1-L2`).
+- PR titles and commit messages must follow the `type: description` naming format.
+- Allowed types: feat, fix, docs, refactor, test, chore, ci, build, perf, style.
+- The description should be a concise verb + object phrase (e.g., `refactor: Refactor auth middleware to async`).
+- Include a Testing section listing the commands run. Prefix each command with ✅, ⚠️, or ❌ and cite relevant terminal output.
+- If network requests fail, add a Network Access section noting blocked domains.
+- When TODOs or placeholders remain, include a Notes section.
+- Review AI-generated changes with developer expertise, ensuring you understand why the code works and that it remains resilient, scalable, and secure.
+- Use `rg` for search instead of `ls -R` or `grep -R`.

CONTRIBUTING.md

@@ -0,0 +1,16 @@
+# Contributing to nostr-java
+
+nostr-java implements the Nostr protocol. A complete index of current Nostr Implementation Possibilities (NIPs) is listed in [AGENTS.md](AGENTS.md).
+
+## Development Guidelines
+
+- Run `mvn -q verify` from the repository root before committing.
+- Use `rg` for code searches instead of `ls -R` or `grep -R`.
+- PR titles and commit messages must follow the `type: description` format.
+  - Allowed types: `feat`, `fix`, `docs`, `refactor`, `test`, `chore`, `ci`, `build`, `perf`, `style`.
+  - The description must be a concise verb + object phrase (e.g., `refactor: Refactor auth middleware to async`).
+- Summaries in pull requests must cite file paths and include testing output.
+- Open pull requests using the template at `.github/pull_request_template.md` and complete every section.
+
+By following these conventions, contributors help keep the codebase maintainable and aligned with the Nostr specifications.
+