Related Pages

Related topics: Policy Enforcement, MCP & Agent Hooks, Code Intelligence & Telemetry Storage

Project Overview & Architecture

Purpose and Scope

coding-ethos is a governance, policy, and agent-routing framework for software projects. It provides a structured way to encode engineering standards, route work to specialized agents, and capture remediation evidence. The repository acts as both a reference implementation and a configuration backbone that other projects can adopt to enforce consistent development practices.

The project is documented across several layered entry points. README.md serves as the top-level orientation, while coding_ethos/CODING_ETHOS.md and ETHOS.md capture the normative rules of the "ethos." Agent-facing guidance is split between AGENTS.md and CLAUDE.md, which give different autonomous agents consistent operational instructions. Source: README.md:1-40.

The latest release, v0.3.0, introduced hardened policy extension seams, remediation evidence payloads, centralized agent routing, and persistent remediation storage in the code-intel subsystem. Source: community release notes (v0.3.0).

High-Level Architecture

The system is organized around four cooperating concerns: policy, agents, hooks, and code-intel. Policy documents define what is allowed; agents perform the work; hooks intercept and route operations; and code-intel stores evidence that work was actually done correctly.

flowchart LR
    A[Developer / CI] --> B[Hooks Layer]
    B --> C{Agent Router}
    C --> D[Policy Agent]
    C --> E[Code Intel Agent]
    C --> F[Remediation Agent]
    D --> G[(Policy Seams)]
    E --> H[(Code Intel Store)]
    F --> I[(Evidence Payloads)]
    G --> A
    H --> A
    I --> A

The configuration root is coding_ethos.yml, which the hooks layer reads to decide how to dispatch work. Source: coding_ethos.yml:1-60.

Core Subsystems

Policy and Extension Seams

The policy subsystem encodes the project's engineering standards. The v0.3.0 release specifically hardened "policy extension seams" so that custom rules can be plugged in without rewriting core logic. This makes the policy layer a stable contract that downstream consumers can extend. Source: PR #38 release notes.

Agent Layer

The agent layer is split across multiple focused agents (policy, code-intel, remediation, etc.). Each agent has a defined contract described in AGENTS.md, while agent-specific instructions for Claude-based agents live in CLAUDE.md. The v0.3.0 release added structured remediation evidence payloads so agents can prove that a fix was applied, not just claimed. Source: PR #39 release notes.

Hooks and Routing

The hooks subsystem centralizes agent routing and code-intel dispatch. Rather than scattering routing logic across individual agents, v0.3.0 moved this concern into a single, auditable layer. This reduces duplicate routing code and gives operators one place to add or modify dispatch behavior. Source: PR #40 release notes.

Code Intel and Evidence Storage

The code-intel subsystem stores remediation outcomes and other intelligence gathered during agent runs. In v0.3.0, this store became the canonical home for remediation evidence, making it queryable for audits and downstream tooling. Source: PR (code-intel remediation) release notes.

Configuration Surface

Configuration is intentionally hierarchical: the YAML file controls *mechanics*, while the Markdown files control *values and behavior*. This split lets operators tune dispatch without editing prose, and lets maintainers update guidance without breaking machine-readable config. Source: coding_ethos.yml:1-30; ETHOS.md:1-20.

Common Failure Modes

• Policy drift: when coding_ethos/CODING_ETHOS.md and AGENTS.md disagree, agents may follow stale guidance. The hardened seams in v0.3.0 aim to surface these conflicts at extension time. Source: PR #38 release notes.
• Missing evidence: remediation steps that do not produce a structured evidence payload are not stored in code-intel, breaking audit trails. Source: PR #39 release notes.
• Routing duplication: pre-v0.3.0, routing logic was scattered; the centralized hooks layer now requires removing redundant route definitions during upgrades. Source: PR #40 release notes.

See Also

• Coding Standards & Ethos
• Agent Contracts
• Hooks and Routing
• Code Intel Store

Related Pages

Related topics: Project Overview & Architecture, Code Intelligence & Telemetry Storage

Policy Enforcement, MCP & Agent Hooks

Overview

The coding-ethos repository defines a layered governance model in which three subsystems cooperate to keep agent-driven code generation aligned with project rules. The policy enforcement layer compiles declarative policy modules and evaluates actions against them; the MCP server exposes those policies (and code-intelligence lookups) as Model Context Protocol tools; and the agent hooks subsystem intercepts agent invocations, routes them through the appropriate code-intel and remediation pipelines, and records evidence of any corrective actions taken.

This triad was the focus of the v0.3.0 release, which hardened policy extension seams (PR #38), added remediation evidence payloads (PR #39), and centralized agent routing and code-intel inside the hooks runner (PR #40). Together, these changes turn a loose set of checkers into a deterministic enforcement pipeline.

Policy Enforcement

Policy Compiler

The compiler is the entry point for converting human-authored policy modules (Solidity-style or DSL configurations bundled with the project) into an in-memory representation that evaluators can consume. The compiler is intentionally narrow in scope: it parses, validates, and emits a normalized rule set. Extension seams added in v0.3.0 expose stable interfaces so that downstream consumers — primarily the MCP server and the hooks runner — can attach custom rule providers without modifying the compiler core. Source: go/internal/policy/compiler.go

Evaluators

Evaluators consume the compiled policy graph and answer the question *"is this proposed action allowed?"* for a given agent request. They are invoked both synchronously (during MCP tool calls that need a precondition check) and asynchronously (when the hooks runner batches decisions for a multi-step agent workflow). The evaluator contract returns a structured verdict rather than a boolean so the hooks runner can attach remediation hints. Source: go/internal/evaluators/evaluator.go

MCP Server

The MCP server surfaces coding-ethos capabilities to external agents that speak the Model Context Protocol. It registers tools backed by the policy compiler and the code-intel index, and it delegates every privileged operation through the evaluator before returning a response. Because MCP clients expect schema-strict payloads, the server is the canonical place where policy verdicts and remediation evidence are serialized for transit. Source: go/internal/mcp/server.go

The server is stateless with respect to long-lived agent sessions; conversation context lives in the hooks runner, which forwards only the slice of state the MCP tool needs for a single call.

Agent Hooks and Routing

Hook Runner

The hooks runner is the orchestration layer. It is invoked by agentproxy for every agent lifecycle event (pre-tool, post-tool, on-error) and is responsible for:

1. Resolving which code-intel index slice is relevant for the current working directory.
2. Routing the request to the appropriate MCP tool or local evaluator.
3. Capturing the verifier response and, if needed, asking agentmsg to attach a remediation evidence payload.
4. Emitting a normalized audit record.

Centralizing this routing inside the runner (PR #40) removed duplicated routing logic that previously lived in each hook implementation. Source: go/internal/hooks/runner.go

Agent Proxy Intercept

agentproxy sits between the agent runtime and the tool implementations. The intercept layer's job is to enrich raw tool invocations with the context (file paths, diff hunks, working directory) that evaluators require. It is deliberately thin so that policy decisions remain attributable to the evaluator rather than the transport layer. Source: go/internal/agentproxy/intercept.go

Remediation Evidence

When an evaluator returns a non-compliant verdict, the system does more than reject the action — it produces a remediation evidence payload that tells the agent exactly which rule was violated and what corrective action would satisfy it. PR #39 introduced first-class payloads in agentmsg so that remediation hints are durable, versionable, and consumable by both the MCP server and downstream code-intel storage. Source: go/internal/agentmsg/remediation.go

End-to-End Flow

sequenceDiagram
    participant Agent
    participant Proxy as agentproxy/intercept
    participant Runner as hooks/runner
    participant MCP as mcp/server
    participant Eval as evaluators
    participant Remed as agentmsg/remediation
    Agent->>Proxy: tool invocation
    Proxy->>Runner: enriched event + context
    Runner->>MCP: route to MCP tool
    MCP->>Eval: evaluate policy
    Eval-->>MCP: verdict (allow/deny + hints)
    alt denied
        MCP->>Remed: build evidence payload
        Remed-->>Runner: remediation record
        Runner-->>Proxy: reject with payload
    else allowed
        Runner-->>Proxy: allow + audit record
    end
    Proxy-->>Agent: final response

Common Failure Modes

• Compiler extension regressions: custom rule providers compiled against an older seam may fail to register. Pin to the v0.3.0 seam interface when extending the compiler. Source: go/internal/policy/compiler.go
• Evaluator timeouts on large diffs: evaluators may exceed MCP client timeouts when validating large generated files. The hooks runner batches decisions for multi-step workflows to mitigate this, but single-shot MCP calls should remain bounded. Source: go/internal/evaluators/evaluator.go
• Missing remediation payload: if a hook bypasses the runner (legacy code paths), the response will lack the remediation evidence produced by agentmsg. Always route through hooks/runner. Source: go/internal/agentmsg/remediation.go

See Also

• Project README for the high-level ethos and policy authoring guide.
• Wiki page on Code Intelligence and the remediation index (referenced by PR #40's code-intel changes).
• v0.3.0 release notes for the motivating PRs #38, #39, and #40.

Related Pages

Related topics: Policy Enforcement, MCP & Agent Hooks, Runtime Sandboxing, Managed Tools & Security

Code Intelligence & Telemetry Storage

Overview

The codeintel package is the persistent substrate of coding-ethos. It captures every signal the agent emits while auditing or remediating a repository — scanner output, policy decisions, AST-derived facts, and repository metadata — and stores them in a local DuckDB database so that subsequent runs, reports, and review sessions can query the same canonical history. Source: go/internal/codeintel/duckdb_store.go

In release v0.3.0 the telemetry layer gained two notable capabilities that surface in this page: structured remediation evidence payloads carried by the agent (feat(agent): add remediation evidence payloads, PR #39) and a centralized routing layer that funnels agent output through a single code-intel hub (feat(hooks): centralize agent routing and code intel, PR #40). Both rely on the storage layer described here.

Architecture

The package is layered: producers emit events into the event log, normalizers enrich them (SARIF shaping, decision records, AST facts), and a single DuckDB-backed store persists everything for query.

flowchart LR
    A[Agent / Hooks] -->|events| B(event_log.go)
    H[AST Scanner] -->|facts| F(astfacts.go)
    F -->|rows| C(duckdb_store.go)
    B --> C
    S[sarif.go] -->|normalized results| C
    D[decisions.go] -->|policy verdicts| C
    R[repo_map.go] -->|repo metadata| C
    C -->|SQL queries| Q[Reports / CLI / Web UI]

The duckdb_store.go module is the only writer to the database; every other file in codeintel/ produces typed structures that are ultimately flushed through it. Source: go/internal/codeintel/duckdb_store.go

DuckDB Storage Backend

duckdb_store.go owns the on-disk database file and the schema migrations. It is responsible for:

• Opening or creating the database with a deterministic path under the project's data directory.
• Running idempotent CREATE TABLE IF NOT EXISTS statements for each logical table.
• Providing typed insert helpers so callers do not write raw SQL.
• Exposing query helpers for read-only consumers (CLI, web UI, report generators).

DuckDB was chosen because the workload is overwhelmingly analytical: the agent runs few writes per session but the resulting tables are queried in aggregate (e.g. "how many error-level SARIF results per file across all runs"). Embedding DuckDB avoids standing up a separate database server while still giving the project SQL semantics. Source: go/internal/codeintel/duckdb_store.go

Core Tables (inferred from package boundaries)

These boundaries let each contributor extend a single concern without coordinating schema changes across the package.

Telemetry Event Log

event_log.go is the package's hot path. Hooks and agents call into it on every meaningful action — file opened, scan started, finding emitted, remediation applied — so its API is intentionally small: Append, Flush, Tail. Source: go/internal/codeintel/event_log.go

Events are buffered in memory and flushed to DuckDB in batches to keep the scanner's I/O cost low. Each event row carries:

• A monotonic event id.
• A wall-clock timestamp.
• The originating component (hook name, agent subsystem, scanner).
• A typed payload, marshalled to a column the store understands.

The release v0.3.0 work on remediation evidence payloads (PR #39) extended the payload schema so that an event can carry the exact diff or rule violation that triggered a fix, making the event log a self-describing audit trail. Source: go/internal/codeintel/event_log.go

SARIF and Decision Normalization

sarif.go converts raw SARIF documents produced by external scanners into the row shape that duckdb_store.go persists. It strips tool-driver noise, maps severity, and preserves the ruleId, message, and location triples needed for later reporting. Source: go/internal/codeintel/sarif.go

decisions.go records policy verdicts: each time a rule fires, the agent stores *why* the rule matched and *what* it decided to do (allow, warn, block, remediate). Persisting the decision alongside the SARIF row closes the loop — a reviewer can later ask "did we ever let this through?" and get a deterministic answer. Source: go/internal/codeintel/decisions.go

Repository Mapping and AST Facts

repo_map.go persists the working snapshot of the repository at the moment a scan ran: file tree, detected languages, configuration files discovered. This anchors every other row — SARIF results, decisions, and AST facts all reference file paths the repo_map knows about, so renaming or deleting files does not orphan dangling foreign keys. Source: go/internal/codeintel/repo_map.go

astfacts.go is a sibling package that walks source files and emits typed facts — symbol definitions, references, import edges — into the same store. Because the schema lives in codeintel, AST facts can be joined directly against SARIF rows and decisions, which is what enables cross-tool queries such as "all error findings touching a function defined in pkg/foo". Source: go/internal/astfacts/astfacts.go

Common Failure Modes

When in doubt, query the database directly — duckdb_store.go exposes the read helpers needed to inspect what actually landed.

See Also

• Policy Engine
• Agent Hooks & Routing
• Remediation Workflow

Related Pages

Related topics: Policy Enforcement, MCP & Agent Hooks, Code Intelligence & Telemetry Storage

Runtime Sandboxing, Managed Tools & Security

The Runtime Sandboxing subsystem is the security boundary that lets the coding-ethos agent execute untrusted or partially-trusted code (tool invocations, shell snippets, build commands) without compromising the host, the developer workspace, or the policy enforcement layer. It pairs Linux kernel-level resource isolation with a curated, version-locked "managed toolchain" so that every action an agent takes can be attributed, capped, and audited. Source: [docs/RUNTIME_SANDBOXING.md]

This page covers the runtime-side guarantees: how sandbox profiles are selected, how managed tools are pinned, how shell activity is captured for remediation, and how the v0.3.0 release tightened policy seams and added remediation evidence.

Architecture Overview

flowchart LR
    A[Agent / Hook Caller] --> B[sandbox.Sandbox]
    B --> C[cgroup_linux]
    B --> D[Policy Seams v0.3.0]
    B --> E[managed_capture]
    E --> F[agent_shell_sandbox]
    B --> G[toolchaincli.ManagedToolchain]
    G --> H[Pinned Binaries]
    F --> I[Evidence Payload]
    I --> J[Code Intel Store]

The caller invokes sandbox.Sandbox, which dispatches to a platform-specific isolation backend (cgroup_linux on Linux) and consults the policy extension seams hardened in v0.3.0. Shell activity is routed through managed_capture/agent_shell_sandbox, which produces a remediation evidence payload that the centralized hooks layer persists to the code-intel store. Source: go/internal/sandbox/sandbox.go

Sandbox Primitives

sandbox.go is the entry point and exposes a profile-driven API. A profile bundles resource caps (CPU, memory, PIDs, wall-clock), filesystem allow/deny rules, and network posture. Profiles are looked up by name (e.g. build, lint, network-egress-disabled) rather than constructed ad-hoc, which keeps policy decisions reviewable. Source: go/internal/sandbox/sandbox.go

On Linux, cgroup_linux.go materializes the profile into a v2 cgroup hierarchy under a per-invocation scope. It applies CPU weight, memory.max, pids.max, and the cgroup.kill escape for stuck children, and tears the scope down on exit so that no orphaned cgroup survives the agent run. The Linux-only file naming mirrors the project's "policy at the kernel boundary" stance: when a profile says "no network", the cgroup is created before the child is exec'd so the denial is structural rather than advisory. Source: go/internal/sandbox/cgroup_linux.go

Common failure modes the sandbox is designed to surface explicitly:

the sandbox returns a typed error so callers can degrade to a dry-run mode rather than silently running unsandboxed.

more permissive profile at runtime.

and the caller receives a structured BudgetExceeded error carrying the offending counter.

• Cgroup creation denied — typically SELinux/AppArmor misconfiguration;
• Profile not found — treated as a hard fail; agents cannot invent a
• Resource cap exceeded — the child receives SIGKILL via cgroup.kill

Managed Toolchain

toolchaincli.ManagedToolchain is the curated wrapper around every external binary the agent is allowed to invoke — go, node, python, git, formatters, linters, and language servers. Each tool entry pins an exact version, a SHA-256 of the binary, and the environment it is safe to expose to. The toolchain refuses to launch a binary whose hash does not match the manifest, which is the primary defense against dependency-confusion and tampered cache replacements. Source: go/internal/toolchaincli/managed_toolchain.go

The toolchain also resolves tool paths through a single lookup function so that hooks (see v0.3.0 "centralize agent routing and code intel") always invoke the same managed binary regardless of which subsystem initiated the call. This makes audit trails meaningful: every captured command references the manifest entry it came from.

Agent Shell Sandboxing & Managed Capture

Shell actions are the riskiest surface, so they get a dedicated wrapper. agent_shell_sandbox.go runs shell snippets inside the sandbox profile selected for the current agent phase, with stdin/stdout/stderr captured in full. managed_capture.go annotates the stream with timestamps, the active profile, the toolchain manifest entries that were resolved, and the policy decisions consulted along the way. Source: go/internal/managedcapture/agent_shell_sandbox.go

In v0.3.0 this capture was extended with a remediation evidence payload that summarizes what the agent did, what was denied, and what the human reviewer should look at first. The payload is the canonical artifact the code-intel store indexes for post-hoc review. Source: go/internal/managedcapture/managed_capture.go

Policy Seams and Recent Hardening

The v0.3.0 release explicitly hardened "policy extension seams" (refactor(solid): harden policy extension seams, PR #38). In practice this means the interface between sandbox.Sandbox, the policy evaluator, and the managed toolchain was narrowed so that new rules can only be added through a small, typed registry rather than via ambient global state. Callers that previously reached into a config struct to widen permissions now receive a compile-time or runtime error depending on the seam. Source: go/internal/sandbox/sandbox.go

The hook layer was also centralized in v0.3.0 (feat(hooks): centralize agent routing and code intel, PR #40), which means every tool and shell invocation now flows through a single dispatch point that consults the sandbox profile before exec. Combined with the remediation evidence payloads (PR #39), this gives reviewers a single, consistent artifact for every action the agent took, even when those actions were generated by different subsystems. Source: docs/RUNTIME_SANDBOXING.md

See Also

authored and consumed by the centralized hook layer.

remediation evidence payloads produced by managed_capture.

workflow for the pinned-binary manifest.

• Policy & Hook Architecture — how policy rules are
• Code Intelligence Store — persistence layer for the
• Managed Toolchain Manifest — schema and update

Doramagic Pitfall Log

Found 14 structured pitfall item(s), including 1 high/blocking item(s). Top priority: Security or permission risk - Security or permission risk requires verification.

1. Security or permission risk: Security or permission risk requires verification

• Severity: high
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/paudley/coding-ethos/issues/224

2. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/paudley/coding-ethos/issues/238

3. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/paudley/coding-ethos/issues/240

4. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | https://github.com/paudley/coding-ethos

5. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/paudley/coding-ethos

6. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/paudley/coding-ethos/issues/241

7. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/paudley/coding-ethos

8. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/paudley/coding-ethos

9. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/paudley/coding-ethos

10. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/paudley/coding-ethos/issues/190

11. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/paudley/coding-ethos/issues/239

12. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/paudley/coding-ethos/issues/235

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using coding-ethos with real data or production workflows.

• [[feature] Add architectural decision intelligence and get-why workflow](https://github.com/paudley/coding-ethos/issues/190) - github / github_issue
• [[feature] Index Markdown rationale nodes into code-intel graph](https://github.com/paudley/coding-ethos/issues/242) - github / github_issue
• [[feature] Surface central nodes and surprise edges in code-intel](https://github.com/paudley/coding-ethos/issues/241) - github / github_issue
• [[feature] Add topology-based code-intel communities](https://github.com/paudley/coding-ethos/issues/240) - github / github_issue
• [[feature] Add provenance classes for code-intel graph facts](https://github.com/paudley/coding-ethos/issues/239) - github / github_issue
• [[feature] Add code-intel graph report for agent repo orientation](https://github.com/paudley/coding-ethos/issues/238) - github / github_issue
• [[feature] Implement Agent-to-API Transparent Proxy for Payload Inspectio](https://github.com/paudley/coding-ethos/issues/52) - github / github_issue
• [[feature] Agent API proxy CEL enforcement and evidence ledger](https://github.com/paudley/coding-ethos/issues/224) - github / github_issue
• [[feature] Agent API proxy inbound CEL enforcement and proxy-denial MCP s](https://github.com/paudley/coding-ethos/issues/235) - github / github_issue
• v0.3.0 - github / github_release
• v0.2.1 - github / github_release
• v0.2.0 - github / github_release