edercnj/x-audit-policies

Skill: Audit Policies

Purpose

Audits src/policies/ for structural and wiring consistency — the policy counterpart of x-audit-code (codebase), audit-knowledge-consistency.sh (knowledge), and the patterns quality gate. It guarantees the policy set itself does not drift: every policy.md is well-formed against the schema, every referenced gate-skill exists, every policy is catalogued in README.md, and no policy is orphaned.

This skill does not evaluate whether a story complies with the policies (that is the Policy Validation Procedure of x-internal-verify-phase-gates --mode final). It validates the policies themselves.

Triggers

User-invocable. Also runnable in CI via the underlying script.

Skill(skill: "x-audit-policies", args: "--scope all --write-report")

Parameters

| Flag | Required | Default | Description | |------|----------|---------|-------------| | --scope | O | all | structure (frontmatter+schema), wiring (gate-skills exist), catalog (README cross-check), or all. | | --write-report | O | off | Write a markdown report to results/audits/policies-audit-YYYY-MM-DD.md. |

Algorithm

Phase 0 — Structural gate (delegated to script)
  Bash: bash src/scripts/audit-policy-consistency.sh --self-check
  Bash: bash src/scripts/audit-policy-consistency.sh
  → exit 1 = POLICY_CONSISTENCY_VIOLATION (blocking)
  → exit 2 = OPERATIONAL_ERROR
  Capture stdout/stderr (VIOLATION / WARNING lines).

Phase 1 — Schema validation (structure scope)
  Glob src/policies/*/policy.md
  For each: parse frontmatter, validate against _schema/policy.schema.json
    - required fields present; enums valid
    - type: artifact ⇒ artifact-pattern present
    - type: conformance ⇒ sources (≥2) present
    - validation block (if present) well-formed

Phase 2 — Wiring (wiring scope)
  For each policy gate-skills[] and related-skills[]:
    - assert src/skills/<skill>/SKILL.md exists
  Detect policies whose gate-skills is empty AND severity: blocking (unenforced gate).

Phase 3 — Catalog (catalog scope)
  Cross-check policies/README.md §Catálogo:
    - every policy directory appears in the catalog table
    - every catalog entry maps to a directory on disk
  Cross-check policy-set.yaml:
    - every policy named in a profile exists on disk

Phase 4 — Semantic checks
  - duplicate/overlapping detection (same artifact-pattern in two policies)
  - deprecated policies still referenced by active gate-skills
  - conformance policies whose sources tokens are unresolvable

Phase 5 — Report
  Aggregate findings by severity (CRITICAL = script VIOLATION; WARNING = advisory).
  If --write-report: emit results/audits/policies-audit-YYYY-MM-DD.md.
  Print summary table to stdout.

Output Contract

Summary printed to stdout; optional markdown report. Example summary:

Policy Audit — 16 policies
  CRITICAL: 0
  WARNING:  2
    - require-ac-test-coverage: not yet listed in README catalog
    - <policy>: gate-skill 'x-foo' not found
Result: PASS (no blocking violations)

Report file structure (when --write-report):

# Policy Audit Report — YYYY-MM-DD
Scope: all
Policies: N | CRITICAL: N | WARNING: N

## CRITICAL Findings
### [C-001] <title>
- Policy: <slug>
- Issue: <description>
- Fix: <recommendation>

## WARNING Findings
...

## Catalog Coverage
| Policy | In README | gate-skills exist | Schema valid |

Exit Behaviour

| Condition | Result | |-----------|--------| | Script exit 0, no schema/wiring criticals | PASS | | Script exit 1 (POLICY_CONSISTENCY_VIOLATION) | FAIL — report blocking findings | | Script exit 2 (OPERATIONAL_ERROR) | ABORT — environment problem |

Integration Notes

| Caller | When | What it checks | |--------|------|----------------| | CI policies-quality-gate.yml | PR touching src/policies/** | Runs the script (structural gate) | | Developer (manual) | Before opening a policy PR | Full audit with --write-report |

References

• src/scripts/audit-policy-consistency.sh — structural gate (delegated)
• src/policies/_schema/policy.schema.json — frontmatter schema
• src/policies/README.md — catalog (cross-checked)
• src/skills/x-internal-verify-phase-gates/references/full-protocol.md — runtime policy evaluator (Policy Validation Procedure; distinct concern)