feat(spec): Spec Enricher — read .zig, enrich .tri (#69)

- specs/tri/spec_enricher.tri: VIBEE spec, vibee gen + ast-check pass
- src/tri/tri_spec_enricher.zig: extract types/fns/tests from .zig → update .tri
- CLI: tri enrich <spec> / tri enrich --all / tri enrich --dry-run
- 9/9 unit tests pass, 334/344 specs enrichable (97%)
- Wired into tri_utils.zig (Command enum) + main.zig (dispatch)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: Antigravity Agent

specs/tri/spec_enricher.tri

@@ -0,0 +1,152 @@
+# ═══════════════════════════════════════════════════════════════════════════════
+# VIBEE Specification — Spec Enricher
+# ═══════════════════════════════════════════════════════════════════════════════
+# φ² + 1/φ² = 3 = TRINITY
+# Issue #69: Read .zig files, enrich .tri specs
+# ═══════════════════════════════════════════════════════════════════════════════
+
+name: spec_enricher
+version: "1.0.0"
+language: zig
+module: spec_enricher
+
+description: |
+  Spec Enricher — reads .zig source files and enriches matching .tri specs.
+  Extracts actual type definitions, public function signatures, and test names
+  from Zig code. Updates the spec without overwriting manual descriptions.
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# TYPE SYSTEM
+# ═══════════════════════════════════════════════════════════════════════════════
+
+types:
+  ExtractedType:
+    fields:
+      name: String
+      kind: String
+      field_names: List(String)
+
+  ExtractedFunction:
+    fields:
+      name: String
+      params: List(String)
+      return_type: String
+      is_public: Bool
+
+  ExtractedTest:
+    fields:
+      name: String
+
+  EnrichResult:
+    fields:
+      spec_path: String
+      zig_path: String
+      types_found: Int
+      functions_found: Int
+      tests_found: Int
+      updated: Bool
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# BEHAVIORS
+# ═══════════════════════════════════════════════════════════════════════════════
+
+behaviors:
+  find_zig_source:
+    description: "Find corresponding .zig file for a .tri spec"
+    inputs:
+      - spec_path: String
+    output: Optional(String)
+    steps:
+      - Extract stem from spec_path
+      - Check generated/{stem}.zig
+      - Check src/tri/{stem}.zig
+      - Check src/tri/tri_{stem}.zig
+      - Return first found or null
+
+  extract_types:
+    description: "Extract pub struct/enum/union definitions from Zig source"
+    inputs:
+      - source: String
+    output: List(ExtractedType)
+    steps:
+      - Scan for "pub const X = struct {"
+      - Scan for "pub const X = enum {"
+      - Scan for "pub const X = union {"
+      - Extract field names from struct bodies
+      - Return list of ExtractedType
+
+  extract_functions:
+    description: "Extract pub fn signatures from Zig source"
+    inputs:
+      - source: String
+    output: List(ExtractedFunction)
+    steps:
+      - Scan for "pub fn name("
+      - Parse parameter list
+      - Parse return type
+      - Return list of ExtractedFunction
+
+  extract_tests:
+    description: "Extract test block names from Zig source"
+    inputs:
+      - source: String
+    output: List(ExtractedTest)
+    steps:
+      - Scan for 'test "name"'
+      - Extract test name string
+      - Return list of ExtractedTest
+
+  enrich_spec:
+    description: "Read .zig, extract info, update .tri spec"
+    inputs:
+      - spec_path: String
+    output: EnrichResult
+    steps:
+      - Find corresponding .zig source
+      - Read .zig file content
+      - Extract types, functions, tests
+      - Read existing .tri spec
+      - Merge new findings (preserve descriptions)
+      - Write updated .tri
+
+  run_enrich_command:
+    description: "CLI entry: tri enrich <spec.tri>"
+    inputs:
+      - args: List(String)
+    output: Void
+    steps:
+      - Parse spec_path from args
+      - Call enrich_spec
+      - Print enrichment report
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# CONSTRAINTS
+# ═══════════════════════════════════════════════════════════════════════════════
+
+constraints:
+  - Never overwrite manually-written descriptions
+  - Preserve existing type/behavior ordering
+  - Output must pass vibee validate
+  - Only extract pub (public) items from .zig
+  - Handle missing .zig gracefully (skip with warning)
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# TESTS
+# ═══════════════════════════════════════════════════════════════════════════════
+
+tests:
+  - name: "extractTypes finds struct"
+    input: {source: "pub const Foo = struct { x: u32 };"}
+    expected: {types_len: 1, name: "Foo", kind: "struct"}
+
+  - name: "extractFunctions finds pub fn"
+    input: {source: "pub fn doStuff(a: u32) void {}"}
+    expected: {fns_len: 1, name: "doStuff"}
+
+  - name: "extractTests finds test blocks"
+    input: {source: "test \"my test\" { }"}
+    expected: {tests_len: 1, name: "my test"}
+
+  - name: "findZigSource checks generated/ first"
+    input: {spec_path: "specs/tri/vsa.tri"}
+    expected: {zig_path_contains: "vsa.zig"}

src/tri/main.zig

@@ -579,6 +579,11 @@ pub fn main() !void {
         .mcp => try tri_register.runCommand(allocator, "mcp", cmd_args),
         // Spec Linter (Issue #68)
         .lint => try commands.runLintCommand(allocator, cmd_args),
+        // Spec Enricher (Issue #69)
+        .enrich => {
+            const spec_enricher = @import("tri_spec_enricher.zig");
+            try spec_enricher.runEnrichCommand(allocator, cmd_args);
+        },
         // GitHub Integration (Protocol v2)
         .github => try github_commands.runGithubCommand(allocator, cmd_args, false),
         // .monitor => {  // TODO: Add monitor to Command enum in tri_utils.zig
@@ -1059,6 +1064,13 @@ fn dispatchCommand(
         .lint => commands.runLintCommand(allocator, cmd_args) catch |err| {
             std.debug.print("Lint error: {}\n", .{err});
         },
+        // Spec Enricher (Issue #69)
+        .enrich => {
+            const spec_enricher = @import("tri_spec_enricher.zig");
+            spec_enricher.runEnrichCommand(allocator, cmd_args) catch |err| {
+                std.debug.print("Enrich error: {}\n", .{err});
+            };
+        },
         // GitHub Integration (Protocol v2)
         .github => github_commands.runGithubCommand(allocator, cmd_args, state.dry_run) catch |err| {
             std.debug.print("GitHub error: {}\n", .{err});