What problem does it solve?
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.
Core Features & Use Cases
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
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"]
W --> DBOk(["Row in audit_log table"])
W --> 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:
- The script writes an audit row with approval-stage auto and outcomes reflecting success or failure of the action.
For R-class actions:
- Step 1: propose entry (before architect ack)
- Step 2: resolve entry (after architect approves OR declines)
- In both steps, the payload contains the per-action_id details and is written to the audit log or degraded to jsonl if the DB is unavailable.
Quick Start
Log an audit entry for a new mutating action by invoking the audit-log-write.sh script with the required arguments.
