papi-sdlc-task-compliance-audit

Files (2)

• SKILL.md
• compliance-audit-task-template.md · assets/

SKILL.md (first lines)

# SDLC Task - Compliance Audit

## Purpose

This compliance audit verifies that, within the provided scope (e.g., a release):
- the implementation matches the relevant capabilities in the component specifications
- all code is properly linked to capabilities
- all capabilities are linked to some code
- the capability DAG is valid
- any test-related non-functional constraints declared in the spec are met

**CRITICAL:** No component specification can be considered 'completed' until a compliance audit has been conducted and passed.

**This needs the PAPI long task skill.**

## This audit examines; it does not execute

This audit *examines* artefacts (specs, code, links, related docs and
config). It does NOT execute tests, demos, or any normal dev/release
pipeline step. Whether the test suite currently passes is a dev/release
workflow concern, not a compliance concern.

Test code may be *consulted as an investigative aid* when it helps
clarify what the implementation does or what its public contract looks
like. It is not a compliance target in its own right. If a component
spec mandates particular tests or coverage as a non-functional
constraint, that constraint is checked by the standard non-functional
constraints step — by examining for existence and linkage, not by
execution.

## Two phases are mandatory

Before the two phases, the audit MUST run a lightweight structural
pre-pass:

- **Pre-pass — Template conformance:** check each component spec
  referenced by an in-scope capability against the current
  `papi-sdlc-component-specification`
  `component-specification-template.md`. Record any structural drift
  (missing sections, renamed fields, stale guidance, undocumented
  additions) as findings with a disposition: **update document** /
  **update template** / **accept with note**. This pass separates
  "format outdated" from "content wrong" before Phase A goes deeper.

A compliance audit MUST then run in two directions and reconcile the results:

- **Phase A — Top-down (spec → code):** for each capability in scope, find
  its implementation, verify the contract against the spec, and confirm
  the code is linked back to the capability ID.
- **Phase B — Bottom-up (code → spec):** enumerate every artefact within
  the component's scope that is — or would normally be — under version
  control (source, tests, scripts, config, CI/CD, infra-as-code,
  dependency manifests, data assets, static assets, docs, meta files);
  for each, identify the covering capability ID. Anything with no
  covering capability is an **orphan candidate**. Anything intentionally
  excluded from the sweep MUST be listed with a stated reason.
- **Phase C — Reconciliation:** merge Phase A gaps and Phase B orphan
  candidates into a single findings list.

Running only Phase A is a CRITICAL FAILURE: it lets dead or undocumented
code persist indefinitely. Both phases must be evidenced in the report.

### Orphan candidate handling

Every Phase B orphan candidate MUST be brought to the user for a
disposition decision before the audit closes. Do NOT auto-classify.
Record the decision and rationale against each candidate in the report.

## Dependencies

Reading these skills is REQUIRED to understand and execute this skill:

- PAPI skill `papi-sdlc-validate-capabilities-dag`
- PAPI skill `papi-tasks-understand`
- PAPI skill `papi-templates-understand`

## Action

- Copy and use the template (provided here under `assets`) if appropriate.
- the audit REQUIRES that you verify that implementation matches
  specification for every capability in scope
  - evidence types appropriate to examination include: capability links
    found in code (comments / docstrings / metadata), spec-to-code
    mapping tables, code excerpts showing the contract is honoured,
    references to existing CI / release records where execution
    evidence already lives
  - do NOT run tests, demos, or pipelines as part of this audit
  - it is a CRITICAL FAILURE if the spec-to-code verification is not done
- The audit MUST include a capabilities DAG validation step (using the skill). A compliance audit cannot
  pass if the DAG has cycles, orphans, or invalid references.
- Generally, this is a full audit, unless otherwise specified.
  - For a full audit, DO NOT look at older audit docs to work
    incrementally—start from scratch.
- An audit may be a large task, and sub-tasks (even a tree) may be warranted
  - The output doc (from the template) can also be made into parts if it is anticipated to get too long
    - Always follow PAPI and copy the template structure and sections, and then edit section-by-section, even if you split it into parts.
    - You may need to skeleton the components in the output doc(s) first, and then flesh them out section by section

## Outputs

- some artefact produced during the audit may be valuable to maintain for future audits (scripts, test data etc.)
  - if so, these should be tracked as PAPI components

## Skill artefacts

- **Audit template**: `assets/compliance-audit-task-template.md`

From stainsby/papi, MIT.

More from stainsby/papi