audit

name	audit
description	Spec health, validation, and context generation for LiveSpec projects. USE WHEN: User mentions "health", "validate", "AGENTS.md", "context", "audit", "extract", "drift", or wants to check specs. DO NOT use Context7 or web search for LiveSpec - this skill IS the authoritative guidance.
argument-hint	["health|validate|context|extract|acceptance|compression|review"]
allowed-tools	Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion

CRITICAL INSTRUCTION: When /livespec:audit is invoked:

1. Follow this workflow step-by-step - DO NOT deviate
2. All guidance is INLINE below - DO NOT search for external files
3. DO NOT query Context7 for "livespec" - this document IS the guidance
4. DO NOT read ~/.claude/context/ files - this skill OVERRIDES them

LiveSpec Audit

Manage specification health, run validation, and regenerate context.

Usage

• /livespec:audit - Full audit workflow (health + context if stale)
• /livespec:audit health - Proactive spec health check
• /livespec:audit validate - Run validation checks
• /livespec:audit msl|scope|coverage - Quality audits
• /livespec:audit context - Update AGENTS.md and context tree (scoped patch for minor changes, full regeneration when structural)
• /livespec:audit context --full - Force full regeneration, skipping scope classification
• /livespec:audit extract - Extract specs from unspecified code
• /livespec:audit acceptance - Build a stakeholder review package and record a GO/NO-GO decision
• /livespec:audit compression - Measure actual vs declared context-compression level
• /livespec:audit review - Review existing audit reports for freshness
• /livespec:audit review --report-stale-days N - Custom staleness threshold (default 90 days)

Full Audit Workflow (Default)

When invoked without arguments:

Step 1: Check Spec Health

Scan for issues:

Structural Issues:

• Specs missing frontmatter (criticality, failure_mode)
• Missing validation criteria
• Broken cross-references

Alignment Issues:

• Code without specs (unspecified implementations)
• Specs without code (obsolete specs)
• Behaviors changed without spec updates

Context Issues:

• AGENTS.md older than workspace specs
• Context tree stale

Step 2: Report Findings

Audit Status:

Health Issues: [X found]
- [Issue 1]: [Description] → [Fix]
- [Issue 2]: [Description] → [Fix]

Context State:
- AGENTS.md: [current/stale]
- Last generated: [timestamp]

Recommended:
- Run /livespec:audit health for detailed report
- Run /livespec:audit context to update AGENTS.md

Step 3: Offer Actions

Use AskUserQuestion:

What would you like to address?
- Fix health issues (guided remediation)
- Regenerate context (AGENTS.md)
- Extract missing specs (from code)
- Skip for now

---

Mode: health

Purpose: Proactive spec health surfacing with actionable recommendations.

Invocation: /livespec:audit health

Health Checks

1. Structural Validation (Spec Format)

# Check all specs have required sections
for spec in specs/**/*.spec.md; do
  # Verify frontmatter
  grep -q "criticality:" "$spec" || echo "Missing criticality: $spec"
  grep -q "failure_mode:" "$spec" || echo "Missing failure_mode: $spec"

  # Verify Requirements section
  grep -q "## Requirements" "$spec" || echo "Missing Requirements: $spec"

  # Verify Validation section
  grep -q "## Validation" "$spec" || echo "Missing Validation: $spec"
done

2. Cross-Reference Validation

# Check all referenced files exist
grep -r "satisfies:\|guided-by:\|derives-from:" specs/ | while read ref; do
  # Extract path and verify exists
done

3. MSL Compliance Check

For each spec, check:

• Line count reasonable (<100 lines preferred, <200 max)
• No implementation details (patterns like "use X library")
• Requirements are testable (not vague)

4. Coverage Check

# Find code without specs
find src/ lib/ -name "*.ts" -o -name "*.py" | while read code; do
  spec="specs/features/$(basename "$code" .ts).spec.md"
  test -f "$spec" || echo "Unspecified: $code"
done

5. Registry Health

# Required registries present, index/body in sync, staleness surfaced
bash scripts/validate-registries.sh

Surfaces missing required registries, index↔body drift, work-item-style summaries, and registries unreviewed for 3+ months. "Time to review a stale registry" is a positive maintenance signal, not a failure.

Health Report Format

All audit reports include a standard provenance block at the top before any findings. This enables freshness evaluation when reading historical reports.

# Spec Health Report

<!-- Provenance metadata — do not remove -->
**LiveSpec version:** [read from .claude-plugin/plugin.json or .livespec-version]
**Report generated:** YYYY-MM-DD HH:MM UTC
**Checks performed:** structural, cross-references, MSL compliance, coverage
**Project path:** /absolute/path/to/project
**Git HEAD:** [short SHA if git repo, else "not a git repo"]
<!-- End provenance -->

**Date:** YYYY-MM-DD
**Project:** [name]
**Overall Health:** [GREEN/YELLOW/RED] XX%

## Structural Health (X/Y passing)
- [PASS] All specs have frontmatter
- [FAIL] 3 specs missing Validation section
- [WARN] 2 specs over 200 lines

## Cross-Reference Health (X/Y valid)
- [PASS] All satisfies: references valid
- [FAIL] 1 broken guided-by: reference

## MSL Compliance (X/Y minimal)
- [PASS] Most specs under 100 lines
- [WARN] 2 specs may have implementation details

## Coverage (X/Y specified)
- [WARN] 5 code files without specs

## Remediation

1. Fix missing Validation sections in:
   - specs/features/X.spec.md
   - specs/features/Y.spec.md

2. Update broken reference:
   - specs/features/Z.spec.md → guided-by: path/old.spec.md

3. Consider extracting specs for:
   - src/auth/oauth.ts
   - src/api/payments.ts

---

Mode: validate

Purpose: Run validation checks and report pass/fail status.

Invocation: /livespec:audit validate

Validation Checks

1. Cross-Reference Integrity

• All satisfies:, guided-by:, derives-from: references point to existing files
• No circular dependencies

2. Generated File Protection

• AGENTS.md/CLAUDE.md not directly edited (check generated header)
• Regeneration needed if source specs newer

3. MSL Format Compliance

• All specs have required frontmatter
• Requirements section present with [!] markers
• Validation criteria defined

4. Folder Structure

• specs/ follows taxonomy
• No misplaced files

5. Version Synchronisation

• Four files must agree on version: .livespec-version, .claude-plugin/plugin.json ("version"), .claude-plugin/marketplace.json ("version" in the plugins array), project.yaml (livespec.version)
• .livespec-version is source of truth; report ERROR naming every file that disagrees

VERSION_FILE=$(cat .livespec-version 2>/dev/null)
PLUGIN_VERSION=$(grep -m1 '"version"' .claude-plugin/plugin.json | grep -oE '[0-9]+\.[0-9]+\.[0-9]+')
MARKETPLACE_VERSION=$(grep -m1 '"version"' .claude-plugin/marketplace.json | grep -oE '[0-9]+\.[0-9]+\.[0-9]+')
PROJECT_VERSION=$(grep -A2 '^livespec:' project.yaml | grep 'version:' | grep -oE '[0-9]+\.[0-9]+\.[0-9]+')

6. Skill/Command Manifest Consistency

• Every commands/*.md has a routes-to: field pointing at a skills/*/SKILL.md that exists
• Every skills/*/SKILL.md that has a corresponding command is reachable via that command (no orphaned skill directories expected to be user-invoked)

for cmd in commands/*.md; do
  target=$(grep -m1 '^routes-to:' "$cmd" | sed 's/routes-to: *//')
  test -f "$target" || echo "ERROR: $cmd routes-to missing file: $target"
done

7. Registry Integrity

• Required registries exist (decisions.md, debt.md, security.md)
• Entry IDs use the correct prefix per type; frontmatter index matches body sections
• No entry summary reads like a work item; no registry stale (>3 months) without acknowledgement
• Governed by specs/features/registry-specs.spec.md

bash scripts/validate-registries.sh   # exit 1 on any error; warnings for staleness / work-item language

Output Format

Validation Results:

[PASS] Cross-reference integrity (24/24 valid)
[PASS] Generated file protection (AGENTS.md current)
[FAIL] MSL format compliance (2 specs missing Validation)
[PASS] Folder structure correct
[FAIL] Version synchronisation (marketplace.json: 5.5.0, expected 5.6.0)
[PASS] Skill/command manifest consistency (7/7 commands route correctly)
[PASS] Registry integrity (required registries present, index in sync)

Overall: 5/7 checks passed

Fix required:
- specs/features/auth.spec.md: Add ## Validation section
- specs/features/payment.spec.md: Add ## Validation section
- .claude-plugin/marketplace.json: update plugins[].version to 5.6.0

---

Mode: msl|scope|coverage

Purpose: Deep quality analysis of specific aspects.

Invocation: /livespec:audit msl or /livespec:audit scope or /livespec:audit coverage

msl

Checks MSL minimalism compliance:

• Requirements are WHAT not HOW
• No implementation details
• Essential requirements only
• Proper criticality levels

scope

Checks workspace scope clarity:

• Taxonomy correctly classifies project
• Specs in correct folders
• No scope creep

coverage

Checks spec coverage:

• Code files with/without specs
• Behaviors specified
• Contracts defined

---

Mode: context

Purpose: Update AGENTS.md and context tree from workspace specifications — scoped patch for minor changes, full regeneration when structural.

Invocation: /livespec:audit context (or /livespec:audit context --full to force full regeneration)

Context Generation Workflow

Step 1: Validate Prerequisites

Check required files exist:

test -f PURPOSE.md && echo "PURPOSE.md: OK"
test -f specs/workspace/context-architecture.spec.md && echo "context-architecture: OK"
ls specs/workspace/*.spec.md

If context-architecture.spec.md missing:

Cannot generate context: specs/workspace/context-architecture.spec.md is missing.
This file defines what content populates the context tree.

Run /livespec:design workspace to create workspace specs first.

Step 2: Classify Scope (skip if --full passed — go straight to Step 3 with full)

Diff workspace specs and PURPOSE.md against the last generation (last commit that touched AGENTS.md/ctxt/):

git log -1 --format=%H -- AGENTS.md
git diff --name-only <that-commit> -- PURPOSE.md specs/workspace/

For each changed source, look it up in specs/workspace/context-architecture.spec.md's Spec → Generated File Map:

• A changed source with no generated target in the map (e.g. generated-files.spec.md, third-party-dependencies.spec.md) → exclude it from the changed-target set; it doesn't force FULL by itself
• Any remaining changed source marked Structural in the map → classify FULL
• A workspace spec was added or removed → classify FULL
• Every remaining changed source maps cleanly to existing content in a single target file → classify MINOR, scope = that target file (plus any other single targets from other changed sources, if still a small, non-overlapping set)
• If no source has a generated target at all → classify MINOR with an empty scope (nothing to regenerate)
• Anything unclear or spanning many unrelated targets → default to FULL (don't guess at a narrow patch)

Report the classification and a one-line reason, then proceed — no confirmation gate:

Detected: wording change in specs/workspace/patterns.spec.md → scoped update to ctxt/domains/governance.md.
(Say "full regenerate" to force a full rebuild instead.)

or

Detected: specs/workspace/taxonomy.spec.md domain classification changed → structural, running full regeneration.

Step 3: Spawn Background Agent

Notify user:

Regenerating context in background... (mode: full | scoped: [files])
Progress logged to var/context-generation.log

Spawn the registered context-builder agent (agents/context-builder.md) with the classified scope:

Agent tool:
  subagent_type: context-builder
  prompt: "Generate the agent context tree with scope=[full | scoped: <files>]. Write progress to var/context-generation.log."

Step 4: Completion

When agent completes, user sees summary:

Context regeneration complete. [X]KB generated in [N] files.

or, for a scoped run:

Scoped update complete: [file] updated ([size]KB). Rest of tree untouched.

Full details available in var/context-generation.log.

---

Mode: extract

Purpose: Extract specifications from existing code (brownfield projects).

Invocation: /livespec:audit extract

Extraction Workflow

Step 1: Identify Unspecified Code

# Find code without specs
for f in src/**/*.ts lib/**/*.py; do
  if ! grep -q "Implements:" "$f"; then
    echo "UNSPECIFIED: $f"
  fi
done

Step 2: Analyze Code Behavior

For each unspecified file:

• What observable behavior does it provide?
• What are the inputs/outputs?
• What error conditions are handled?
• What constraints are enforced?

Step 3: Draft Behavior Spec

Create spec with confidence markers:

---
criticality: IMPORTANT
failure_mode: Inferred - requires validation
extracted_from:
  - src/auth/oauth.py
extracted_date: 2025-01-31
confidence: LOW
requires_validation: true
extraction_reason: "Inferred from code, needs review"
---

Step 4: Present for Review

Extracted Specs (REVIEW REQUIRED):

specs/features/oauth-flow.spec.md (60% confidence)
- Extracted from: src/auth/oauth.py
- Review: Verify auth flow matches intent
- Requirements: 3 inferred

specs/features/retry-logic.spec.md (75% confidence)
- Extracted from: src/utils/retry.ts
- Review: Confirm retry parameters
- Requirements: 2 inferred

Step 5: Validate Extractions

Use AskUserQuestion to review each:

• Is this behavior correct?
• Any missing requirements?
• Should this be merged with existing spec?

Step 6: Promote Validated Specs

Remove confidence markers after review:

• confidence: LOW → remove
• requires_validation: true → remove
• Add proper satisfies: and guided-by: relationships

---

Mode: acceptance

Purpose: Stakeholder-facing acceptance ritual — build a review package from specs and validation results, then record a GO/NO-GO decision. Distinct from validate (technical pass/fail checks): this mode is about human sign-off.

Invocation: /livespec:audit acceptance

Acceptance Workflow

Step 1: Build Review Package

Assemble from existing specs and the latest validate run — do not re-derive from scratch:

• Purpose and vision — from PURPOSE.md (why this exists, what success looks like)
• Delivered behaviors by criticality — from specs/features/, grouped CRITICAL / IMPORTANT, each marked done / partial / missing
• Validation results — latest /livespec:audit validate output (tests, contract compliance, constraint satisfaction)
• Known issues — open items from registries/issues.md or equivalent, with impact and workaround if any

Step 2: Ask Review Questions

Group by theme, present via AskUserQuestion or as a checklist for the stakeholder:

• Problem validation — does this solve the stated problem? Do success criteria hold?
• Behavior validation — do all CRITICAL behaviors work as specified? Any missing?
• Constraint validation — are constraints and performance targets satisfied?
• Deployment readiness — ready for production? Any blocking issues?

Step 3: Apply Decision Rule

Decision	Condition
GO	All CRITICAL behaviors validated, all constraints satisfied, no blocking issues
GO WITH WARNINGS	All CRITICAL behaviors work; some IMPORTANT behaviors have documented warnings; no blocking issues
NO-GO	Any CRITICAL behavior failing, a constraint violated, or a blocking issue open

Step 4: Record Decision

# Acceptance Decision

**Date**: YYYY-MM-DD
**Reviewers**: [Names]
**Decision**: GO | GO WITH WARNINGS | NO-GO

## Rationale
[Why this decision was made]

## Conditions (if GO WITH WARNINGS)
- [ ] [Follow-up item, e.g. "Optimize PDF export in v1.1"]

## Sign-off
- [Reviewer 1]: Approved
- [Reviewer 2]: Approved

---

Mode: compression

Purpose: Measure actual context-compression level against the declared level and flag drift, using four quantitative metrics.

Invocation: /livespec:audit compression

Compression Workflow

Step 1: Read Declared Level

Check specs/workspace/constitution.spec.md frontmatter (or project.yaml livespec.methodology.context_compression) for light | moderate | aggressive. If absent, note undeclared (default: moderate assumed).

Step 2: Measure the Four Metrics

Metric	Formula	Light	Moderate	Aggressive
Extraction ratio	templates content ÷ (inline + templates content)	<30%	30-60%	>60%
Reference depth	avg hops from AGENTS.md to source content (0 = inline)	avg <0.5	avg 0.5-1.0	avg >1.0
Example coverage	concepts with inline examples ÷ total concepts	>70%	40-70%	<40%
Redundancy tolerance	duplicated checklists/examples across files	high	moderate	low

Step 3: Compare and Report

## Context Compression Audit

**Declared Level**: moderate
**Measured Level**: aggressive
**Alignment**: Significant mismatch

| Metric | Value | Expected (moderate) | Assessment |
|--------|-------|----------------------|------------|
| Extraction Ratio | 68% | 30-60% | Above range |
| Reference Depth | 1.3 avg | 0.5-1.0 | Above range |
| Example Coverage | 25% | 40-70% | Below range |
| Redundancy | Low | Moderate | Differs |

Step 4: Migration Plan (if a level change is recommended)

1. Update the declaration in specs/workspace/constitution.spec.md (and project.yaml if mirrored there)
2. Reorganize content — moving to higher compression: extract inline content to templates and add references; moving to lower compression: inline templates and cut reference hops
3. Regenerate with /livespec:audit context --full
4. Re-run /livespec:audit compression to confirm the new structure matches the newly declared level

---

Mode: review

Purpose: Review existing audit reports for freshness and flag stale or version-mismatched findings.

Invocation: /livespec:audit review

Review Workflow

Step 1: Collect Reports

# Current plugin version
PLUGIN_VERSION=$(grep '"version"' .claude-plugin/plugin.json 2>/dev/null | grep -o '"[0-9.]*"' | tr -d '"')
TODAY=$(date +%Y-%m-%d)
STALE_DAYS=${REPORT_STALE_DAYS:-90}  # configurable via --report-stale-days N

# Per-project issues file
test -f .livespec-audit/issues.md && echo "Found: .livespec-audit/issues.md"

# Global sweep reports (in current project's var/audit-reports/)
ls var/audit-reports/*.md 2>/dev/null || echo "No sweep reports found"

Step 2: Evaluate Each Report

For each report found, extract its provenance block:

• LiveSpec version: field → compare to current plugin version
• Report generated: field → calculate age in days
• Check if project has git commits since report date

Step 3: Classify Freshness

Condition	Status
Version matches + age < 90 days	CURRENT
Version mismatch	STALE (version)
Age > 90 days + project active since	STALE (time)
Both mismatches	STALE (both)

Step 4: Present Freshness Table

## Report Freshness Review

Plugin version: X.Y.Z | Date: YYYY-MM-DD

| Report | Version | Age | Status | Action |
|--------|---------|-----|--------|--------|
| .livespec-audit/issues.md | 5.0.0 | 45d | STALE (version) | Re-run /livespec:audit health |
| var/audit-reports/2025-11-01-sweep.md | 4.9.0 | 95d | STALE (both) | Re-run /livespec:sweep |
| .livespec-audit/issues.md | 5.1.0 | 12d | CURRENT | — |

Stale reports: N | Current: N

Step 5: Offer Actions

Use AskUserQuestion:

• "Re-run audit on stale single-project reports" → invoke /livespec:audit health for each stale project
• "Re-run sweep on stale sweep reports" → invoke /livespec:sweep to refresh portfolio audit
• "View a specific report" → Read and display the chosen report file
• "Skip"

---

MSL Format Quick Reference

All specs must follow this format:

---
criticality: CRITICAL | IMPORTANT
failure_mode: [What breaks without this]
satisfies:
  - specs/foundation/outcomes.spec.md
guided-by:
  - specs/strategy/architecture.spec.md
---

# [Name]

## Requirements

- [!] [Observable behavior - WHAT not HOW]
  - [Testable criterion 1]
  - [Testable criterion 2]

## Validation
- [How to verify]

---

Validation

[CHECKPOINT] After audit:

• All specs pass health checks
• AGENTS.md reflects current workspace specs (if generated)
• No orphaned or obsolete specs
• All cross-references valid
• If context was regenerated, the mode (full/scoped) and reasoning were reported to the user

---

References

All guidance is inline above. For extended documentation:

• LiveSpec repository: https://github.com/chrs-myrs/livespec