feat: implement universal coupling metrics model (Layer 1)

.github/workflows/ci.yml

@@ -0,0 +1,43 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+
+      - name: Build
+        run: go build ./...
+
+      - name: Vet
+        run: go vet ./...
+
+      - name: Test
+        run: go test -race -count=1 -coverprofile=coverage.out ./...
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+
+      - name: golangci-lint
+        uses: golangci/golangci-lint-action@v7
+        with:
+          version: latest

.golangci.yml

@@ -0,0 +1,33 @@
+version: "2"
+
+run:
+  timeout: 5m
+
+formatters:
+  enable:
+    - gofmt
+    - goimports
+  settings:
+    goimports:
+      local-prefixes:
+        - github.com/zero-dot-force/vibe-check
+
+linters:
+  enable:
+    - errcheck
+    - govet
+    - revive
+    - staticcheck
+    - unused
+    - ineffassign
+  settings:
+    revive:
+      rules:
+        - name: exported
+          severity: warning
+        - name: error-return
+          severity: warning
+        - name: error-strings
+          severity: warning
+        - name: unexported-return
+          severity: warning

.opencode/uf/packs/go-custom.md

@@ -17,4 +17,19 @@ Use the `CR-NNN` prefix for all custom rules. Use `[MUST]`,
 
 ## Custom Rules
 
-<!-- Add project-specific rules below this line -->
+### CR-001 [SHOULD] Functional Options for Multi-Parameter Constructors
+
+Constructor functions with 3 or more optional parameters MAY use
+the functional options pattern (`type Option func(*T)`) instead
+of the AP-001 Options struct pattern when the options are
+independent and self-documenting. The functional options pattern
+is preferred for adapter configuration where sensible defaults
+are provided and each option modifies a single field.
+
+**Rationale**: The `metrics.ExternalAdapter` has 5 configurable
+timeouts/limits with sensible defaults. Functional options are
+more ergonomic for this use case — callers specify only the
+overrides they need without constructing a full Options struct.
+
+**Scope**: `metrics` package adapter configuration. New packages
+should prefer AP-001 unless the same conditions apply.

.uf/dewey/learnings/universal-coupling-model-20260829T005320-jay-flowers.md

@@ -0,0 +1,10 @@
+---
+tag: universal-coupling-model
+author: jay-flowers
+category: pattern
+created_at: 2026-08-29T00:53:20Z
+identity: universal-coupling-model-20260829T005320-jay-flowers
+tier: draft
+---
+
+When implementing a universal coupling metrics model for Go codebases (vibe-check project), the two-layer architecture pattern (Layer 1 = universal model, Layer 2 = language adapters) proved effective. The key design decisions that worked well: (1) flat metrics package rather than internal/ because the model IS the public API, (2) named metric types like Instability float64 with GoDoc documenting ranges and citations, (3) Module as the universal unit of analysis with language-neutral terminology, (4) JSON-RPC 2.0 over stdin/stdout for external adapters with newline-delimited framing. The ExternalAdapter's functional options pattern (WithAnalyzeTimeout, WithMaxResponseSize, etc.) provided clean configuration without breaking constructor signatures, though it deviates from the AP-001 Options struct convention — this deviation should be documented as a custom rule.

.uf/dewey/learnings/universal-coupling-model-20260829T005332-jay-flowers.md

@@ -0,0 +1,10 @@
+---
+tag: universal-coupling-model
+author: jay-flowers
+category: gotcha
+created_at: 2026-08-29T00:53:32Z
+identity: universal-coupling-model-20260829T005332-jay-flowers
+tier: draft
+---
+
+When testing Go subprocess communication (ExternalAdapter in vibe-check), the TestHelperProcess pattern (os.Args[0] with GO_WANT_HELPER_PROCESS env var) is the standard library-compatible approach that avoids external test binaries. Key gotchas: (1) the test function parameter should use _ *testing.T since it's not a real test, (2) tests using t.Setenv cannot use t.Parallel — Go 1.17+ enforces this, (3) limitedBuffer for stderr capture must always report the full write length to avoid breaking the subprocess pipe even on internal errors, (4) Gaze quality analysis revealed that constructor functions (NewExternalAdapter, NewRegistry) often have 0% contract coverage because tests call them but never directly assert on the return value — adding nil checks and default value assertions closes this gap easily.

.uf/dewey/learnings/universal-coupling-model-20260829T005336-jay-flowers.md

@@ -0,0 +1,10 @@
+---
+tag: universal-coupling-model
+author: jay-flowers
+category: gotcha
+created_at: 2026-08-29T00:53:36Z
+identity: universal-coupling-model-20260829T005336-jay-flowers
+tier: draft
+---
+
+For the vibe-check project's golangci-lint configuration, version 2 of golangci-lint treats gofmt and goimports as formatters not linters — they must go under formatters.enable, not linters.enable. Also, gosimple was merged into staticcheck in v2, so listing it separately causes an error. The .golangci.yml needs version: "2" at the top level. When implementing a hand-rolled JSON schema validator (metrics/validate.go) to avoid external dependencies, keep complexity low by extracting helper functions (validateModule, validateWarning) — Gaze flagged the main Validate function at complexity 16 which is the only Q4 Dangerous function in the codebase.

.uf/dewey/learnings/universal-coupling-model-20260829T005344-jay-flowers.md

@@ -0,0 +1,10 @@
+---
+tag: universal-coupling-model
+author: jay-flowers
+category: pattern
+created_at: 2026-08-29T00:53:44Z
+identity: universal-coupling-model-20260829T005344-jay-flowers
+tier: draft
+---
+
+The review council consistently flagged zone classification threshold contradictions across spec artifacts — the design doc said thresholds are "configuration, not model" while the metrics-schema spec hardcoded them. The resolution was to accept thresholds as part of the model and update the design non-goal. This is a common spec review pattern: when a non-goal contradicts a spec requirement, the non-goal usually needs refinement rather than the spec. Another recurring theme was LCOM variant ambiguity — the constitution requires citing the measurement model, and LCOM4 (Hitz and Montazeri, 1995) was chosen for its connected-component semantics. Always specify WHICH variant of a well-known metric you're implementing.

AGENTS.md

@@ -234,8 +234,6 @@ hotfixes (retroactively documented).
 
 ## Build & Test Commands
 
-<!-- Placeholder — update when go.mod and Makefile are created -->
-
 ```bash
 # Build
 go build ./...
@@ -256,17 +254,29 @@ golangci-lint run ./...
 .opencode/          # OpenCode agent configuration, skills, packs
 .specify/           # Constitution and governance memory
 .uf/                # Unbound Force tooling configuration
+metrics/            # Universal coupling metrics model (Layer 1)
+  adapter.go        # Adapter interface and Capability type
+  compute.go        # Metric computation functions
+  cycle.go          # Cycle type for circular dependency representation
+  doc.go            # Package-level GoDoc
+  external.go       # ExternalAdapter (JSON-RPC subprocess)
+  graph.go          # ModuleGraph and ModuleResult types
+  jsonrpc.go        # JSON-RPC 2.0 protocol types
+  module.go         # Module type (universal unit of analysis)
+  modulegraph.schema.json  # JSON Schema for ModuleGraph validation
+  registry.go       # Adapter registry (dependency-injected)
+  schema.go         # Embedded JSON schema access
+  security.go       # Path validation and environment sanitization
+  validate.go       # JSON schema validation
+  values.go         # Named metric types (Instability, Abstractness, etc.)
+  warning.go        # Warning type for analysis caveats
+  zone.go           # Zone and Status types
 openspec/           # OpenSpec change artifacts (proposals, specs, tasks)
   changes/          # Individual change directories
   schemas/          # Spec validation schemas
   specs/            # Spec templates
 ```
 
-> **Pre-implementation**: No Go source directories exist yet.
-> Package layout will be established during the first spec
-> workflow. Update this section when `go.mod` and source
-> packages are created.
-
 ## Architecture
 
 The planned architecture follows the RFC phasing:
@@ -280,7 +290,8 @@ The planned architecture follows the RFC phasing:
   architectural drift tracking
 - **P3**: TS/JS adapter, SBOM integration, mutation testing hooks
 
-Package layout will be established during the first spec workflow.
+The `metrics` package implements the P0 universal model. Language
+adapters (P1+) will be added as separate packages.
 
 ## Coding Conventions
 

go.mod

@@ -0,0 +1,3 @@
+module github.com/zero-dot-force/vibe-check
+
+go 1.25.7

metrics/adapter.go

@@ -0,0 +1,37 @@
+package metrics
+
+import "context"
+
+// Adapter is the interface that all language-specific analyzers must implement.
+// Adding a new language adapter requires only implementing this interface and
+// registering with a [Registry].
+type Adapter interface {
+	// Analyze analyzes the project at projectPath and returns a complete ModuleGraph.
+	Analyze(ctx context.Context, projectPath string) (*ModuleGraph, error)
+	// Language returns the lowercase language identifier (e.g., "go", "python").
+	Language() string
+	// Capabilities returns the list of metrics this adapter can compute.
+	// A nil or empty return may indicate either zero capabilities or a
+	// communication failure. Use Analyze for detailed error diagnostics.
+	Capabilities() []Capability
+}
+
+// Capability represents a metric that an adapter can compute.
+type Capability string
+
+const (
+	// CapAfferentCoupling indicates the adapter can compute afferent coupling (Ca).
+	CapAfferentCoupling Capability = "ca"
+	// CapEfferentCoupling indicates the adapter can compute efferent coupling (Ce).
+	CapEfferentCoupling Capability = "ce"
+	// CapInstability indicates the adapter can compute instability (I).
+	CapInstability Capability = "instability"
+	// CapAbstractness indicates the adapter can compute abstractness (A).
+	CapAbstractness Capability = "abstractness"
+	// CapDistance indicates the adapter can compute distance from main sequence (D).
+	CapDistance Capability = "distance"
+	// CapLCOM indicates the adapter can compute Lack of Cohesion of Methods (LCOM4).
+	CapLCOM Capability = "lcom"
+	// CapCircularDeps indicates the adapter can detect circular dependencies.
+	CapCircularDeps Capability = "circular"
+)

metrics/compute.go

@@ -0,0 +1,52 @@
+package metrics
+
+import "math"
+
+// ComputeInstability computes I = Ce / (Ca + Ce).
+// When both Ca and Ce are 0, returns 0.0 (maximally stable by convention).
+// This follows the convention that an isolated module with no coupling
+// relationships is treated as stable rather than unstable.
+func ComputeInstability(ca, ce int) Instability {
+	denom := ca + ce
+	if denom == 0 {
+		return 0.0
+	}
+	return Instability(float64(ce) / float64(denom))
+}
+
+// ComputeAbstractness computes A = abstractTypes / totalExported.
+// When totalExported is 0, returns 0.0 (a module with no exported types
+// is treated as fully concrete).
+func ComputeAbstractness(abstractTypes, totalExported int) Abstractness {
+	if totalExported == 0 {
+		return 0.0
+	}
+	return Abstractness(float64(abstractTypes) / float64(totalExported))
+}
+
+// ComputeDistance computes D = |A + I - 1|.
+// The result measures how far a module is from the main sequence, where
+// the main sequence represents the ideal balance between abstractness
+// and instability.
+func ComputeDistance(a Abstractness, i Instability) Distance {
+	return Distance(math.Abs(float64(a) + float64(i) - 1.0))
+}
+
+// ComputeZone classifies a module's position relative to the main sequence.
+// Precedence (evaluated in order):
+//  1. main-sequence: D < 0.2
+//  2. zone-of-pain: A < 0.2 AND I < 0.2
+//  3. zone-of-uselessness: A > 0.8 AND I > 0.8
+//  4. normal: all other cases
+func ComputeZone(a Abstractness, i Instability, d Distance) Zone {
+	if d < 0.2 {
+		return ZoneMainSequence
+	}
+	if a < 0.2 && i < 0.2 {
+		return ZoneOfPain
+	}
+	if a > 0.8 && i > 0.8 {
+		return ZoneOfUselessness
+	}
+	return ZoneNormal
+}