flow-audit
Enable, record, query, summarize, or verify the opt-in PWDEV Flow semantic audit trail. Use when the user asks what Flow actions occurred, wants audit integrity checked, or needs a portable JSONL reco
SKILL.mdplugins/pwdev-flow/skills/flow-audit/SKILL.md
GitHubOperate the PWDEV Flow Audit Trail
Read audit, safety, and artifacts. Resolve flow_audit.py from this installed plugin and pass its absolute path to python3 with the active repository root.
Route
enableupdates only.planning/flow/config.jsonafter an explicit request and preserves unknown configuration fields.summaryreports counts by action, skill, and phase.eventsreturns the latest valid semantic events, optionally filtered by an allowed action.verifychecks every non-empty JSONL line and returns integrity errors without repairing them.recordappends one event only after the described semantic action actually occurred.
Use the helper rather than parsing or appending JSONL with ad hoc shell commands.
Procedure
- Confirm the repository root and inspect
.planning/flow/config.jsonwithout reading secrets. - For
enable, require explicit intent, setaudittotrue, preserve unknown fields, and runverify. Do not create a synthetic historical trail. - For queries, run the matching helper command and report invalid-trail failures before any counts.
- For
record, choose one allowed action from the audit contract, a canonicalflow-*skill, and only the smallest non-sensitive structured detail needed. Record after the gate, write, decision, archive, migration, or phase outcome succeeds. - Report helper exit status and whether a write occurred. Recording while disabled is a successful no-op, not an audit event.
Constraints
- Never include prompts, environment variables, file contents, secrets, credentials, tokens, or private-key paths.
- Do not promise complete runtime telemetry: this trail records semantic Flow events only and uses no hooks.
- Do not repair, truncate, reorder, or replace an invalid trail without a separate explicit instruction.
- Audit failure must be visible but does not retroactively invalidate the workflow event it attempted to record.
Output
Return MODE, AUDIT_ENABLED, command result, integrity status, event count when applicable, limitations, and NEXT.