Audit Trail: Every Decision, Recorded

Every capability call, every confirmation, every stage advancement — Fabriq records it all in an append-only audit log. This is the source of truth for "what happened, when, and who approved it."

What gets logged

Event	Example log entry
Feature created	capability: feature.create
File written after approval	capability: write with approved: true
Stage advanced	capability: feature.runStage with stage: implementation
Gate blocked	capability: feature.runStage with error: GATE_BLOCKED
Gate bypassed	capability: feature.runStage with confirmed: true
Validation run	capability: validation.run with testsPassed: 4
Feature closed	capability: feature.close with promoted: 4

Where the audit trail lives

The audit log is stored as a JSONL file (one JSON object per line):

.dapei/runtime/audit/capability.log

This file is:

• Append-only — entries are never modified or deleted
• Local — stays on your machine, not sent anywhere
• Readable — plain JSONL, viewable in any text editor

How to read the log

Each log entry has this structure:

{
  "schema_version": 1,
  "timestamp": "2026-07-20T15:00:00Z",
  "capability": "feature.close",
  "version": "0.1.0",
  "ok": true,
  "duration": 350,
  "metadata": {
    "feature": "add-dark-mode-toggle",
    "dimension": "feature",
    "confirmed": true,
    "promoted": 4
  },
  "error": null
}

Field	Meaning
schema_version	Audit log format version
timestamp	ISO 8601 timestamp of the event
capability	The capability that was called
version	Capability version
ok	Whether the operation succeeded (true) or failed (false)
duration	Duration in milliseconds
metadata	Event-specific data (feature name, dimension, confirmation status)
error	Error details if ok is false, otherwise null

Browsing the audit trail in the UI

From the Workspace Browser:

1. Click Knowledge in the sidebar
2. Click Audit Trail tab
3. You'll see a chronological timeline of every event

You can filter by:

• Feature — see all events for a specific feature
• Capability — filter by capability type
• Date range — narrow by time
• Status — show only failures (good for debugging)
• Dimension — workspace vs feature events

How to use the audit trail

For compliance

"Who approved writing to that file?"

Filter by the file path in metadata → find the write capability → see which user confirmed it and when.

For debugging

"Why did the validation fail?"

Filter by validation.run with ok: false → read the error field to see what went wrong.

For process improvement

"How long do features spend in review?"

Filter by feature.runStage events → calculate time between first Review entry and the eventual Approve.

For rollback

"What exactly changed in that feature?"

Filter by feature name → chronological list of every write, approval, and rejection → full picture of what the agent did.

Privacy

Audit data stays on your machine. Fabriq doesn't send audit logs anywhere — they're stored locally in .dapei/runtime/audit/. Your team's decisions remain your data.

Pro tips

• Check the audit trail first: Before debugging "why is this file different," check the audit log to see what was approved and when
• Use failures as signals: If validation.run consistently fails on the same feature type, your testability.md templates may need updating
• Gate bypasses are visible: Every confirmed=true override is logged — use them to identify process friction points

Next steps

• Closing a Feature — the close pipeline includes an audit log entry
• Stage Gates — gate bypasses are logged here
• Working with the Agent — confirm/reject loop generates audit entries