flow-audit

Operate 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

• enable updates only .planning/flow/config.json after an explicit request and preserves unknown configuration fields.
• summary reports counts by action, skill, and phase.
• events returns the latest valid semantic events, optionally filtered by an allowed action.
• verify checks every non-empty JSONL line and returns integrity errors without repairing them.
• record appends 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

1. Confirm the repository root and inspect .planning/flow/config.json without reading secrets.
2. For enable, require explicit intent, set audit to true, preserve unknown fields, and run verify. Do not create a synthetic historical trail.
3. For queries, run the matching helper command and report invalid-trail failures before any counts.
4. For record, choose one allowed action from the audit contract, a canonical flow-* skill, and only the smallest non-sensitive structured detail needed. Record after the gate, write, decision, archive, migration, or phase outcome succeeds.
5. 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.