docs: add WOMM certification badge and developer guides

- Add WOMM bronze certification SVG and text certificate - Add CLAUDE.md for AI coding guidance - Update README.md with certification badge - Add TEST-COVERAGE.md in docs/developer-guide
2026-04-02 17:25:45 +01:00 · 2026-04-02 17:25:45 +01:00 · c49f6d84ef
commit c49f6d84ef
parent 071568b37b
5 changed files with 357 additions and 1 deletions
--- a/.womm/bronze.svg
+++ b/.womm/bronze.svg
@ -0,0 +1,76 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 400 400" width="400" height="400">
+  <defs>
+    <style>
+      .seal-text { font-family: 'Georgia', 'EB Garamond', serif; font-weight: 700; }
+    </style>
+  </defs>
+
+  <!-- Outer ring -->
+  <circle cx="200" cy="200" r="190" fill="none" stroke="#B87333" stroke-width="6"/>
+  <circle cx="200" cy="200" r="180" fill="none" stroke="#B87333" stroke-width="2"/>
+
+  <!-- Decorative dots -->
+  <g fill="#B87333">
+    <circle cx="200" cy="14" r="4"/>
+    <circle cx="200" cy="386" r="4"/>
+    <circle cx="14" cy="200" r="4"/>
+    <circle cx="386" cy="200" r="4"/>
+    <circle cx="68" cy="68" r="3"/>
+    <circle cx="332" cy="68" r="3"/>
+    <circle cx="68" cy="332" r="3"/>
+    <circle cx="332" cy="332" r="3"/>
+  </g>
+
+  <!-- Inner ring -->
+  <circle cx="200" cy="200" r="150" fill="none" stroke="#B87333" stroke-width="2"/>
+  <circle cx="200" cy="200" r="140" fill="none" stroke="#B87333" stroke-width="1"/>
+
+  <!-- Stars between rings -->
+  <g fill="#B87333" class="seal-text" text-anchor="middle" font-size="16">
+    <text x="200" y="42">&#9733;</text>
+    <text x="200" y="370">&#9733;</text>
+    <text x="38" y="206">&#9733;</text>
+    <text x="362" y="206">&#9733;</text>
+  </g>
+
+  <!-- Circular text - top: "WORKS ON MY MACHINE" -->
+  <path id="topArc" d="M 80,200 a 120,120 0 0,1 240,0" fill="none"/>
+  <text class="seal-text" font-size="18" fill="#B87333" letter-spacing="3">
+    <textPath href="#topArc" startOffset="50%" text-anchor="middle">WORKS ON MY MACHINE</textPath>
+  </text>
+
+  <!-- Circular text - bottom: "CERTIFIED" -->
+  <path id="bottomArc" d="M 320,200 a 120,120 0 0,1 -240,0" fill="none"/>
+  <text class="seal-text" font-size="18" fill="#B87333" letter-spacing="5">
+    <textPath href="#bottomArc" startOffset="50%" text-anchor="middle">CERTIFIED</textPath>
+  </text>
+
+  <!-- Laptop + checkmark icon -->
+  <g transform="translate(200,165)" fill="none" stroke="#B87333" stroke-width="3"
+     stroke-linecap="round" stroke-linejoin="round">
+    <rect x="-35" y="-30" width="70" height="48" rx="4"/>
+    <polyline points="-12,0 -2,10 16,-10" stroke-width="4" stroke="#8B5E3C"/>
+    <path d="M-45,18 L-50,28 L50,28 L45,18"/>
+  </g>
+
+  <!-- WOMM -->
+  <text x="200" y="228" class="seal-text" font-size="42" fill="#B87333"
+        text-anchor="middle" letter-spacing="6">WOMM</text>
+
+  <!-- Divider -->
+  <line x1="120" y1="240" x2="280" y2="240" stroke="#B87333" stroke-width="1.5"/>
+
+  <!-- Level label -->
+  <text x="200" y="260" class="seal-text" font-size="16" fill="#B87333"
+        text-anchor="middle" letter-spacing="3">BRONZE</text>
+
+  <!-- Date -->
+  <text x="200" y="285" class="seal-text" font-size="13" fill="#B87333"
+        text-anchor="middle" letter-spacing="1">2026-04-02</text>
+
+  <!-- Dot decorations -->
+  <g fill="#B87333">
+    <circle cx="148" cy="282" r="2"/>
+    <circle cx="252" cy="282" r="2"/>
+  </g>
+</svg>
--- a/.womm/womm-certificate.txt
+++ b/.womm/womm-certificate.txt
@ -0,0 +1,110 @@
+        ================================================================
+                    WOMM CERTIFICATE OF COMPLIANCE
+                         WOMM-STD-001:2026
+        ================================================================
+
+        Certificate Number:  WOMM-20260402172447-2462
+        Date of Issuance:    2026-04-02 17:24:47
+        Standard:            WOMM-STD-001:2026, First Edition
+
+        ----------------------------------------------------------------
+                          PROJECT INFORMATION
+        ----------------------------------------------------------------
+
+        Project Name:        grokkit
+        Project Path:        /data/Projects/grokkit
+        Certification Level: BRONZE (It Compiles)
+
+        ----------------------------------------------------------------
+                        CERTIFICATION AUTHORITY
+        ----------------------------------------------------------------
+
+        Certifying Machine:  plato
+        Certifying User:     gmgauthier
+        Operating System:    Linux 6.17.0-111019-tuxedo
+        Python Version:      3.12.3
+
+        This certification was performed on the above machine and is
+        valid exclusively for this machine in its current configuration,
+        including all running processes, environment variables, and the
+        certifier's current emotional state.
+
+        ----------------------------------------------------------------
+                          AUDIT TRAIL
+        ----------------------------------------------------------------
+
+        | Check                                    | Result | Detail |
+        |------------------------------------------|--------|--------|
+        | Project directory exists                 | PASS   | Project directory 
+located. We're off to a strong start. |
+| Contains source code                     | PASS   | Source files detected. 
+This is, in fact, a software project. |
+| Python syntax check                      | PASS   | No Python files to check. 
+Blissful ignorance achieved. |
+| Test suite exists                        | FAIL   | No test suite found. Bold 
+strategy. |
+| Tests pass                               | FAIL   | Tests failed. 
+/usr/bin/python: No module named pytest |
+| README exists                            | PASS   | README found. 
+Documentation: the thought that counts. |
+| No TODO/FIXME/HACK comments              | FAIL   | Found markers in: 
+testgen_test.go:20, testgen.go:216, testgen.go:218, testgen.go:223, 
+testgen.go:225. The guilt is documented. |
+| CI configuration exists                  | FAIL   | No CI configuration found.
+You are the CI. |
+| Git working tree is clean                | FAIL   | Uncommitted changes 
+detected. Living dangerously. |
+
+        ----------------------------------------------------------------
+                          DECLARATION
+        ----------------------------------------------------------------
+
+        I, gmgauthier@plato, do hereby certify that the software
+        project "grokkit" has been evaluated in accordance
+        with WOMM-STD-001:2026 and has achieved:
+
+                    *** WOMM BRONZE CERTIFICATION ***
+
+        This certification is granted under the following conditions:
+
+        1. The software was observed to work on my machine.
+        2. No guarantee is made regarding any other machine.
+        3. This certificate is void if anyone asks "are you sure?"
+        4. Validity expires upon the next git pull, dependency update,
+           or passage of more than 24 hours.
+
+        ----------------------------------------------------------------
+                            SIGNATURES
+        ----------------------------------------------------------------
+
+        Certified by:
+
+            ___________________________
+            gmgauthier
+            plato
+            2026-04-02
+
+        Witnessed by:
+
+            ___________________________
+            /dev/null
+            (The Void)
+
+
+        Approved by the WOMM Standards Committee:
+
+            ___________________________
+            The Committee
+            (Quorum: 1)
+
+
+        ================================================================
+         This document was generated in compliance with WOMM-STD-001:2026
+             "Works On My Machine" Certification Standard
+                      First Edition, 2026-04-02
+
+           Copyright 2026 The WOMM Standards Committee.
+           All rights reserved, except the right to guarantee
+           it works on your machine.
+        ================================================================
+
--- a/CLAUDE.md
+++ b/CLAUDE.md
@ -0,0 +1,87 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Grokkit is a Go CLI that integrates the xAI Grok API with git workflows. It provides AI-assisted chat, file editing, commit message generation, multi-language linting, test generation, documentation, and automated todo workflows. The core philosophy is "The Developer Is The Agent" — the LLM enhances rather than replaces developer judgment.
+
+## Commands
+
+```bash
+make build        # Build optimized binary to build/grokkit (with ldflags: version, commit, builddate)
+make install      # Build + install to ~/.local/bin
+make test         # Run all tests with -v -race
+make test-cover   # Generate HTML coverage report at build/coverage.html
+make test-agent   # Run only agent tests
+make lint         # Run golangci-lint (matches CI)
+make clean        # Remove build/ directory
+```
+
+To run a single test:
+```bash
+go test -run TestFunctionName ./cmd/...
+go test -run TestFunctionName ./internal/grok/...
+```
+
+Required env var: `XAI_API_KEY=sk-...`
+
+## Architecture
+
+```
+main.go → cmd.Execute()
+cmd/        Cobra subcommands (~40 files). Each command: parse flags → load config → call internal packages → stream output
+config/     Viper config from ~/.config/grokkit/config.toml; resolves model aliases; CLI flags > env > file > defaults
+internal/
+  grok/     HTTP client with SSE streaming; AIClient interface for testability
+  git/      os/exec wrapper around git commands; GitRunner interface
+  linter/   Detects language by extension, runs available linters, supports 9 languages
+  errors/   Domain-specific error types (GitError, APIError, etc.)
+  prompts/  AI prompt construction
+  recipe/   Loads and executes transactional markdown workflow recipes
+  todo/     Task tracking
+  workon/   Automated branch+plan+execute workflow
+  logger/   slog facade; JSON to ~/.config/grokkit/grokkit.log
+```
+
+Key interfaces in `internal/grok/interface.go` (`AIClient`) and `internal/git/interface.go` (`GitRunner`) enable dependency injection for tests.
+
+The typical command flow: CLI flags parsed → `config.Load()` → build prompt → `grok.Client.Stream()` (SSE) → display streamed output.
+
+## Code Conventions
+
+- Go 1.24.2
+- Use `errors.Is`/`errors.Join`, `slices`, `maps` packages (modern Go)
+- Table-driven tests with `t.Parallel()` and `t.Run()`
+- Interface-based design for external dependencies (API, git)
+- Structured logging via `internal/logger` (not fmt.Println for errors)
+- Coverage target: >70% for internal packages
+
+## Testing Notes
+
+These are not unit-tested (require integration or E2E):
+- Cobra command execution paths
+- Terminal input (Scanln)
+- API SSE streaming (would need mock HTTP server)
+- `os.Exit()` paths
+
+## Configuration
+
+`~/.config/grokkit/config.toml`:
+```toml
+default_model = "grok-4"
+temperature = 0.7
+timeout = 60
+
+[aliases]
+fast = "grok-4-1-fast-non-reasoning"
+
+[commands.lint.model]
+"model" = "grok-4-1-fast-non-reasoning"
+```
+
+Model resolution: `--model` flag → config alias expansion → literal model name.
+
+## CI
+
+Gitea CI (`.gitea/workflows/ci.yml`): test → lint → build. golangci-lint v2.1.6. Release workflow builds multi-platform binaries with SHA256 checksums.
--- a/README.md
+++ b/README.md
@ -257,3 +257,5 @@ Error: Request failed: context deadline exceeded
 ---

 **Made with ❤️ using Grok AI**
+
+THIS PROJECT IS [WOMM CERTIFIED](.womm/womm-certificate.txt) ![BRONZE-BADGE](.womm/bronze.svg)
--- a/docs/developer-guide/TEST-COVERAGE.md
+++ b/docs/developer-guide/TEST-COVERAGE.md
@ -0,0 +1,81 @@
+# Test Coverage Assessment
+
+**Date:** 2026-04-02
+**Scope:** All packages in `cmd/`, `internal/`, and `config/`
+**Test files reviewed:** 32 across 12 packages
+
+---
+
+## Overall: ~60% unit / ~20% integration
+
+The pattern is consistent: **pure helper functions are well-tested; the actual command execution paths are mostly not**.
+
+---
+
+## Per-Package Breakdown
+
+| Package | Est. Coverage | Notes |
+|---|---|---|
+| `internal/logger/` | ~85% | Comprehensive public API coverage |
+| `internal/prompts/` | ~85% | All load paths + fallback covered |
+| `internal/errors/` | ~80% | Error types + unwrapping covered |
+| `internal/todo/` | ~80% | Bootstrap idempotency solid |
+| `internal/linter/` | ~75% | Language detection strong; output parsing weak |
+| `config/` | ~75% | Config getters good; file-load errors not tested |
+| `internal/workon/` | ~70% | State transitions good; `Run()` itself untested |
+| `internal/git/` | ~70% | Real git integration, good core coverage |
+| `internal/grok/` | ~60% | Streaming + SSE parsing tested; error paths absent |
+| `internal/version/` | ~50% | Just variable presence check |
+| `internal/recipe/` | ~50% | Loading tested; execution engine (`Run()`, `refactorFiles()`, `handleApplyStep()`) entirely untested |
+| `cmd/` | ~25–35% | Message builders tested; nearly all `run*()` functions untested |
+
+---
+
+## What's Systematically Untested
+
+**Command execution** — Most `run*()` functions in `cmd/` have zero direct tests:
+- `runAgent()`, `runChat()`, `runQuery()`, `runRecipe()`, `runTestgen()`, `runWorkon()`, `runChangelogCommand()`, `runDocs()`
+
+**API error scenarios** — The grok client has no tests for: HTTP errors, rate limits, auth failures, malformed SSE chunks, timeouts, or stream cancellation.
+
+**Recipe execution** — `internal/recipe/` tests only YAML loading. The entire execution side (`Run`, `refactorFiles`, `handleApplyStep`, `executeReadOnlyShell`) is untouched.
+
+**User interaction** — All interactive confirmation/prompt flows are untested. No mock stdin anywhere.
+
+**File system errors** — Read-only paths, permission failures, disk full — none tested.
+
+---
+
+## Highest-Impact Gaps
+
+1. `internal/recipe/` — execution engine is production code with zero test coverage
+2. `internal/grok/` — error path coverage missing entirely for a network client
+3. `cmd/agent.go`, `cmd/chat.go`, `cmd/query.go` — core UX features without tests
+4. `config/` — file parsing errors and env var overrides not tested
+
+---
+
+## Strengths
+
+- Good use of `t.TempDir()` for isolation
+- Real git integration in `internal/git/` tests (not mocked)
+- Mock injection via function variables (git runner, API client) makes testing feasible
+- `t.Parallel()` used consistently where appropriate
+- Error type chain verification (`errors.Is`) is present
+
+## Weaknesses
+
+- The "Live" test pattern (`TestScaffoldCmd_Live`) uses `testing.Short()` logic inconsistently — it's gated but the semantics are inverted from convention
+- No benchmark tests anywhere
+- No CI separation between unit and integration tests — "live" tests quietly depend on environment
+- Mocking strategy is inconsistent across packages (some use testify mocks, some manual function variables)
+
+---
+
+## Priority Recommendations
+
+**High:** Add tests for `internal/recipe/` execution, grok client error scenarios, and `runAgent()`/`runChat()`/`runQuery()`.
+
+**Medium:** Test `config/` file-load failure paths, git error scenarios (uninitialized repo), and file permission errors.
+
+**Low:** Standardize the Live test pattern, add benchmarks for SSE streaming, add concurrent operation tests.