Skip to content

[Feature] Audit-skill artefact persistence + canonical structure #218

@atlas-apex

Description

@atlas-apex

User Story

As a portfolio operator running audit skills periodically (/threat-model, /security-review, /compliance-check, /accessibility-audit, /performance-audit, /seo-audit, /monitoring-audit, /docs-audit, /analytics-audit), I want each run to write a structured artefact to a canonical location with consistent frontmatter, so that I can compare audit runs over time and see whether a project's risk posture is improving or regressing.

Acceptance Criteria

  • Extract /launch-check's persistence + trend-rendering pattern into a shared library at .claude/hooks/_lib-audit-history.sh (read / write / append-trend / list-recent), with tests in .claude/hooks/tests/test_audit_history.sh
  • Define a canonical artefact path: projects/<name>/audits/<dimension>/<YYYY-MM-DD>-<short-sha>.md
  • Define required frontmatter fields: date, sha, dimension, skill_version, verdict (one of pass / conditional / fail), and a scored_items[] array each with id, severity, status
  • Add canonical templates at templates/audits/<dimension>.md for each of the nine audit dimensions; remove the inline stdout-only templates currently buried in each SKILL.md
  • Pilot retrofit on /threat-model and /security-review. Each writes the artefact AND renders the "Trend (last 5 runs)" section after persisting, same shape /launch-check already uses
  • Stdout summary preserved — the persisted artefact is additional output, not a replacement for what the operator sees in the terminal
  • /launch-check itself is refactored to consume the shared lib without behaviour change (regression-tested against its existing history store)
  • Follow-up ticket filed for retrofitting the remaining seven audit skills (/compliance-check, /accessibility-audit, /performance-audit, /seo-audit, /monitoring-audit, /docs-audit, /analytics-audit) — they adopt the same path + frontmatter via the shared lib

Design Notes

No UI changes. Markdown artefacts + a shared bash lib + nine templates.

Storage choice (defaults, overridable in .claude/project-config.jsonaudit.persistence):

  • committed (default) — artefacts in projects/<name>/audits/**/*.md are tracked in git so the trend is visible to anyone reading project docs and survives clones
  • local-only — adopters who don't want audit history in git override to gitignore the path

Frontmatter is the load-bearing piece: it's what _lib-audit-history.sh parses to render the trend section. Operators editing artefacts by hand keep the frontmatter intact; freeform editing is fine in the body.

Out of Scope

  • Migrating existing free-form audit outputs to the new format — there are no persisted historical runs to backfill; the trend starts from the first post-feature run.
  • Cross-project audit aggregation (a portfolio-wide "show me every audit's latest verdict across all managed projects" view). Useful later, separate ticket.
  • Changing what each audit actually checks — this ticket is purely about persistence, structure, and trend rendering. Audit content changes are out of scope.

Effort Estimate

TBD

Metadata

Metadata

Assignees

No one assigned

    Labels

    P1High — material gap or user-impactingenhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions