auditing-actions

name	auditing-actions
description	Use right after `board-superpowers:classifying-actions` returns a decision, every time a board-superpowers skill is recording what it is about to do or what it just did. For actions that proceed automatically, apply once after the action lands. For actions that wait for architect approval, apply once when first proposing the action and again after the architect approves or declines. Apply even when the action seems too small to log — every mutating action gets a row, no exceptions. Do NOT use for read-only actions; reads are not audited. Do NOT invoke to determine the A/R/N decision — that is `board-superpowers:classifying-actions`.
user-invocable	false

auditing-actions

This skill is the audit-row writing authority. Every mutating action the plugin performs leaves a trail of one or two rows in the audit log, recording what was decided, who approved (if anyone), and what happened when the action ran.

Flow at a glance

flowchart TD
    Caller["Caller: A or R decision + payload"] --> C{"Decision class"}
    C -- A --> A1["1 row\napproval-stage=auto"]
    C -- R --> R1["Row 1: propose\napproval-stage=propose"]
    R1 --> Wait["Surface to architect"]
    Wait -- approve --> R2A["Row 2: approved\nact then audit result"]
    Wait -- decline --> R2D["Row 2: rejected\naudit decline; abort"]
    A1 --> W["audit-log-write.sh"]
    R2A --> W
    R2D --> W
    W -- "DB reachable" --> DBOk(["Row in audit_log table"])
    W -- "DB unreachable" --> JSONL["Degrade to jsonl\nwith mode field\nidentifying cause"]
    JSONL --> JE(["Row in audit-local.jsonl"])

How to apply this skill

The caller has just received an A/R decision from board-superpowers:classifying-actions. Now the caller invokes scripts/audit-log-write.sh (located inside the board-superpowers plugin) once for A-class actions or twice for R-class actions, with structured args. Examples below assume the caller has resolved the plugin root path; scripts/lib/common.sh ships a bsp_plugin_root helper that does this cross-platform.

For A-class actions:

bash <plugin-root>/scripts/audit-log-write.sh \
  --action-id <int> \
  --decision A \
  --skill <calling-skill-name> \
  --approval-stage auto \
  --outcome <success|failure> \
  --payload '<json-per-action_id>'

For R-class actions, two invocations — propose, then resolve:

# Step 1: propose entry (before architect ack)
bash <plugin-root>/scripts/audit-log-write.sh \
  --action-id <int> --decision R --skill <name> \
  --approval-stage propose --outcome success \
  --payload '<proposal-json>'

# Step 2: resolve entry (after architect approves OR declines)
bash <plugin-root>/scripts/audit-log-write.sh \
  --action-id <int> --decision R --skill <name> \
  --approval-stage approved \         # OR rejected
  --outcome <success|failure> \       # OR success (for rejected)
  --payload '<full-action-json>'      # OR '<decline-reason-json>'

The script returns exit 0 when the row was written somewhere — to the configured RDBMS (preferred) or to a host-local jsonl file (fallback). The caller does NOT need to handle DB errors specially; the script self-heals (recreating the venv if needed) and degrades gracefully.

Quick reference

What you have	What you need
an action just decided as A	invoke once with approval-stage=auto
an action just decided as R, before ack	invoke once with approval-stage=propose
architect approved an R-class proposal	invoke once with approval-stage=approved
architect declined an R-class proposal	invoke once with approval-stage=rejected
audit row schema details	read references/schema.md
per-action_id payload templates	read references/db-write-conventions.md
degradation behavior	read references/degradation-mode.md

What this skill does NOT cover

• Deciding A vs R vs N — that's board-superpowers:classifying-actions. This skill records what was decided.
• Drafting the proposal text — that's the molecular caller's UX responsibility. This skill writes the text into the payload field.
• Surfacing degraded-mode warnings to the architect — the script emits stderr WARN; architect may notice. This skill doesn't escalate.

This skill defines how to record an action's audit trail. The caller decides what to do; this records it.