Skip to content

Core Architecture & Operational Invariants

Clean-Room Engineering Lifecycle, Zero-CGo Invariant & Antigravity Native Tooling

gosec adheres to strict architectural patterns engineered specifically for high-efficiency Go development, autonomous AI pair programming with Google Antigravity, and runtime policy enforcement via ctxsec.io.

1. Zero-CGo Static Go Architecture

Every package and binary in gosec compiles cleanly with CGO_ENABLED=0.

  • Pure-Go SQLite Engine (modernc.org/sqlite): Unlike traditional Go SQLite drivers requiring GCC/Clang (mattn/go-sqlite3), gosec uses a 100% pure-Go transpilation of SQLite. This guarantees instant cross-compilation across Darwin, Linux, and Windows with zero dynamic link dependencies.
  • Production Binary Optimization: Binaries are compiled with -ldflags="-s -w" to strip debug symbols, resulting in lightweight, sub-millisecond execution times suitable for containers and local CLI tools.
  • Hermetic Build Verification: Enforced via make test with -race concurrency detection enabled across all packages.

2. Antigravity-First AI Discovery & Invariants

gosec treats AI coding agents as first-class team members:

flowchart LR
    Root["Authoritative Root\n(AGENTS.md / GEMINI.md)"] --> Rules[".agents/rules/\n(Scoped Invariants)"]
    Root --> Skills[".agents/skills/\n(Domain Skills)"]
    Root --> MCP["bin/mcp-server\n(Multiplexed Stdio)"]
    MCP --> Protection["ctxsec.io Policy Gate\n(Google CEL Validation)"]
    Protection --> Workspace["Workspace Code &\nBacklog Database"]
Hold "Alt" / "Option" to enable pan & zoom

Hierarchical Invariant Architecture

Policy Layer Path Purpose
Root Policy AGENTS.md / GEMINI.md Supreme behavioral contract governing all agents
Task Discipline .agents/rules/single-task-discipline.md Enforces strictly ONE active task at any time
Local LLM Tiering .agents/rules/local-llm-tiering.md Prioritizes Tier 0/1 local Ollama ($0.00) inference
Binary Recompilation .agents/rules/local-binaries.md Mandates rebuilding to bin/ upon code edits
Pre-Implementation .agents/rules/pre-implementation-research.md Enforces live web lookup before adopting dependencies
Session Memory .agents/rules/session-continuity.md Cross-turn state persistence in SQLite and memory logs

3. The 6-Phase Clean-Room Lifecycle

Every capability implemented in gosec follows an immutable lifecycle tracked inside the SQLite backlog ledger (db/backlog/backlog.sqlite):

flowchart LR
    Backlog["1. Backlog\n(Discrete Task Registration)"] --> Research["2. Research\n(Live Discovery & Specs)"]
    Research --> TDD["3. TDD\n(Unit Tests Before Code)"]
    TDD --> Verification["4. Verification\n(make test, vulncheck)"]
    Verification --> Documentation["5. Documentation\n(MkDocs & Portal)"]
    Documentation --> Release["6. Release\n(Version Bump & Dist)"]
Hold "Alt" / "Option" to enable pan & zoom
  • Task registered in db/backlog/backlog.sqlite with priority, acceptance criteria, and DAG dependencies.
  • AI agents interact strictly via stdio MCP tools (backlog_create_task, backlog_update_stage).
  • Zero training-cutoff assumptions.
  • Live verification of package APIs, GitHub Actions action versions, container base images, and Go 1.27 signatures.
  • Comprehensive unit tests written before functional implementation.
  • Concurrency race conditions caught early with go test -race.
  • Static code analysis with go vet and golangci-lint.
  • Go vulnerability scanning via govulncheck ./....
  • Static binary compilation to bin/gosec and bin/mcp-server.
  • Technical docs updated in docs/ and validated with mkdocs build --strict.
  • Astro portal updated in website/ and synchronized to Cloudflare Pages.
  • Semantic version update in VERSION.
  • Multi-arch cross-compilation release archives built into dist/ with SHA256 checksums.

4. Rule 14: Mandatory AI MCP Coverage

In gosec, no feature is considered complete until it is exposed across three distinct surfaces:

  1. Go Package (pkg/<name>): Strongly typed, reusable Go API with clean interfaces.
  2. CLI Subcommand (cmd/gosec <command>): Human-friendly terminal interface with formatted tables.
  3. MCP Tool (cmd/mcp-server): Strongly typed JSON-RPC tool callable by Antigravity agents.

5. Security Plane Synergy with ctxsec.io

While gosec provides the scaffolding, task backlog, and AI tool harness, runtime protection is provided by ctxsec.io:

  • Declarative CEL Hypervisor: Evaluates all agent tool calls in sub-5µs using Google Common Expression Language (CEL).
  • Context DLP & Secret Masking: Prevents credentials and sensitive tokens from leaking into agent prompt contexts.
  • In-Kernel OS Sandbox: Applies zero-overhead Linux kernel process restrictions before agent execution.

Together, gosec.io and ctxsec.io form a complete, hardened foundation for enterprise agentic software engineering engineered by emaik.