Audit Write Path via CLI Update

[SorraTheOrc]

Final summary

Add a small, safe CLI write path so wl update <id> --audit-text "..." records a structured per-item audit object ({time, author, text}). The command auto-generates time (UTC ISO8601) and author (actor display name) and overwrites the latest audit entry.

Problem statement

Add a safe, structured CLI write path for per-item audits so maintainers and automation can record a concise, machine-readable audit entry from the CLI. The goal is a small vertical slice that lets wl update <id> --audit-text "..." write (or overwrite) an audit object on a work item containing { time, author, text } where time and author are generated by the system.

Users

• Operators and maintainers who need to record a short audit note from the terminal (example: record a migration, a manual fix, or an important handoff).
• Automation authors and scripts that must record a single, recent audit from CI or tooling.

Example user stories

• As a maintainer, I want to run wl update WL-... --audit-text "Applied DB migration" so the work item shows a concise, timestamped audit I and my colleagues can read and scripts can parse.
• As an automation, I want wl update to set audit.time to the current UTC ISO8601 and audit.author to the actor display name so downstream tools can rely on standardized metadata.

Success criteria

1. CLI: wl update --help documents --audit-text and wl update <id> --audit-text "..." stores or overwrites audit.text on the work item.
2. Metadata: audit.time is generated as the current UTC ISO8601 when writing and audit.author stores the actor display name; wl show <id> (human and --json) includes the audit object.
3. Tests: unit and integration tests cover write and overwrite behavior and CLI help rendering.
4. Scope: This change overwrites the single latest audit object (no audit-history array) and does not implement PII redaction; redaction is handled by the separate item WL-0MMNCOIYS15A1YSI.

Constraints

• Only support --audit-text for this change; the system generates audit.time and audit.author automatically (no --audit-time flag in this item).
• Overwrite behaviour: the command replaces the work item's audit object (no history kept).
• Defer email redaction and advanced safety rules to WL-0MMNCOIYS15A1YSI.
• Reuse existing update permission model: the same permission check that gates wl update continues to apply to audit writes.

Existing state

• Data model planning exists in: WL-0MMNCNT1M16ESD04 (Audit Data Model and Migration).
• Work item: WL-0MMNCOIYF18YPLFB (Audit Write Path via CLI Update) already exists and is staged idea (assigned to Map).
• Several dependent/related items exist for read-paths, migration, redaction and end-to-end validation (see Related work).
• Implementation pointers: CLI handler at src/commands/update.ts, runtime types in src/types.ts, and persistence in src/persistent-store.ts were identified as touch points.

Desired change

• Add parsing and handler in the update command to accept --audit-text and produce a well-formed audit object: { time: <UTC ISO8601>, author: <actor-display-name>, text: <redacted-or-raw-text?> } (redaction deferred).
• Store/overwrite the work item's audit field via existing persistence helpers and surface the audit in wl show output.
• Add unit tests for parsing/validation and an integration test for CLI flow.
• Update CLI help and short docs describing the overwrite semantics and that redaction is handled by a separate work item.

Related work

• Potentially related docs

  • skill/audit/SKILL.md — new structured audit report format (triage output) used by AMPA (repo-local skill).
  • docs/triage-audit.md — guidance for audit report formatting used by triage tooling.
  • src/commands/update.ts — CLI handler to be updated.
  • src/persistent-store.ts — persistence layer where the audit object will be stored.

• Potentially related work items

  • Replace comment-based audits with structured audit field (WL-0MLDJ34RQ1ODWRY0) — parent/epic for structured audit efforts.
  • Audit Data Model and Migration (WL-0MMNCNT1M16ESD04) — schema and migration planning for the audit field (important for DB changes).
  • Audit Read Path in Show Outputs (WL-0MMNCOJ0V0IFM2SN) — surface audit in wl show human and JSON output.
  • Redaction and Safety Rules for Audit Text (WL-0MMNCOIYS15A1YSI) — separate item covering email/PII redaction (this intake defers to that item).
  • End-to-End Validation, Docs and Reuse Alignment (WL-0MMNCOQY30S8312J) — finalization and integrated tests across write/read/redaction paths.

Notes and open questions

• Per decision: support --audit-text only and auto-generate audit.time and audit.author (no --audit-time for this slice).
• Per decision: overwrite the existing audit object rather than append to history.
• Per decision: defer redaction to WL-0MMNCOIYS15A1YSI so we don't duplicate safety rules; this intake will reference that item as a blocking/adjacent dependency for PII handling.

Acceptance criteria (draft)

1. wl update --help lists --audit-text and shows short usage.
2. wl update <id> --audit-text "..." writes audit on the item with time = now (UTC ISO8601), author = actor display name, text = provided string.
3. wl show <id> (human) and wl show <id> --json include the audit object when present.
4. Unit tests cover parsing, overwrite behavior, and permission checks; an integration test covers the end-to-end CLI path.
5. Documentation note added to the CLI reference noting overwrite semantics and reference to WL-0MMNCOIYS15A1YSI for redaction rules.

Risks & assumptions

• Risk: PII leakage if audit text contains email addresses or other sensitive tokens. Mitigation: redaction is out of scope for this change and is captured in WL-0MMNCOIYS15A1YSI; tests should assert that redaction work item is referenced and that redaction is applied once that item is merged.
• Risk: Schema mismatch / migration failure. Mitigation: rely on WL-0MMNCNT1M16ESD04 for migration strategy and add a migration dry-run test.
• Risk: Scope creep (adding history, time override, complicated redaction) — Mitigation: record additional feature requests as separate work items and avoid expanding this item beyond the single write/overwrite slice.
• Assumption: wl update permission checks cover audit writes; no additional permission model changes are required.

Related work (automated report)

• Replace comment-based audits with structured audit field (WL-0MLDJ34RQ1ODWRY0): parent specification defining the audit shape, migration strategy and UX; primary reference for permissions and migration policy.
• Audit Data Model and Migration (WL-0MMNCNT1M16ESD04): migration and schema notes that define {time, author, text, status} and wl doctor upgrade behaviour — consult when adding migrations/tests.
• Redaction and Safety Rules for Audit Text (WL-0MMNCOIYS15A1YSI): PII redaction rules (email masking, safety notes); this intake defers implementation to that item.
• Audit Read Path in Show Outputs (WL-0MMNCOJ0V0IFM2SN): specifies how wl show should include the audit object in human and JSON outputs; update src/commands/show.ts accordingly.
• End-to-End Validation, Docs and Reuse Alignment (WL-0MMNCOQY30S8312J): final tests and docs covering write+show+redaction flows — reference when creating integration tests and operator docs.

[SorraTheOrc]

Map

Related work (automated report) appended by intake: see Intake draft file .opencode/tmp/intake-draft-Audit-Write-Path-via-CLI-Update-WL-0MMNCOIYF18YPLFB.md for details. Referenced items: WL-0MLDJ34RQ1ODWRY0, WL-0MMNCNT1M16ESD04, WL-0MMNCOIYS15A1YSI, WL-0MMNCOJ0V0IFM2SN, WL-0MMNCOQY30S8312J.

[SorraTheOrc]

Map

Intake draft created at .opencode/tmp/intake-draft-Audit-Write-Path-via-CLI-Update-WL-0MMNCOIYF18YPLFB.md. Decisions: support only --audit-text (auto time/author), overwrite existing audit, defer redaction to WL-0MMNCOIYS15A1YSI. Ready for user review.

[SorraTheOrc]

Map

Intake brief approved by requester. Proceeding with five conservative review passes, then finalizing work item description and syncing.

[SorraTheOrc]

Map

Finished Completeness review: added Risks & assumptions and Related work automated report. Finished Capture fidelity review: wording tightened but meaning preserved. Finished Related-work & traceability review: references verified. Finished Risks & assumptions review: added mitigation notes and scope creep mitigation. Finished Polish & handoff review: final summary tightened.

[SorraTheOrc]

OpenCode

Implemented WL-0MMNCOIYF18YPLFB changes locally on branch feature/WL-0MMNCOIYF18YPLFB-audit-text-write-path.

What changed:

• Added CLI write flag to update/create commands and wired persistence for structured audit object .
• Removed readiness/status parsing from audit payloads (no field now).
• Updated human formatting to render audit content and metadata.
• Updated tests/docs for semantics and overwrite behavior.

Validation:

• Focused tests: PASS (, , , , ).
• Full suite currently has 1 unrelated failing test: with at line 235.

Blocker note:

• Attempted triage helper invocation; helper failed to create a new test-failure item because local wl DB migration state is inconsistent (, missing column in for create paths).
• Because a critical test failure remains open/untriaged in this run, I did not create a commit/PR yet.