feat: implement modern repository best practices, CI Gatekeeper, and Go 1.23+ compatibility

.agents/AGENTS.md

@@ -103,6 +103,9 @@ For all tests in this repository, strictly adhere to the following conventions:
 
 Before concluding any code modification task, agents MUST run and verify the following commands succeed without errors or warnings:
 1. `gofmt -s -w .`
-2. `go test -race ./...`
-3. `golangci-lint run ./...` (or `revive ./... && go vet ./...`)
+2. `go mod tidy && git diff --exit-code go.mod go.sum`
+3. `go test -race ./...`
+4. `golangci-lint run ./...` (or `revive ./... && go vet ./...`)
+5. `govulncheck ./...`
+
 

.gitattributes

@@ -1 +1,24 @@
+# Auto-detect text files and normalize line endings to LF
 * text=auto eol=lf
+
+# Explicit text files
+*.go text eol=lf
+*.md text eol=lf
+*.yml text eol=lf
+*.yaml text eol=lf
+*.json text eol=lf
+*.mod text eol=lf
+*.sum text eol=lf
+*.txt text eol=lf
+
+# Export ignore for archive tarballs
+.github export-ignore
+.gitignore export-ignore
+.gitattributes export-ignore
+.golangci.yml export-ignore
+revive.toml export-ignore
+codecov.yml export-ignore
+CONTRIBUTING.md export-ignore
+SECURITY.md export-ignore
+AGENTS.md export-ignore
+CLAUDE.md export-ignore

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,78 @@
+name: 🐛 Bug Report
+description: Report a bug, panic, incorrect behavior, or unexpected allocation
+title: "[Bug]: "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for reporting an issue! Please provide as much detail as possible to help us diagnose and fix the problem.
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: A clear and concise description of what the bug is.
+      placeholder: Describe what happened...
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Minimal Reproducible Example
+      description: |
+        Please provide a short, self-contained Go code snippet that reproduces the issue.
+      placeholder: |
+        ```go
+        package main
+
+        import (
+            "fmt"
+            "github.com/lock14/collections/treeset"
+        )
+
+        func main() {
+            // Your code here
+        }
+        ```
+      render: go
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+      description: What did you expect to happen?
+      placeholder: Explain what behavior was expected...
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual Behavior & Output
+      description: What actually happened? Include error messages or stack traces if applicable.
+      placeholder: |
+        panic: runtime error...
+    validations:
+      required: true
+
+  - type: input
+    id: go-version
+    attributes:
+      label: Go Version
+      description: Output of `go version`
+      placeholder: e.g. go version go1.27.0 windows/amd64
+    validations:
+      required: true
+
+  - type: input
+    id: environment
+    attributes:
+      label: Operating System & Architecture
+      description: OS and Architecture (e.g. macOS arm64, Linux amd64, Windows amd64)
+      placeholder: e.g. Linux amd64
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security Vulnerability Reporting
+    url: https://github.com/lock14/collections/security/policy
+    about: Please report security vulnerabilities privately according to our security policy.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,51 @@
+name: 💡 Feature Request
+description: Propose a new data structure, collection method, or architectural enhancement
+title: "[Feature]: "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for suggesting a feature! Please describe the use case and API proposal in detail.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem or Use Case
+      description: Is your feature request related to a specific problem or missing collection type?
+      placeholder: I need a data structure that...
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed Solution / API Design
+      description: Describe the proposed API, types, constructors, and method signatures.
+      placeholder: |
+        ```go
+        type MyNewDataStructure[T any] struct { ... }
+        func New[T any]() *MyNewDataStructure[T]
+        ```
+      render: go
+    validations:
+      required: true
+
+  - type: textarea
+    id: performance
+    attributes:
+      label: Performance & Complexity Characteristics
+      description: Describe expected time and space complexity, allocation profile, and growth strategy.
+      placeholder: |
+        - Read operations (Get, Contains, Peek): O(1) time, 0 allocations
+        - Insertions / Deletions: Amortized O(1)
+    validations:
+      required: false
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives Considered
+      description: Describe any alternative solutions or workarounds you have considered.
+    validations:
+      required: false

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,32 @@
+## Description
+
+Please provide a summary of the changes introduced in this pull request, including motivation and context.
+
+## Type of Change
+
+- [ ] 🐛 Bug fix (non-breaking change which fixes an issue)
+- [ ] ✨ New feature (non-breaking change which adds functionality)
+- [ ] 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] ⚡ Performance optimization (latency, CPU, memory, or allocation improvements)
+- [ ] 📝 Documentation update
+- [ ] 🔧 Tooling / CI / Build configuration
+
+## Repository Design & Architecture Checklist
+
+- [ ] **Generics & Type Safety:** Uses Go generics cleanly; avoids unnecessary `any` boxing or runtime assertions.
+- [ ] **Interface Compliance:** Concrete structures declare compile-time interface assertions (`var _ collections.Interface = (*Type)(nil)`).
+- [ ] **Standard Iteration:** Exposes standard Go 1.23+ `iter.Seq` / `iter.Seq2` iterators respecting early yield termination.
+- [ ] **Zero-Allocation Reads:** Read operations (`Get`, `Contains`, `Peek`, `Size`, `Empty`) produce 0 B/op and 0 allocs/op in benchmarks.
+- [ ] **Stringer:** Implements `fmt.Stringer` matching Go slice `[e1 e2]` or map `map[k:v]` format.
+- [ ] **Panic Semantics:** Slice-like indexing panics on out-of-bounds; positional extractions panic on empty; targeted map/set removals are silent no-ops.
+- [ ] **Standard Package Layout:** Follows the 4-file package structure (`<pkg>.go`, `<pkg>_test.go`, `<pkg>_bench_test.go`, `example_<pkg>_test.go`).
+
+## Verification & Testing
+
+- [ ] Ran `gofmt -s -w .` (no unformatted files).
+- [ ] Ran `go test -race ./...` (all unit tests pass without data races).
+- [ ] Ran `golangci-lint run ./...` (or `revive ./... && go vet ./...`) with zero warnings.
+- [ ] Added table-driven unit tests in `<pkg>_test.go`.
+- [ ] Added/updated benchmarks in `<pkg>_bench_test.go` and verified no regressions with `benchdiff` / `benchstat`.
+- [ ] Added/updated runnable examples with `// Output:` in `example_<pkg>_test.go`.
+- [ ] Documentation (Go doc comments, `README.md`, `AGENTS.md`) is updated and synchronized.

.github/dependabot.yml

@@ -0,0 +1,32 @@
+version: 2
+updates:
+  # Go modules
+  - package-ecosystem: gomod
+    directory: "/"
+    schedule:
+      interval: weekly
+      day: monday
+    labels:
+      - dependencies
+      - go
+    open-pull-requests-limit: 10
+    groups:
+      go-minor-patch:
+        update-types:
+          - minor
+          - patch
+
+  # GitHub Actions
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly
+      day: monday
+    labels:
+      - dependencies
+      - ci
+    open-pull-requests-limit: 10
+    groups:
+      actions:
+        patterns:
+          - "*"

.github/workflows/benchmark.yml

@@ -6,6 +6,13 @@ on:
   pull_request:
     branches: [ "main" ]
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
 jobs:
   detect-packages:
     name: Detect Changed Packages

.github/workflows/ci.yml

@@ -0,0 +1,144 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  format-and-tidy:
+    name: Format & Module Hygiene
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: 'go.mod'
+
+      - name: Verify dependencies
+        run: |
+          go mod verify
+          go mod download
+
+      - name: Check Formatting
+        run: |
+          if [ -n "$(gofmt -s -l .)" ]; then
+            echo "The following files are not formatted properly:"
+            gofmt -s -l .
+            echo "Please run 'gofmt -s -w .' locally and commit the changes."
+            exit 1
+          fi
+
+      - name: Check go mod tidy
+        run: |
+          go mod tidy
+          git diff --exit-code go.mod go.sum
+
+  test:
+    name: Test (Go ${{ matrix.go }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        go:
+          - "1.27"
+          - "stable"
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: ${{ matrix.go }}
+
+      - name: Build
+        run: go build -v ./...
+
+      - name: Run tests with race detector
+        run: go test -v -race -shuffle=on -coverprofile=coverage.out -covermode=atomic ./...
+
+      - name: Upload coverage to Codecov
+        if: matrix.go == 'stable'
+        uses: codecov/codecov-action@v5
+        with:
+          files: ./coverage.out
+          fail_ci_if_error: false
+
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: 'go.mod'
+
+      - name: Run go vet
+        run: go vet ./...
+
+      - name: Install and run revive
+        run: |
+          go install github.com/mgechev/revive@latest
+          revive -config revive.toml -formatter friendly ./...
+
+  govulncheck:
+    name: Vulnerability Scan
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: 'go.mod'
+
+      - name: Run govulncheck
+        uses: golang/govulncheck-action@v1
+        with:
+          go-version-file: 'go.mod'
+
+  # CI Gatekeeper Aggregator Job
+  # This single job acts as the required status check for branch protection rules.
+  ci-gatekeeper:
+    name: CI Gatekeeper
+    runs-on: ubuntu-latest
+    needs:
+      - format-and-tidy
+      - test
+      - lint
+      - govulncheck
+    if: always()
+    steps:
+      - name: Evaluate Upstream Job Statuses
+        run: |
+          echo "Evaluating CI pipeline job results:"
+          echo "Format & Tidy: ${{ needs.format-and-tidy.result }}"
+          echo "Test Matrix:   ${{ needs.test.result }}"
+          echo "Lint:          ${{ needs.lint.result }}"
+          echo "Govulncheck:   ${{ needs.govulncheck.result }}"
+
+          if [ "${{ needs.format-and-tidy.result }}" != "success" ] || \
+             [ "${{ needs.test.result }}" != "success" ] || \
+             [ "${{ needs.lint.result }}" != "success" ] || \
+             [ "${{ needs.govulncheck.result }}" != "success" ]; then
+            echo "❌ CI Gatekeeper failed: One or more upstream checks did not succeed."
+            exit 1
+          fi
+
+          echo "✅ All required CI checks passed successfully!"