feat: implement universal coupling metrics model (Layer 1)

[jflowers]

Summary

Implements the universal, language-agnostic coupling metrics model
(Layer 1) for vibe-check, addressing GitHub issue #1. This provides
the foundation that all language-specific analyzers will target.

Core capabilities:

• Universal metrics model: Ca, Ce, Instability, Abstractness, Distance,
  LCOM4, circular dependency detection
• Adapter interface with dependency-injected Registry for multi-language
  support
• External analyzer protocol: JSON-RPC 2.0 over stdin/stdout with
  security hardening (path validation, environment sanitization,
  response size limits)
• JSON schema (draft 2020-12) for ModuleGraph interchange format
  with structural validation

Key design decisions:

• Flat metrics package (public API, not internal/)
• Module as universal unit of analysis (language-neutral)
• Named metric types with GoDoc documenting formulas, ranges, citations
• Zero external dependencies

How to Test

# Run all 48 tests with race detection
go test -race -count=1 -timeout=60s ./...

# Build verification
go build ./...

# Static analysis
go vet ./...
golangci-lint run ./...

Key acceptance scenarios verified by tests:

• Metric computations match Martin's published formulas (Ca, Ce, I, A, D)
• LCOM4 variant (Hitz & Montazeri, 1995) with connected-component semantics
• Zone classification with precedence (main-sequence → pain → uselessness → normal)
• Boundary conditions (zero denominators, exact thresholds)
• Determinism verification (100-iteration checks for all compute functions)
• ExternalAdapter subprocess lifecycle (timeout, crash, shutdown, stderr capture)
• Security: path traversal rejection, credential environment blocking, response size limits
• JSON schema round-trip serialization with zero-value preservation

How to Demo

# Verify the metrics package compiles and passes all tests
go test -v -race -count=1 ./metrics/...

# Inspect the JSON schema
cat metrics/modulegraph.schema.json

# Review package documentation
go doc ./metrics/
go doc ./metrics/ Module
go doc ./metrics/ Adapter
go doc ./metrics/ ExternalAdapter

This is a model/interface implementation — there is no CLI or
end-to-end demo yet. The Go adapter (P0) and CLI (P1) will
consume these types.

Key Files Changed

Directory	Files	Description
metrics/	20	Universal coupling model: types, computation, adapter interface, JSON-RPC protocol, JSON schema, validation, security
openspec/changes/universal-coupling-model/	8	Spec artifacts: proposal, design, 4 specs, tasks
.	3	go.mod, .golangci.yml, AGENTS.md (project structure update)
.uf/dewey/learnings/	4	Retrospective learnings from implementation session

Known Issues

The following findings from the review council were acknowledged
but deferred as follow-up work (greenfield project):

• HIGH (SRE): No CI workflow (.github/workflows/) — automated
  quality gate not yet configured
• HIGH (SRE/Guard): No README.md or CHANGELOG.md — initial
  project documentation not yet created

This PR was generated by /uf.finale (AI-assisted).

[jflowers]

Council Verdict: APPROVE

Reviewers: Adversary, Architect, Curator, Envoy, Guard, Herald, Scribe, SRE, Testing
Iterations: 1 (3 REQUEST CHANGES resolved, all 9 now APPROVE)

Adversary (APPROVE)

• [MEDIUM] Symlink-based path traversal bypass in ValidateProjectPath — filepath.EvalSymlinks not called; limited blast radius (analyzer only reads, sanitized env)
• [MEDIUM] Blocked env var list gaps (AZURE_, GOOGLE_, API_KEY, SSH_AUTH_SOCK) — mitigated by allowlist-first design
• [MEDIUM] Windows-style path traversal not guarded — darwin-only currently
• 3 LOW findings omitted

Architect (APPROVE)

• [MEDIUM] Functional options pattern deviates from AP-001 Options struct convention — needs custom rule in go-custom.md
• [MEDIUM] Validate function complexity CRAP 16.8 — decomposition opportunity (SHOULD-level)
• 5 LOW findings omitted

Guard (APPROVE)

No MEDIUM+ findings. All tasks traced to implementation, all constitution principles satisfied.

• 3 LOW findings omitted

Testing (APPROVE)

All HIGH findings resolved in iteration 1 (floatEq refactored to assertFloatEq with t.Helper(), 3 untested functions now tested). All addressed MEDIUM findings resolved (edge case tests added, error assertions strengthened).

• 3 MEDIUM findings deferred (design.md docs, cycle enforcement, Registry concurrency) — acceptable for model layer scope
• 3 LOW findings omitted

SRE (APPROVE)

• [MEDIUM] limitedBuffer.Write swallows errors silently — could add writeErr field for observability
• [MEDIUM] No CI workflow files — greenfield project, track as follow-up
• [MEDIUM] go.mod specifies Go 1.25.7 without toolchain directive
• 5 LOW findings omitted

Curator (APPROVE)

All findings resolved — issue #18 filed for README/CHANGELOG, issue #19 for blog, AGENTS.md stale content fixed.

• 1 LOW finding omitted

Scribe (APPROVE)

• [MEDIUM] Validate doesn't check schemaVersion value — spec-to-code gap
• 7 LOW findings omitted

Envoy (APPROVE)

• [MEDIUM] Capabilities() returns nil on all error paths — interface constraint, needs GoDoc clarification
• 9 LOW findings omitted

Herald (APPROVE)

All findings resolved — issue #18 satisfies CHANGELOG documentation gate, issue #19 tracks blog.

• 3 LOW findings omitted

---

This review was generated by /review-council (AI-assisted).