feat(v1.6): batch operations, benchmark suite & post-v1.6 cleanup (#46)

* docs(v1.6): create Phase 7 batch operations plans

4 plans covering:
- 07-01: Core infrastructure (Cache/cacher interfaces, concreteCache, fakeCacher, tests, docs)
- 07-02: mem + memcache providers (single-lock, GetMulti, per-key goroutines)
- 07-03: redis + valkey providers (Pipeline, DoMulti)
- 07-04: postgres provider + E2E tests + race verification

All BATCH-01 through BATCH-07 requirements mapped.
All D-01 through D-14 decisions implemented.

* docs(v1.6): add Phase 7 research and patterns artifacts

* fix(07-batch-operations): revise plans to use BatchCache interface, fix D-02 BLOCKER

Plan 01: Replace Cache interface batch methods with BatchCache[K,V]
embedding interface per D-02 (Cache[K,V] unchanged, backward
compatibility preserved). NewConcreteCache returns BatchCache.

Plans 02-04: Cascade BatchCache through provider New() return types
and E2E test infrastructure. Provider tests and E2E tests access
batch methods directly through BatchCache interface.

BREAKING: None — BatchCache embeds Cache, fully backward compatible.

* feat(07-batch-operations): add BatchCache interface, cacher methods, delegation, and tests

- Add BatchCache[K,V] embedding interface to cache.go that embeds
  Cache[K,V] and adds MGet/MSet/MDel (D-02 backward compatible)
- Add MGetFunc/MSetFunc/MDelFunc to unexported cacher interface (D-01)
- Change NewConcreteCache return type to BatchCache[K,V]
- Add concreteCache MGet/MSet/MDel delegation to cacher
- Add provider stub implementations for mem, redis, valkey, memcache,
  postgres to unblock compilation (Rule 3)
- Add fakeCacher batch methods for unit testing (Rule 3, vet fix)
- Add TestConcreteCache_Batch with 7 subtests (found/missing/empty/error)
- Add TestMemCache_Batch with 6 subtests (found/missing/empty/TTL)
- Use errors.Join for error accumulation in provider stubs (D-06)

* docs(07-batch-operations): add batch operations documentation to package doc

- Add BatchCache[K,V] section with code example for type assertion
- Document MGet/MSet/MDel with per-provider optimal strategies
- Reference backward-compatible design (Cache[K,V] unchanged)

* docs(07-batch-operations): complete plan 01 infrastructure

* feat(07-batch-operations): implement redis Pipeline batch operations

Replace per-key fallback stubs with go-redis Pipeline implementations:
- MGetFunc: Pipeline with per-key Get, individual result checking,
  redis.Nil ignored (D-06 best-effort)
- MSetFunc: Pipeline with Set, single TTL via resolveTTL
- MDelFunc: Pipeline with Del

Change New() return type from cache.Cache[K,V] to cache.BatchCache[K,V]
(backward compatible via embedded Cache interface).

Remove unused 'errors' import (no longer needs errors.Join).
Package compiles and vets clean.

* feat(07-batch-operations): implement mem and memcache batch operations with optimized strategies

mem: single lock acquisition per batch (D-07), New returns BatchCache
memcache: GetMulti for MGet (D-08), per-key goroutines for MSet/MDel
Both: New() return type changed to cache.BatchCache[K,V] (backward compatible)

* feat(07-batch-operations): implement valkey DoMulti batch operations

Replace per-key fallback stubs with valkey-go DoMulti implementations:
- MGetFunc: DoMulti with B().Get() per key, individual result checking,
  valkey.Nil ignored (D-06 best-effort), initErr guard
- MSetFunc: DoMulti with B().Set() per item, optional Px for TTL,
  initErr guard, iterates responses for errors
- MDelFunc: DoMulti with B().Del() per key, initErr guard,
  iterates responses for errors

Change New() return type from cache.Cache[K,V] to cache.BatchCache[K,V]
(backward compatible via embedded Cache interface).

Package compiles and vets clean.

* test(07-batch-operations): add provider-level batch tests for mem and memcache

mem_test.go: remove type assertions (New now returns BatchCache directly)
memcache_test.go: add TestMemcacheCache_Batch (6 subtests, skipIfNoMemcache)
memcache_internal_test.go: add TestMemcacheBatch_NoServer (5 subtests, no server needed)

* test(07-batch-operations): add provider batch integration tests

Add TestRedisCache_Batch and TestValkeyCache_Batch with 6 subtests each:
- mget_returns_found: Set two keys, MGet with one missing
- mget_empty_keys: MGet() returns empty map
- mset_stores_all: MSet two keys, Get each
- mset_with_ttl: MSet with zero TTL still stores
- mdel_deletes: Set two, MDel, Get returns error
- mdel_empty_keys: MDel() returns no error

All tests use skipIfNoRedis/skipIfNoValkey guards and are safe
to run with or without Docker infrastructure.

* docs(07-batch-operations): complete 07-02 plan

* docs(07-batch-operations): complete plan 07-03 redis/valkey batch operations

SUMMARY: Implemented Pipeline-based batch operations for redis (D-09)
and DoMulti-based batch operations for valkey (D-10). Both New() return
BatchCache[K,V]. Added 12 integration test subtests across both providers.
Coverage thresholds satisfied.

* feat(07-04): implement postgres batch ops with SendBatch + change New return type

- Change New() return type from cache.Cache[K,V] to cache.BatchCache[K,V]
- MGetFunc: uses pgx SendBatch with parameterized SELECT queries
- MSetFunc: uses pgx SendBatch with INSERT ON CONFLICT (upsert)
- MDelFunc: uses pgx SendBatch with DELETE queries
- All batch methods consume all results before closing (defer br.Close())
- Error accumulation via errors.Join for MSetFunc/MDelFunc
- Backward compatible: BatchCache embeds Cache

Per D-11 (pgx SendBatch for batch ops), BATCH-06.

* test(07-04): add postgres batch integration tests

- Change newTestCache return type to cache.BatchCache[string,string]
- Add TestPostgresCache_Batch with 6 subtests:
  - mget_returns_found: MGet found + missing keys
  - mget_empty_keys: MGet with no args returns empty
  - mset_stores_all: MSet stores both keys, Get verifies
  - mset_empty_map: MSet with empty map does not error
  - mdel_deletes: MDel removes keys, Get returns ErrMiss
  - mdel_empty_keys: MDel with no args does not error
- Uses skipIfNoPostgres pattern for skipping when Postgres unavailable

* feat(07-04): update E2E infra to BatchCache + add batch subtests + race verification

- Change providerCase.fn type to cache.BatchCache[string,string]
- Change runCacheE2E parameter type to cache.BatchCache[string,string]
- Update all provider closures return types (mem, redis, valkey, memcache, postgres)
- Update postgres variable type in TestCacheE2E_Postgres
- Add 7 batch E2E subtests: mget_returns_multiple, mget_empty_keys,
  mset_stores_all_keys, mset_empty_map, mdel_removes_all_keys,
  mdel_idempotent, mdel_empty_keys
- All batch E2E subtests pass across all 5 providers
- Race detector passes on all batch operations (BATCH-07, D-14)

* docs(07-04): complete postgres batch + E2E batch subtests + race verification

* docs(08): capture phase context for benchmark suite

* docs(state): record phase 8 context session

* docs(08): create phase 8 benchmark suite plans

* feat(08-01): create thundering-herd benchmark with mem provider

Add cache/bench_test.go with:
- BenchmarkSingleflightGetOrSet with sub-benchmarks for concurrency
  levels 10, 50, 100, 500
- benchmarkHerdNaive: TOCTOU pattern demonstrating thundering-herd
  (setter runs N times per iteration)
- benchmarkHerdSingleflight: via BatchCache.GetOrSet showing dedup
  (setter runs exactly once per iteration)
- benchmarkHerdSingleflightConcurrencyLoop: shared loop for provider
  subtests
- skipIfNoDocker: runtime Docker availability gate

Deviation: naive path uses check-outside/compute-outside-store (TOCTOU)
pattern instead of the plan's described lock-everything approach, because
a full mutex scope inherently deduplicates and defeats the benchmark's
purpose of demonstrating the thundering-herd problem (Rule 1 - Bug)

* feat(08-01): add Docker-gated thundering-herd subtests for redis, valkey, memcache, postgres

Extend BenchmarkSingleflightGetOrSet with Docker-backed provider subtests:
- redis: testcontainers redis:7-alpine container
- valkey: testcontainers valkey/valkey:8-alpine container
- memcache: testcontainers memcached:1-alpine container
- postgres: testcontainers postgres:16-alpine container with
  connection retry loop
- Each subtest gated by skipIfNoDocker (checks DOCKER_HOST + docker info)
- Uses benchmarkHerdSingleflightConcurrencyLoop for shared concurrency
  level iteration across providers

Also improve skipIfNoDocker to check DOCKER_HOST env var alongside
docker info (required by testcontainers for non-default Docker sockets
like Orbstack).

* docs(08-01): complete thundering-herd benchmark plan

* feat(08-benchmark-suite): add BenchmarkBatch/MGet with per-key comparison

- prePopulateKeys helper for setting up batch benchmark keys
- benchmarkMGetNative for native MGet batch path
- benchmarkMGetPerKey for per-key Get loop fallback
- BenchmarkBatch/MGet sub-benchmarks at sizes 1, 10, 100, 1000
- Native path shows ~14% lower ns/op for batch sizes >= 100

* feat(08-benchmark-suite): add BenchmarkBatch/MSet and MDel with per-key comparison

- MSet native vs per-key at sizes 1, 10, 100, 1000
- MDel native vs per-key at sizes 1, 10, 100, 1000
- Native MDel shows ~44% lower ns/op for Size100
- Native MSet consistently lower allocs/op (single-lock benefit)
- Keys unique per iteration for write/delete benchmarks

* docs(08-benchmark-suite): complete 08-02 batch benchmark plan

* feat(08-benchmark-suite): add make benchmark and make benchmark-quick targets

- Add  target: go test -bench=. -benchtime=1s -count=5 -benchmem ./cache/...
- Add  target: go test -bench=. -benchtime=100ms -count=1 -benchmem ./cache/...
- Place targets between test-e2e and coverage, maintaining alphabetical order
- Update .PHONY to include benchmark and benchmark-quick

Per D-11/D-12/D-13 from phase context.

* feat(08-benchmark-suite): add Docker-gated batch benchmark subtests for all providers

- Add runBatchBenchmarks helper function extracting the shared
  MGet/MSet/MDel benchmark structure for reuse across providers
- Add Docker-gated provider subtests for redis, valkey, memcache,
  and postgres inside BenchmarkBatch, gated by skipIfNoDocker
- Fix Makefile benchmark targets to pass DOCKER_HOST env var so
  Docker-backed benchmarks actually run when Docker is available
- Providers create test containers with pinned images:
  redis:7-alpine, valkey/valkey:8-alpine, memcached:1-alpine,
  postgres:16-alpine

Per D-08/D-09 from phase context.

* docs(08-benchmark-suite): complete 08-03 make benchmark + Docker-gated batch subtests plan

* docs: update for v1.6 cache dedup milestone (batch ops, benchmarks, changelog)

* docs(v1.6): generate milestone summary for team onboarding

* feat(config): add HTTPHandler() method to Provider[T]

- Add HTTPHandler() that returns http.Handler accepting PATCH/POST JSON
- Thread-safe via Provider's internal write lock
- Returns 200 OK + updated config on success
- Returns 405 on wrong method, 400 on invalid JSON, 422 on validation failure
- Add tests for method not allowed, invalid JSON, successful patch, POST accepted, validation error

Refs: D-04, T-09-01, T-09-02

* refactor(httptest_mock): replace mock-iteration for-loop with http.ServeMux routing

- Add mux http.ServeMux field to MockHandler struct
- Add ensureMux() lazy initializer with double-checked locking
- Add rebuildMux() to group mocks by 'METHOD /path' and register ServeMux handlers
- Add handleMockGroup() helper extracted from the old ServeHTTP loop body
- Update AddMocks() to rebuild the mux after appending new mocks
- All 75 existing tests pass unchanged — zero behavioral change

Refs: D-05

 fix(httptest_mock): normalize header keys to lowercase in matchHeaders

- Compare expected and request header keys as lowercase with underscores
  replaced by hyphens, handling Windows transport non-canonical variances
- Store readData under normalized key so GetHeaderValue('api-key') works
- Improve match-log message to show both expected and actual values
- Handle empty header values correctly (empty matches empty, non-empty
  expected with empty found = no match)
- Add 8 TestRequest_matchHeaders sub-tests covering exact, case-insensitive,
  underscore-to-hyphen, Windows non-canonical, missing, multi-value, empty

Refs: D-06

* docs(09-post-v1.6-cleanup): complete 09-01 cleanup plan

* chore: remove REQUIREMENTS.md for v1.6 milestone

* chore: commit pending milestone archival changes

docs: turn README into project showcase entry point

docs: describe catalog-driven article sync

feat: replace Hermes with opencode as required dependency

- cliInstall.js: add opencode install spec (manual + auto per OS)
- doctor.js: validate opencode via getCliPath instead of hermes
- init.js: auto-install opencode in init (interactive or --yes)
- welcome scripts: reference opencode as prerequisite
- bump version to 0.1.2

[AUTO-COMMIT] Updated README.md software versions

chore: atualiza Makefile para padrão da skill makefile (help agrupado)

- help com awk + grupos ##@ + descrições ##
- check targets: gocheck, uvcheck, check-e2e-config
- regex corrigido [a-zA-Z0-9_.-] p/ capturar targets com hífen no BSD awk
- variáveis GO/UV/PYTEST com ?=
- .PHONY por grupo

Initial commit

chore: update Go version to 1.25 in Dockerfile

Merge pull request #3 from guionardo/guionardo-patch-1

Add LAB.md for documenting new services

Merge pull request #13 from guionardo/guionardo-patch-1

Update Go Release badge in README.md