fix(skills): add soup_register kind to evidence-pack source mapping#614
Merged
Merged
Conversation
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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Summary
Adds the
soup_registerkind to theevidence-packskill so the audit pack collects the SOUP register (docs/.index/soup.yamlplus optionaldocs/.index/soup.md) emitted by the siblingsoup-inventoryskill. Without this, the assembled DHF-style audit pack is missing IEC 62304 sections 5.3.3 and 8.1.1 evidence.Change Type
Affected Components
global/skills/_internal/evidence-pack/reference/source-mapping.md-- newkind: soup_registersection afterrisk_fileglobal/skills/_internal/evidence-pack/reference/manifest-schema.md-- enum extension, schema bump 1.0.0 -> 1.1.0, classification entry, example entry, CHANGES tableglobal/skills/_internal/soup-inventory/SKILL.md-- replaces three forward references to a "future"soup_registerkind with cross-references to the now-landed entriesWhy
Problem Solved
evidence-pack(PR #598) landed beforesoup-inventory(PR #604). The newersoup-inventoryskill producesdocs/.index/soup.yaml(and optionaldocs/.index/soup.md), but theevidence-packkindenum still does not listsoup_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.mdalready explicitly notes the gap (three places said "futuresoup_registerkind"). This PR closes the gap.Related Issues
Alternative Approaches Considered
soup_registeras a directory-shaped kind (mirror bothsoup.yamlandsoup.mdas 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.Who
Reviewers
Required Approvals
When
Urgency
Target Release
Next regulated-track release; the new kind will be picked up by the next
evidence-packinvocation that runs against a project carryingdocs/.index/soup.yaml.Where
Files Changed Summary
global/skills/_internal/evidence-pack/reference/source-mapping.mdkind: soup_registersection afterrisk_file. Models therisk_fileprecedent (single-file contract).global/skills/_internal/evidence-pack/reference/manifest-schema.mdsoup_registerto Allowed Kind Values table; add to Single-file vs. directory-shaped kinds classification (PR #612 added this subsection); bump_meta.schemato 1.1.0 in template + example; expand example with asoup_registerentry; add CHANGES table documenting the bump.global/skills/_internal/soup-inventory/SKILL.mdsoup_registerkind" forward references with cross-references to the now-landedsource-mapping.mdandmanifest-schema.mdentries.API/Database Changes
_meta.schemabumps 1.0.0 -> 1.1.0 in the evidence-pack manifest. Backward-compatible per the doc's own evolution policy: a new allowedkindvalue 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
risk_fileprecedent (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-controlfor risk_file,soup-inventoryfor soup_register).soup.mdcompanion 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'ssha256and its absence does not change the entry'sstatus. This avoids tying pack integrity to an optional documentation file.IEC-62304-5.3.3,IEC-62304-8.1.1) match the clauses thesoup-inventoryskill itself cites for SOUP requirements and configuration items.manifest-schema.mdis new (1.0.0 had no CHANGES line because it was the initial release); it now documents both versions for traceability.Testing Done
kindvalues, fields, and contracts are unchanged.soup-inventory/SKILL.mdcross-references point to real anchors in the updatedevidence-packreference docs.Test Plan
git diff develop...HEAD --stat-- expect 3 files changed, ~65 insertions / ~8 deletions.kind: soup_registersection insource-mapping.md-- confirm it follows the same six-field contract structure as the other kinds.manifest-schema.md-- confirmsoup_registerrow exists.soup_registeris in the Single-file row alongsidematrix,signed_commits,risk_file.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_registerkind yet.Checklist
Closes #610)