repo-compliance-audit

Repo Compliance Audit

This skill provides a two-phase workflow:first audit and produce a report, then have humans check the items requiring remediation, and finally perform selective remediation. The core goals are "forensically verifiable compliance review" and "minimal remediation, by default not changing business logic".

Workflow (Audit → Human Check → Remediation)

1) Audit (read-only audit, by default does not modify the repository)

Run in the target repository root directory (or use --repo to specify):

python3 scripts/audit_repo.py --repo . --out /tmp/repo-compliance-audit

Output:

• report.md: human-readable audit report (conclusion summary, risk grading, evidence, remediation checklist)
• findings.json: machine-readable findings list (including finding.id, evidence, and suggested fixes)

CI / gate usage (optional):

python3 scripts/audit_repo.py --repo . --out /tmp/repo-compliance-audit --fail-on high

Recommended gate strategy (oriented toward "execution process aligned with AGENTS.md")

• Minimal gate (recommended default): use --fail-on high, mainly intercepts:
  • High risk of rule file integrity:AGENTS_MD_DELETED / AGENTS_MD_MODIFIED
  • High risk of process evidence:AGENTS_EXECUTION_TEST_EVIDENCE_MISSING
  • Obvious security risk:POSSIBLE_SECRET_FOUND
• Strict gate (enable as needed): use --fail-on medium, will additionally intercept:
  • Spec-first evidence missing category (e.g. SPEC_ENTRYPOINT_MISSING、AGENTS_EXECUTION_SPEC_FIRST_EVIDENCE_MISSING）
  • worklog process evidence missing category (e.g. AGENTS_EXECUTION_WORKLOG_EVIDENCE_MISSING）

Output redaction (recommended to enable when sharing reports):

# 仅脱敏 report.md（保留 findings.json 供系统编排/整改使用）
python3 scripts/audit_repo.py --repo . --out /tmp/repo-compliance-audit --redact report

# report.md + findings.json 均脱敏（对外共享）
python3 scripts/audit_repo.py --repo . --out /tmp/repo-compliance-audit --redact all

Reduce leakage/noise (optional):

python3 scripts/audit_repo.py --repo . --out /tmp/repo-compliance-audit --no-git-meta
python3 scripts/audit_repo.py --repo . --out /tmp/repo-compliance-audit --no-secret-scan

2) Humans check the items to be remediated

From report.md or findings.json select finding.id, separated by commas or written to a file.

3) Remediation (selective remediation, by default only runs safe-to-autofix)

python3 scripts/remediate_repo.py \
  --repo . \
  --findings /tmp/repo-compliance-audit/findings.json \
  --select DOCS_INDEX_MISSING,ENV_EXAMPLE_MISSING

Constraints:

• By default only execute safe_to_autofix=true fix items
• By default do not overwrite existing files (unless explicitly --overwrite）
• By default do not change business logic (only perform "compliance skeleton/evidence/repository hygiene" type fixes)

How outputs are used by the system (strong structure vs ecosystem compatibility)

• Control-plane strong structure：findings.json used for system-level interaction (orchestratable, auditable, can be used for gates).
• Friendly to the human ecosystem：report.md prioritizes readability and does not force structured JSON.
• Avoid forcing structure at every node: only enable when "the gate/node truly needs machine-readable judgment" --fail-on or only gate certain findings.
• Rule file integrity first: if you care about the coding agent's rules being "deleted/tampered with", you can focus on the audit output's AGENTS_MD_DELETED/AGENTS_MD_MODIFIED/AGENTS_MD_UNTRACKED(based on git forensics; if it is not a git repository, it can only prompt).

Resources

• ./scripts/audit_repo.py: audit entry point
• ./scripts/remediate_repo.py: remediation entry point (selectively execute according to finding.id )
• ./references/finding-catalog.md: finding ID directory (for extension/alignment of terminology)