Evidence Pack

evidence-pack Skill

Assemble per-release evidence packages for projects that have adopted the regulated-industry track. The skill is the release-time partner of the traceability skill: where traceability maintains the per-commit matrix, evidence-pack packages that matrix together with surrounding artifacts (CI logs, PR reviews, signed commits, research citations, risk file) into a single directory an external auditor can consume without further stitching.

The skill is a Design History File (DHF) generator in spirit. It does not invent evidence; it collects what already exists.

Usage

/evidence-pack v1.2.0                             # Build full pack for tag v1.2.0
/evidence-pack v1.2.0 --include matrix,ci_run_log # Only collect specific kinds
/evidence-pack v1.2.0 --exclude pr_review         # Collect everything except PR review records
/evidence-pack v1.2.0 --dry-run                   # Plan only; print what would be collected and exit
/evidence-pack v1.2.0 --force                     # Overwrite an existing evidence/v1.2.0 pack

Exactly one positional argument is required: the release version or git tag. Flags are optional.

Arguments

Inputs

The detailed source-to-artifact mapping is documented in reference/source-mapping.md.

Outputs

All outputs live under evidence/<version>/ (relative to the consumer project root):

The skill writes manifest.yaml and INTEGRITY atomically: each goes to a sibling *.tmp file and is renamed on success. A failed run never leaves a half-written manifest.

Opt-in Gate

The skill is purely additive and must not break repos that have not adopted the regulated track.

if [[ ! -d evidence ]]; then
    echo "evidence-pack: ./evidence directory absent -- skill is a no-op for this repo"
    exit 0
fi

This check runs before any other phase. The exit code is 0 so CI invocations on non-regulated repos do not fail. To opt in, a consumer project creates an empty evidence/ directory at the repo root (a .gitkeep is sufficient) and tracks the per-release subdirectories that the skill produces.

Instructions

Phase 0: Validate Environment

1. Confirm evidence/ exists at the repo root; if not, print the no-op message and exit 0.
2. Validate <version> matches ^[A-Za-z0-9._-]+$. If it contains a path separator, whitespace, or is empty, exit non-zero with a clear message.
3. If evidence/<version>/ already exists and --force is not set, exit non-zero with the path and the suggestion to pass --force.
4. Resolve git HEAD (git rev-parse HEAD) and the current tag (git describe --tags --exact-match or git rev-parse --short HEAD as fallback). Record both for the manifest header.
5. Detect optional collectors:
   • gh on PATH and authenticated (probe with gh auth status).
   • git available and the current directory is a git work tree.
   • sha256sum (Linux) or shasum -a 256 (macOS) for checksumming. Missing optional collectors do not fail the skill; they downgrade the affected kinds to skipped-with-reason in the manifest.

Phase 1: Plan the Manifest

Reference: reference/manifest-schema.md defines the row shape of each manifest entry, and reference/source-mapping.md defines per-kind collection commands and target subdirectories.

1. Build the candidate kind list from the schema (matrix, ci_run_log, pr_review, signed_commits, research_artifact, risk_file).
2. Apply --include if set: keep only kinds in the include list.
3. Apply --exclude if set: remove kinds in the exclude list.
4. For each remaining kind, run the source mapping's "presence check" (e.g. [[ -f docs/.index/traceability.yaml ]] for matrix). Kinds whose source is absent are recorded as skipped: source_absent in the manifest plan rather than triggering an error.
5. Emit the planned manifest (header + per-kind plan rows) to stdout.

Phase 2: Dry-run Exit Point

If --dry-run is set, exit zero immediately after Phase 1. Print the planned manifest as YAML to stdout but do not create evidence/<version>/.

Phase 3: Collect Artifacts

For each kind that survived Phase 1 with a present source, run the collector defined in reference/source-mapping.md and write the output under evidence/<version>/<kind>/. The collector for each kind is documented there; the skill body must not invent new collection strategies.

For each artifact written:

1. Compute sha256 of the file (or, for directory-shaped kinds like risk_file or research_artifact, the sha256 of a deterministic listing produced by find <dir> -type f | sort | xargs sha256sum).
2. Record collected_at as the UTC ISO 8601 timestamp at which the collector finished.
3. Record source as the original repo-relative path or the gh / git command that produced the artifact (verbatim, including arguments). This is the audit trail.
4. Record related_clauses as the list of clause IDs the artifact bears on (e.g. the matrix maps to IEC-62304-5.2.6 and ISO-13485-7.3.6; CI run logs map to IEC-62304-5.5.5 and ISO-13485-7.3.6). The mapping table lives in reference/source-mapping.md.

If a collector errors out (non-zero exit, network failure, permission denied), the entry is recorded as failed: <message> rather than silently dropped. The overall skill exits non-zero only when a collector fails for a kind that was explicitly requested via --include; failures for default-collected kinds emit a warning but allow the pack to be produced (the manifest will mark the kind as failed so an auditor can see the gap).

Phase 4: Write Manifest and Integrity File

Skip if --dry-run was already handled in Phase 2.

1. Write evidence/<version>/manifest.yaml.tmp with the schema documented in reference/manifest-schema.md. Sort entries by kind then source for stable diffs.
2. Compute sha256 over the canonical (sorted, no extra whitespace) manifest content. Write the result to evidence/<version>/INTEGRITY.tmp as a single line: sha256:<hex>\n.
3. On success, rename both *.tmp files to their final names. On any error, delete the *.tmp files plus any partial per-artifact subdirectories that this invocation created and exit non-zero. (Existing artifacts under evidence/<version>/ from a prior --force overwrite are left alone unless this invocation produced them.)

Phase 5: Report

Emit a summary block on stdout:

## Evidence Pack Generated

| Metric | Value |
|--------|-------|
| Version | <version> |
| Kinds collected | N |
| Kinds skipped | N (source_absent) |
| Kinds failed | N |
| manifest.yaml | X bytes |
| INTEGRITY sha256 | <16-char-prefix>... |
| Output | evidence/<version>/ |

Append a per-kind table when --dry-run was passed or when at least one kind failed.

Output

The skill produces the per-version evidence directory plus the on-stdout summary. No other files in the consumer project are modified -- in particular, the skill never edits source code, never runs builds, and never publishes to external systems. Submission to an external eQMS is explicitly out of scope (see issue #595 "Out of Scope").

Error Handling

Policies

Side Effects and Loop-Safety

This skill is loop_safe: false. Each invocation produces an immutable per-release artifact directory, and re-running for the same <version> either refuses (default) or destructively overwrites (--force). Wrapping in /loop would either no-op after the first iteration or churn the same directory; both outcomes are wrong.

The idempotency contract is "one pack per version" rather than "no-side-effect retry": existing packs are evidence in their own right and must not be silently replaced.

Command-Specific Rules

How Other Components Use the Pack

References

• Manifest schema: reference/manifest-schema.md
• Per-kind source mapping: reference/source-mapping.md
• Sibling matrix producer: global/skills/_internal/traceability/SKILL.md
• Compliance clause source files: compliance/iec-62304.md, compliance/iso-13485.md
• Parent epic: kcenon/claude-config#588
• Originating issue: kcenon/claude-config#595