pactkit-audit

name	pactkit-audit
description	H1-H7 AI Readiness Assessment — harness audit scoring and hotspot analysis
model	sonnet

PactKit Audit

H1-H7 AI Coding Harness readiness assessment. Scans project structure against a 7-layer model, produces a Harness Score (0-100), and identifies code hotspots.

When Invoked

• Done Phase 8 (Harness Audit Refresh): Auto-invoked via pactkit audit --append.
• Standalone: Ad-hoc project health assessment.
• Headless / Frontend integration: Called as /pactkit-audit via Claude Code headless mode.

The 7 Layers

Layer	Name	What It Checks
H1	Prompt Engineering	CLAUDE.md, rules, agents, commands
H2	Context Engineering	Specs, test cases, architecture graphs
H3	Process Governance	Sprint board, PDCA workflow artifacts
H4	Tool Governance	Skills, CLI tools, MCP integration
H5	Safety & Guardrails	Pre-commit hooks, security rules, credential guards
H6	Observability	Logging, cost tracking, lessons, self-audit rules
H7	Evolution	Version management, changelog, CI/CD publish

Scoring

• Each layer scores L0-L3 (None → Basic → Structured → Advanced).
• Harness Score = sum(all 7 levels) / 21 × 100.
• AI Ready = min(all 7 levels) ≥ L1.

Protocol

1. Run Audit

pactkit audit

• Outputs: scorecard + top hotspots (concise by default).
• Output file: docs/architecture/governance/harness_audit.json.

2. Options

Flag	Purpose
--json	JSON output only (machine-readable)
--layer H1-H7	Check a single layer
--append	Silent update for /project-done integration
--if-needed STORY_ID	Only refresh when harness_audit.json exists and its story_id matches; skips otherwise
--verbose	Full detail: findings + insights + hotspots

3. Interpret Results

• Score < 50: Major gaps — address weakest layer first.
• Score 50-80: Functional but room for improvement.
• Score > 80: Strong harness — focus on hotspot refinement.
• Hotspots: Files ranked by composite score (complexity, blast radius, fan-in, test coverage, smells).

4. Suggested Tasks

When hotspots are detected and developer is configured in pactkit.yaml, the audit generates suggested task entries that can be added to the sprint board.

Usage Scenarios

• /project-done: Run pactkit audit --append --if-needed {STORY_ID} — only refreshes if the audit belongs to this story; silently skips otherwise.
• Sprint planning: Run pactkit audit --verbose to identify technical debt priorities.
• CI integration: Run pactkit audit --json for machine-readable pipeline checks.
• Frontend dashboard: Call /pactkit-audit via headless mode for real-time project health.