Skip to content

fix(skills): add soup_register kind to evidence-pack source mapping#614

Merged
kcenon merged 1 commit into
developfrom
fix/issue-610-evidence-pack-soup-register-kind
May 5, 2026
Merged

fix(skills): add soup_register kind to evidence-pack source mapping#614
kcenon merged 1 commit into
developfrom
fix/issue-610-evidence-pack-soup-register-kind

Conversation

@kcenon

@kcenon kcenon commented May 5, 2026

Copy link
Copy Markdown
Owner

What

Summary

Adds the soup_register kind to the evidence-pack skill so the audit pack collects the SOUP register (docs/.index/soup.yaml plus optional docs/.index/soup.md) emitted by the sibling soup-inventory skill. Without this, the assembled DHF-style audit pack is missing IEC 62304 sections 5.3.3 and 8.1.1 evidence.

Change Type

  • Bugfix (closes a documented gap left over from sibling skill ordering)
  • Feature
  • Refactor
  • Documentation

Affected Components

  • global/skills/_internal/evidence-pack/reference/source-mapping.md -- new kind: soup_register section after risk_file
  • global/skills/_internal/evidence-pack/reference/manifest-schema.md -- enum extension, schema bump 1.0.0 -> 1.1.0, classification entry, example entry, CHANGES table
  • global/skills/_internal/soup-inventory/SKILL.md -- replaces three forward references to a "future" soup_register kind with cross-references to the now-landed entries

Why

Problem Solved

evidence-pack (PR #598) landed before soup-inventory (PR #604). The newer soup-inventory skill produces docs/.index/soup.yaml (and optional docs/.index/soup.md), but the evidence-pack kind enum still does not list soup_register, so audit packs do not collect the SOUP register. IEC 62304 §5.3.4 / §8.1.2 require the SOUP register in the audit submission; an auditor would currently flag the omission.

soup-inventory/SKILL.md already explicitly notes the gap (three places said "future soup_register kind"). This PR closes the gap.

Related Issues

Alternative Approaches Considered

  1. Treat soup_register as a directory-shaped kind (mirror both soup.yaml and soup.md as equal artifacts) -- rejected because the YAML is the canonical record and the Markdown is a derived view; sha256 over both would tie pack integrity to the optional companion's presence.
  2. Defer the schema bump to a "kinds revamp" PR -- rejected because the issue is acceptance-tested on schema 1.1.0 specifically and the bump is purely additive (consumers ignoring unknown kinds remain valid).

Who

Reviewers

  • Repo owner

Required Approvals

  • Code owner

When

Urgency

  • Normal -- additive documentation/contract change, no runtime behavior modified

Target Release

Next regulated-track release; the new kind will be picked up by the next evidence-pack invocation that runs against a project carrying docs/.index/soup.yaml.

Where

Files Changed Summary

File Change
global/skills/_internal/evidence-pack/reference/source-mapping.md New kind: soup_register section after risk_file. Models the risk_file precedent (single-file contract).
global/skills/_internal/evidence-pack/reference/manifest-schema.md Add soup_register to Allowed Kind Values table; add to Single-file vs. directory-shaped kinds classification (PR #612 added this subsection); bump _meta.schema to 1.1.0 in template + example; expand example with a soup_register entry; add CHANGES table documenting the bump.
global/skills/_internal/soup-inventory/SKILL.md Replace three "future soup_register kind" forward references with cross-references to the now-landed source-mapping.md and manifest-schema.md entries.

API/Database Changes

  • Schema: _meta.schema bumps 1.0.0 -> 1.1.0 in the evidence-pack manifest. Backward-compatible per the doc's own evolution policy: a new allowed kind value is a minor bump, pre-1.1.0 manifests remain valid, and consumers that ignore unknown kinds continue to work without modification.

How

Implementation Highlights

  • Modeled on the risk_file precedent (PR docs(skills): align evidence-pack risk_file kind with single-file contract #612): both are single-file kinds whose source is a normalized YAML produced by a sibling skill (risk-control for risk_file, soup-inventory for soup_register).
  • The soup.md companion is collected when present so the audit pack carries the same human-readable view the project ships, but it is not part of the kind's sha256 and its absence does not change the entry's status. This avoids tying pack integrity to an optional documentation file.
  • Related clauses (IEC-62304-5.3.3, IEC-62304-8.1.1) match the clauses the soup-inventory skill itself cites for SOUP requirements and configuration items.
  • The CHANGES table in manifest-schema.md is new (1.0.0 had no CHANGES line because it was the initial release); it now documents both versions for traceability.

Testing Done

  • Verified the diff is purely additive: existing kind values, fields, and contracts are unchanged.
  • Verified the soup-inventory/SKILL.md cross-references point to real anchors in the updated evidence-pack reference docs.
  • Verified the example minimal manifest still parses as YAML (visual inspection; the example was already minimal and only gained one entry plus three counter bumps).

Test Plan

  1. git diff develop...HEAD --stat -- expect 3 files changed, ~65 insertions / ~8 deletions.
  2. Read the new kind: soup_register section in source-mapping.md -- confirm it follows the same six-field contract structure as the other kinds.
  3. Read the Allowed Kind Values table in manifest-schema.md -- confirm soup_register row exists.
  4. Read the Single-file vs. directory-shaped kinds classification -- confirm soup_register is in the Single-file row alongside matrix, signed_commits, risk_file.
  5. Read the CHANGES table -- confirm both 1.0.0 and 1.1.0 entries exist with backward-compat note.

Breaking Changes

None. Schema bump is a minor version (additive enum value only). Pre-1.1.0 manifests remain valid; consumers that ignore unknown kinds continue to work.

Rollback Plan

Revert this PR. No data migration required because no project has produced an evidence pack with the soup_register kind yet.

Checklist

  • Code follows project style guidelines
  • Self-review completed
  • No tests required (documentation-only change; no runtime code paths modified)
  • Documentation updated (the change IS documentation)
  • No sensitive data exposed
  • Commits are atomic and well-described
  • Related issue(s) linked with closing keywords (Closes #610)

Extends the evidence-pack manifest schema (1.0.0 -> 1.1.0) to include
soup_register as an allowed kind, and documents its collection contract
in source-mapping.md. The new kind is the audit-time companion to the
soup-inventory skill (issue #601, PR #604), which produces
docs/.index/soup.yaml plus an optional human-readable
docs/.index/soup.md.

Changes:
- source-mapping.md: new kind: soup_register section after risk_file,
  modeled on the risk_file precedent (single-file contract). Source
  presence check, collection commands, output layout, sha256 strategy
  (over soup.yaml only), and related clauses (IEC-62304-5.3.3 and
  IEC-62304-8.1.1) all populated.
- manifest-schema.md: add soup_register to the Allowed kind enum and
  to the Single-file vs. directory-shaped kinds classification (added
  by PR #612 for risk_file). Bump _meta.schema to 1.1.0 in the schema
  template and the minimal-manifest example, expand the example to
  include a soup_register entry, and add a CHANGES table documenting
  the version bump.
- soup-inventory/SKILL.md: replace the three forward references to a
  future soup_register kind with cross-references to the now-landed
  source-mapping.md and manifest-schema.md entries.

The schema bump is backward-compatible per the doc's own evolution
policy: adding a new allowed kind is a minor bump, pre-1.1.0 manifests
remain valid, and consumers that ignore unknown kinds continue to work
without modification.

Closes #610
@kcenon kcenon merged commit eadc79d into develop May 5, 2026
1 check passed
@kcenon kcenon deleted the fix/issue-610-evidence-pack-soup-register-kind branch May 5, 2026 01:56
@kcenon kcenon mentioned this pull request Jun 8, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant