Add ComparableMap type, improve doc comments, and update tooling

[min0625]

Summary

Add a new ComparableMap type that requires the value type to implement comparable, providing safe CompareAndDelete and CompareAndSwap operations without risk of runtime panic.

Changes

New Features

• ComparableMap[Key, Value comparable]: A drop-in replacement for Map when CompareAndDelete or CompareAndSwap is needed. Enforces comparability at compile time.
• CompareAndDelete and CompareAndSwap on Map are now explicitly deprecated with clear guidance to use ComparableMap instead.

Documentation

• Added package-level doc comment to map.go explaining both types.
• Added Go doc comments to all exported methods on Map.
• Improved README.md with clearer descriptions, a ComparableMap quick-start example, and a Types section.

Tooling & Infrastructure

• Bumped Go version to 1.24.0 in go.mod.
• Simplified Makefile: removed dependency on gofumpt/tools/ module; lint now runs golangci-lint -v, test runs with -race -failfast.
• Replaced .tool-versions with mise.toml.
• Added .golangci.yaml linter config.
• Added GitHub Actions workflows (pr-check.yml, codeql.yml).
• Added AGENTS.md with development guidelines.
• Added map_test.go with unit tests (race-detector enabled).
• Added devcontainer and VS Code settings for consistent development environment.

[github-advanced-security]

You are seeing this message because GitHub Code Scanning has recently been set up for this repository, or this pull request contains the workflow file for the Code Scanning tool.

What Enabling Code Scanning Means:

• The 'Security' tab will display more code scanning analysis results (e.g., for the default branch).
• Depending on your configuration and choice of analysis tool, future pull requests will be annotated with code scanning analysis results.
• You will be able to see the analysis results for the pull request's branch on this overview once the scans have completed and the checks have passed.

For more information about GitHub Code Scanning, check out the documentation.

[Copilot]

Pull request overview

This PR introduces a new ComparableMap type to provide compile-time safety for CompareAndDelete/CompareAndSwap, expands API documentation/examples, and updates repo tooling/CI for a more standardized developer workflow.

Changes:

• Add ComparableMap[Key, Value comparable] and deprecate the unsafe Map compare operations.
• Add/refresh docs and examples (package docs, README, example tests) plus comprehensive unit/concurrency tests.
• Modernize tooling (Go version bump, golangci-lint config, Makefile simplification, mise/devcontainer, GitHub Actions workflows).

Reviewed changes

Copilot reviewed 18 out of 19 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
comparable_map.go	Adds ComparableMap wrapper intended to enforce comparability for CAS/CAD operations.
map.go	Adds package/type/method doc comments; deprecates Map compare methods with guidance.
map_test.go	Adds unit + concurrent tests for both Map and ComparableMap.
map_example_test.go	Updates examples to use ComparableMap for compare operations; minor callback cleanup.
README.md	Adds clearer type descriptions and a ComparableMap quick-start snippet.
go.mod	Bumps Go version directive to 1.24.0.
Makefile	Simplifies lint/test targets; adds fix via golangci-lint.
.golangci.yaml	Adds golangci-lint v2 configuration.
mise.toml	Replaces asdf tool versions with mise-managed tool pins.
.tool-versions	Removes asdf tool-version file.
.github/workflows/pr-check.yml	Adds PR lint+test workflow using mise + make.
.github/workflows/codeql.yml	Adds CodeQL workflow for Go analysis.
.devcontainer/devcontainer.json	Adds devcontainer definition for consistent environment setup.
.devcontainer/post_create.sh	Sets up mise + installs dev tools inside devcontainer.
.vscode/settings.json	Adds VS Code Go tooling settings aligned with golangci-lint v2.
AGENTS.md	Adds development and contribution guidelines for agents.
tools/tools.go	Removes tools module tooling file (gofumpt).
tools/go.mod	Removes tools module go.mod.
tools/go.sum	Removes tools module go.sum.
.agents/skills/**/SKILL.md	Adds agent skill documentation files.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.