Audit Logging

Meriadoc can write a structured log record for every task execution — including dry-runs, blocked attempts, and calls from AI agents. Logging is off by default and opt-in via config.

Enable audit logging

# ~/.config/meriadoc/config.yaml
audit:
  enabled: true
  sinks:
    - type: file
      path: ~/.config/meriadoc/audit.log

Log record schema

Each execution produces one NDJSON line:

{
  "timestamp": "2026-06-02T14:30:00.123Z",
  "schema_version": "1",
  "caller": "mcp-stdio",
  "action": "task.run",
  "task": "deploy-staging",
  "project": "myapp",
  "project_root": "/home/user/projects/myapp",
  "risk_level": "high",
  "exit_code": 0,
  "duration_ms": 1423,
  "env_override_keys": ["ENV"],
  "outcome": "success",
  "meriadoc_version": "0.1.3",
  "pid": 12345
}

Fields

Field	Description
`caller`	Who invoked the task: `cli`, `api`, `mcp-stdio`, `mcp-http`
`action`	`task.run`, `task.dry_run`, or `task.blocked`
`task`	Task name
`project`	Project name
`risk_level`	`low`, `medium`, `high`, or `critical`
`exit_code`	Process exit code (`null` for dry-run and blocked)
`duration_ms`	Execution time in milliseconds (`null` for dry-run and blocked)
`env_override_keys`	Keys of env vars overridden at call time — values are never logged
`outcome`	`success`, `failure`, `blocked`, or `dry_run`

Actions

Action	When
`task.run`	Normal task execution
`task.dry_run`	Preview run (`--dry-run`), no process spawned
`task.blocked`	Execution denied by a risk approval gate

Blocked calls are as important as successful ones for compliance. They’re always logged when audit is enabled.

Sinks

File sink

Appends NDJSON records to a file. Best for local development and persistent audit trails.

sinks:
  - type: file
    path: ~/.config/meriadoc/audit.log

Multiple processes writing to the same file is safe — Meriadoc uses O_APPEND which guarantees atomic writes for records under ~4 KB (well within the schema).

Stderr sink

Writes records to stderr. Best for containers and CI — log aggregators (Docker, Kubernetes) capture stderr automatically.

sinks:
  - type: stderr

You can combine sinks:

sinks:
  - type: file
    path: ~/.config/meriadoc/audit.log
  - type: stderr

Security notes

Secret values are never logged — only key names appear in env_override_keys
Broken sinks print a warning to stderr but never abort task execution
The sink architecture is designed for future extension (OTLP, webhook) without config changes