audit

Live Context

Current audit context:

• Recent git commits: !git log --oneline -10 2>/dev/null || echo "No git history"
• Git authors today: !git log --since="midnight" --format="%an" 2>/dev/null | sort | uniq -c || echo "None"
• Uncommitted changes: !git status --short 2>/dev/null || echo "Not a git repo"
• Recent file modifications: !find . -type f -mtime -1 -not -path './.git/*' 2>/dev/null | wc -l | tr -d ' ' files in last 24h
• Audit log exists: !ls -la .audit/ 2>/dev/null | head -5 || echo "No .audit/ directory"
• Audit records exist: !wc -l "${CLAUDE_PROJECT_DIR:-.}/.claude/audit/records.jsonl" 2>/dev/null || echo "No .claude/audit/records.jsonl"
• Checkpoint log exists: !ls -la .checkpoints/ 2>/dev/null | head -5 || echo "No .checkpoints/ directory"

Intent

Execute audit to create a structured record of actions taken, tools invoked, changes made, and the reasoning behind decisions. This provides accountability, enables investigation of issues, and supports compliance requirements.

Success criteria:

• Complete chronological record of relevant actions
• Every action linked to actor, timestamp, and rationale
• Changes documented with before/after state
• Provenance chain for all outputs

Compatible schemas:

• schemas/output_schema.yaml

Inputs

Inputs not listed here are outside the capability's contract: a workflow step that binds them gets W604 (STANDARD v1.1 §5.5).

Procedure

1. Define audit scope: Determine what to include in the audit
   • Record the event itself: what happened, by whom, when
   • Read the report scope from context.scope to identify targets
   • Apply the time window in context.time_window if provided
   • Identify relevant log sources (git log, tool invocations, file changes)
2. Collect action records: Gather all actions within scope
   • Read git log for commits and their messages
   • Review tool invocation history if available
   • Identify file changes (created, modified, deleted)
   • Record timestamps for each action
3. Extract decision rationale: Document the "why" for each action
   • Link actions to plans or goals that motivated them
   • Capture assumptions stated before action
   • Record any constraints that influenced decisions
4. Build provenance chain: Track inputs to outputs
   • For each output, identify its source inputs
   • Document transformations applied
   • List dependencies between artifacts
5. Ground claims: Attach evidence for all audit entries
   • Format: file:line, tool:git:commit_hash, timestamp
   • Include actual command outputs where relevant
6. Write the record (append-only): Persist the audit record before returning
   • Build one compact JSON line: audit_id, timestamp, the event, the context, retention if given, and the collected audit_record, changes and provenance (redact credentials and PII first)
   • Append it with Bash to "${CLAUDE_PROJECT_DIR:-.}/.claude/audit/records.jsonl" (mkdir -p "${CLAUDE_PROJECT_DIR:-.}/.claude/audit", then >>), so the record lands in the same project .claude/ directory the plugin's hooks use rather than under whatever the working directory is; refuse if the file is a symlink, and never rewrite, truncate or reorder existing lines
   • Do not write to .claude/audit.log: the plugin's PostToolUse hook keeps it as an HMAC-chained log of skill invocations (checked by tools/verify_audit_log.py), and a foreign line would break the chain. The hook appends this skill's own invocation only after the skill finishes, so there is no line for it yet: cite earlier lines (the invocations being audited) as evidence, not this one
   • The plugin's PreToolUse hook blocks a Bash command that matches its mutation pattern (rm, mv, sed, git, curl, chmod, … anywhere in the command, record text included) while there is no valid checkpoint marker (.claude/checkpoint.ok); a plain mkdir/printf >> append whose text matches none of them is not blocked. If the append is blocked or fails, set recorded: false, return the record in the output anyway, and say why in assumptions
7. Format output: Structure per audit contract; recorded is true only when step 6 appended the line

Output Contract

Return a structured object:

recorded: boolean  # Whether the record was appended to .claude/audit/records.jsonl
audit_id: string  # Unique audit record ID
timestamp: string  # ISO 8601 date-time the audit record was generated
audit_record:
  actor: string  # Who/what performed audited actions
  action_type: string  # Category of actions
  targets: array[string]  # What was affected
  outcome: success | failure | partial
changes:
  - type: string  # create, modify, delete, execute
    before: string | null  # Previous state/value
    after: string | null  # New state/value
    location: string  # File path or identifier
    timestamp: string  # When change occurred
tool_usage:
  - tool: string  # Tool name
    invocation_count: integer
    success_rate: number  # 0.0-1.0
    commands: array[string]  # Actual commands if verbose
decision_rationale: string  # Why these actions were taken
provenance:
  inputs: array[string]  # Source data/files
  outputs: array[string]  # Produced artifacts
  dependencies: array[string]  # External dependencies used
confidence: number  # 0.0-1.0 (completeness of audit)
evidence_anchors: ["tool:git:...", "file:..."]
assumptions: []

Field Definitions

Examples

Example 1: Audit Code Change Session

Input:

event:
  type: session_completed
  actor: "claude-agent"
  timestamp: "2024-01-15T16:00:00Z"
context:
  scope: "session"
  time_window:
    start: "2024-01-15T14:00:00Z"
    end: "2024-01-15T16:00:00Z"
  detail_level: standard
  include_diffs: false

Output:

recorded: true
audit_id: "audit_20240115_160000_session"
timestamp: "2024-01-15T16:00:00Z"
audit_record:
  actor: "claude-agent"
  action_type: "code_modification"
  targets:
    - "src/api/handlers/user.py"
    - "src/api/handlers/auth.py"
    - "tests/test_handlers.py"
  outcome: success
changes:
  - type: modify
    before: "get_user() with inline SQL"
    after: "get_user() with parameterized query"
    location: "src/api/handlers/user.py:45-62"
    timestamp: "2024-01-15T14:45:00Z"
  - type: modify
    before: "5 test cases"
    after: "7 test cases (added SQL injection tests)"
    location: "tests/test_handlers.py"
    timestamp: "2024-01-15T15:15:00Z"
tool_usage:
  - tool: Read
    invocation_count: 12
    success_rate: 1.0
  - tool: Edit
    invocation_count: 4
    success_rate: 1.0
  - tool: Bash
    invocation_count: 3
    success_rate: 1.0
    commands: ["pytest tests/", "git diff", "git commit"]
decision_rationale: "Refactored to prevent SQL injection vulnerability identified in security audit. Added parameterized queries and corresponding test coverage."
provenance:
  inputs:
    - "security_audit_report.md"
    - "src/api/handlers/user.py (original)"
  outputs:
    - "src/api/handlers/user.py (modified)"
    - "tests/test_handlers.py (modified)"
  dependencies:
    - "pytest>=7.0"
    - "psycopg2"
confidence: 0.95
evidence_anchors:
  - "file:.claude/audit/records.jsonl"
  - "tool:git:abc123def456"
  - "tool:bash:pytest tests/ - 7 passed"
  - "file:src/api/handlers/user.py:45"
assumptions:
  - "Git log accurately reflects all changes"
  - "No manual edits outside of tracked session"

Evidence pattern: Git commit history, tool invocation logs, file diffs.

Example 2: Audit Specific File Changes

Input:

event:
  type: configuration_changed
  actor: "claude-agent"
  target: "config/production.yaml"
context:
  scope: "config/production.yaml"
  detail_level: verbose
  include_diffs: true

Output:

recorded: true
audit_id: "audit_20240115_config"
timestamp: "2024-01-15T17:00:00Z"
audit_record:
  actor: "claude-agent"
  action_type: "configuration_change"
  targets:
    - "config/production.yaml"
  outcome: failure
changes:
  - type: modify
    before: |
      database:
        host: db.internal
        port: 5432
    after: |
      database:
        host: db.external
        port: 5433
    location: "config/production.yaml:12-15"
    timestamp: "2024-01-15T15:30:00Z"
  - type: rollback
    before: "(modified config)"
    after: "(original config)"
    location: "config/production.yaml"
    timestamp: "2024-01-15T16:00:00Z"
tool_usage:
  - tool: Edit
    invocation_count: 2
    success_rate: 0.5
decision_rationale: "Attempted database migration to external host. Rollback triggered after connection test failed."
provenance:
  inputs:
    - "migration_plan.md"
    - "config/production.yaml (original)"
  outputs:
    - "config/production.yaml (restored to original)"
  dependencies: []
confidence: 1.0
evidence_anchors:
  - "file:.claude/audit/records.jsonl"
  - "file:.checkpoints/chk_20240115_150000_config/manifest.json"
  - "tool:bash:rollback command output"
assumptions: []

Verification

Apply the following verification patterns:

• Evidence Grounding: All changes linked to evidence_anchors
• Contract Validation: Output has recorded, audit_id and evidence_anchors per the output schema
• Completeness Check: No gaps in timeline for the specified time window
• Provenance Valid: All inputs and outputs are verifiable

Verification tools: Read (for log files and the appended record), Grep (for searching history), Bash (to append the record)

Safety Constraints

• mutation: true (it writes an audit record); mutation_overridable, so a step that only reads may declare mutation: false
• requires_checkpoint: false
• requires_approval: false
• risk: low

Capability-specific rules:

• Never modify audited artifacts during audit
• Preserve original timestamps (do not alter history)
• Include failed actions, not just successes
• Redact sensitive information (credentials, PII) from audit output
• Store audit records append-only: only ever append to "${CLAUDE_PROJECT_DIR:-.}/.claude/audit/records.jsonl"; never edit or delete earlier lines, and never write to the hook-maintained .claude/audit.log

Composition Patterns

Commonly follows:

• verify - After verify passes (passed: true), audit the successful changes (CAVR pattern)
• execute / mutate - Audit what was executed
• rollback - Audit the rollback event itself

Commonly precedes:

• explain - Summarize audit for stakeholder reporting
• persist - Store audit record for compliance

Anti-patterns:

• Never skip audit after execute or mutate (breaks accountability)
• Never modify artifacts during audit (breaks integrity)
• Never omit failed actions from audit trail

Workflow references:

• See reference/composition_patterns.md#debug-code-change for audit-after-verify
• See reference/composition_patterns.md#digital-twin-sync-loop for audit in loops