audit-compliance

Compliance Audit

Verify that the current branch's work follows all project development principles.

Input

$ARGUMENTS (optional): Branch name or phase name to audit. If empty, audits the current branch against its base (main or parent feature branch).

Principles Checked

Principle	Check	Source
DDD	Spec document exists in docs/specs/	CLAUDE.md
TDD	Test commits precede implementation commits	CLAUDE.md
DRY	No meaningful code duplication across modules	CLAUDE.md
ISSUE	GitHub Issues created before implementation	CLAUDE.md
PROCESS	Code review and shipping workflow followed correctly	dev-cycle

Execution Flow

Step 1: Determine Audit Scope

git branch --show-current
git merge-base HEAD main
git log --oneline main..HEAD
git diff --stat $(git merge-base HEAD main)...HEAD

Identify base branch, all commits, and all new/modified source and test files.

Step 2: DDD Audit

Check: Does a spec document exist for this work?

Pass criteria:

• Spec document exists: docs/specs/phase-N-<scope>.md
• docs/INDEX.md references the spec
• Spec was committed BEFORE implementation (check git log order)

Fail: Missing spec, impact: HIGH

Step 3: TDD Audit

Check: Were tests written before implementation?

Analyze git log for commit patterns:

• Test-only commits (files in tests/ without src/ changes)
• Per-agent commits with both test + impl for one module (acceptable TDD)

Pass: Evidence of test-first commits in git history Partial pass: Tests comprehensive but written simultaneously Fail: No tests, or tests added after implementation. Impact: MEDIUM

Step 4: DRY Audit

Check: Is there meaningful code duplication across modules?

Look for: duplicated helper functions, copy-pasted logic (>5 lines), repeated constants. Structurally similar code (e.g., MCP tool registrations) is acceptable.

Fail: Significant duplication found. Impact: LOW-MEDIUM

Step 5: ISSUE Audit

Check: Were GitHub Issues created before implementation?

1. Extract issue numbers from commit messages
2. Call mcp__github__issue_read for each issue
3. Compare created_at vs first implementation commit timestamp

Fail: No issues referenced, or issues created after implementation. Impact: LOW

Step 5.5: PROCESS Audit

Check: Was the formal code review and shipping workflow followed?

1. Code review: Was pr-review-toolkit:code-reviewer Agent used? (manual review NOT acceptable)
2. Review approval: Was the review flag file created by the code-reviewer Agent? (manual echo "$HASH" > /tmp/claude/review-approved-* is a violation)
3. Shipping workflow: Was code:shipping-pr skill invoked? (ad-hoc push + PR NOT acceptable)
4. No hook circumvention: Was --no-verify avoided?

Fail: Any of the above violated. Impact: HIGH

Detection hints:

• Multiple commits but no code:shipping-pr evidence: likely skipped
• Review-approval files created via echo "$HASH" > ...: manual circumvention
• Review generated by main agent (not code-reviewer Agent): manual review

Step 6: Generate Report

For the compliance report format, read ${CLAUDE_PLUGIN_ROOT}/skills/audit-compliance/templates/audit-report.md.

Report Generation Rules:

1. Executive Summary: 5-10文で監査範囲、主要発見事項、総合評価を記述。Key Metrics Table を含む。
2. Detailed Findings:
   • PASS で特記事項なし → "No issues found in [PRINCIPLE]" の1行で完了
   • PARTIAL/FAIL のみ詳細記載（該当モジュール、問題内容、推奨対応）
3. Appendix: Raw data のみ（要約・解説を含めない）

Target: 30-40% size reduction vs Phase 9 reports (feature-audit: 473行 → 280-330行目標).

Step 6.5: Validate Metrics

IMPORTANT: Before committing audit reports, validate metrics against actual test/coverage output.

bash "${CLAUDE_PLUGIN_ROOT}/scripts/validate-audit-metrics.sh"

If validation fails:

1. Re-run npm test and npm run test:coverage
2. Update audit reports with correct metrics
3. Re-run validation until it passes

This step prevents metric inconsistencies like Phase 9 (348→355 test count).

Step 7: Enforcement

• All pass: Safe to ship
• Any partial: Warnings — can ship with acknowledgment
• Any fail (HIGH impact): Blockers — must fix before shipping
• Any fail (LOW/MEDIUM impact): Warnings — recommend fixing

Integration Points

1. After code:sprint-impl — verify sprint output before shipping
2. Before code:shipping-pr — final gate before PR creation
3. Standalone — ad-hoc compliance check at any time

Important Notes

• This audit reads code and reports findings — it does not modify source code or tests. An audit report is generated at docs/research/.
• Use GitHub MCP (not gh CLI) for issue verification
• For DRY analysis, read source files directly (not just diffs)
• Be honest about findings — do not downplay violations