Coding Ethos Docs

coding-ethos is policy as code for AI coding agents. It turns a repository’s engineering principles into generated agent instructions, CEL policy checks, Git hooks, MCP tools, SARIF output, runtime sandbox evidence, and CI gates.

Current OpenSSF Best Practices status: Silver. Gold readiness and remaining gaps are tracked in the OpenSSF Gold checklist.

Start Here

• README: project overview, quick start, supported agents, and common workflows.
• Repository analysis: source-of-truth boundaries, generated artifacts, and verification model.
• Strategic roadmap: major platform directions for MCP, CEL, SARIF, sandboxing, and agent remediation loops.
• AST/CEL/SARIF architecture: the preferred path for turning parsed source facts into principle-owned CEL policy, stable SARIF, and code-intelligence storage.
• Code intelligence: local DuckDB, duckdb-vss, Tree-sitter chunks, SARIF/remediation evidence, and MCP retrieval surfaces.
• Agent proxy foundation: opt-in proxy trust boundary, provider-neutral event envelope, code-intel ledger, CEL facts, SARIF properties, and operator model.
• Trust signals: OpenSSF Scorecard, Best Practices badge, security posture, and publication checklist.
• OpenSSF Gold checklist: .bestpractices.json evidence, remaining Gold gaps, and remediation plan.
• Security assurance case: security claims, evidence, input-validation posture, and known limits.
• Gold security posture: cryptography applicability, TLS verification, site hardening, and release signing.
• Build reproducibility: repeatable build inputs, deterministic Go flags, generated artifact checks, and known limits.
• Supply-chain attestations: Scorecard publishing, GitHub artifact provenance, SBOMs, PyPI Trusted Publishing, checksums, and verification commands.
• Threat model: protected assets, actors, trust boundaries, risks, and out-of-scope claims.
• Release process: versioning, artifact, checklist, and release note expectations.
• Discussions plan: recommended GitHub Discussions categories and issue/discussion boundaries.
• Demo: verified MCP, command-block, lint-check, and SARIF excerpts plus a recording plan.
• Comparison: how coding-ethos relates to pre-commit, CodeQL, Semgrep, OPA, branch protection, and plain agent instructions.
• Integrations: Codex, Claude Code, Gemini CLI, MCP, GitHub Actions, GitLab CI, SARIF consumers, and managed static analysis.

AI Agent Policy Enforcement

coding-ethos is built for agentic development workflows where Codex, Claude Code, Gemini CLI, and human contributors need the same enforceable rules.

• MCP server: stdio MCP tools for policy checks, lint advice, SARIF remediation, risk summaries, and capability inspection.
• Code intelligence: MCP-backed search over stored SARIF, remediation outcomes, hook traces, Tree-sitter chunks, and vector metadata.
• Integrations: setup notes for Codex, Claude Code, Gemini CLI, MCP clients, GitHub Actions, GitLab CI, SARIF consumers, and managed tools.
• Runtime sandboxing: native namespaces, cgroups, seccomp, network isolation, and least-privilege tool capabilities.
• Red-team suite: adversarial coverage for hook bypass, shell parsing, protected paths, MCP framing, SARIF, and sandbox behavior.

CEL Policy Language

CEL lets repos express narrow custom policies without adding a new Go evaluator for every rule. Principle-owned CEL policies live with the ETHOS principle they enforce.

• Policy language strategy: CEL inputs, helper functions, staged migration path, and limits.
• AST/CEL/SARIF architecture: source-fact collection, CEL evaluation, SARIF emission, and code-intel persistence.
• MCP server: policy explanation and policy check tools that expose compiled CEL behavior to agents.

SARIF And Code Scanning

SARIF turns local policy and static-analysis evidence into code-scanning, artifact, trend, and remediation workflows.

• CI/CD SARIF: generated GitHub Actions and GitLab CI gates.
• SARIF uses: remediation advice, risk summaries, trend analysis, editor loops, and policy feedback.
• SARIF editor integration: local workflows for developers and agents.
• Code intelligence: persistent SARIF and AST-backed retrieval for repeated-failure analysis and remediation memory.

Hook And Tool Runtime

• Hook runtime bootstrap: checkout-local runtime artifacts, repair behavior, and consumer hook entrypoints.
• Runtime publication: PyPI generator boundaries and the release-asset model for future compiled Go runtime distribution.
• Lint capture Go flow: managed lint capture through compiled Go request, target resolution, config validation, and normalized output.
• Source docs index: full document list for maintainers.