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

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

Author: kcenon

global/skills/_internal/evidence-pack/reference/manifest-schema.md

@@ -13,7 +13,7 @@ semantics. Auditors and downstream consumers should treat this file as the contr
 # evidence/<version>/manifest.yaml
 # Generated by /evidence-pack -- do not edit by hand
 _meta:
-  schema: "1.0.0"           # Schema version of this document
+  schema: "1.1.0"           # Schema version of this document
   generated: "YYYY-MM-DDTHH:MM:SSZ"  # ISO 8601 UTC timestamp
   generator: "evidence-pack"         # Skill name that produced this artifact
   version: "<version>"      # The release version this pack documents
@@ -82,6 +82,7 @@ The kind value is a closed enum. Adding a new kind requires updating both this f
 | `signed_commits` | `evidence/<version>/signed_commits/` | Plain text from `git log --format='%H %G? %s' <prev-tag>..<version>` showing the signature status (`G`/`B`/`U`/`N`/`X`/`Y`/`R`/`E`) of every commit in the release. |
 | `research_artifact` | `evidence/<version>/research_artifact/` | Mirror of files under `docs/research/` that document external citations (per the `research` skill output). |
 | `risk_file` | `evidence/<version>/risk_file/risk-file.yaml` | Verbatim copy of the single normalized risk file at `docs/.index/risk-file.yaml` produced by the sibling `risk-control` skill. **Single file** contract -- the `risk_file/` subdirectory contains exactly one file, retained for per-kind directory symmetry. |
+| `soup_register` | `evidence/<version>/soup_register/soup.yaml` | Verbatim copy of the single normalized SOUP register at `docs/.index/soup.yaml` produced by the sibling `soup-inventory` skill. Optional companion `soup_register/soup.md` collected when `docs/.index/soup.md` exists. **Single file** contract -- the kind's `sha256` is computed over `soup.yaml` alone; the `soup.md` companion is documentation only. |
 
 A kind whose source is genuinely absent in a project (e.g. no `docs/.index/risk-file.yaml`
 yet) should appear in the manifest with `status: skipped` and `reason: source_absent` rather
@@ -94,7 +95,7 @@ and must not be inferred from the `output_path`:
 
 | Shape | Kinds | sha256 over |
 |-------|-------|-------------|
-| Single file | `matrix`, `signed_commits`, `risk_file` | The bytes of the one collected file. |
+| Single file | `matrix`, `signed_commits`, `risk_file`, `soup_register` | The bytes of the one collected file. |
 | Directory listing | `ci_run_log`, `pr_review`, `research_artifact` | `find <kind>/ -type f \| sort \| xargs sha256sum` (deterministic listing). |
 
 **The `risk_file` kind is single-file**: the collector copies the single normalized
@@ -104,6 +105,16 @@ directory symmetry and contains exactly one file. Future evidence-pack consumers
 treat `risk_file` as single-file; promoting it to a directory mirror would be a
 backward-incompatible schema change requiring a major `_meta.schema` bump.
 
+**The `soup_register` kind is single-file**: the collector copies the single normalized
+`docs/.index/soup.yaml` produced by the sibling `soup-inventory` skill, plus an optional
+`docs/.index/soup.md` companion when present. The kind's `sha256` covers `soup.yaml`
+alone; the `soup.md` file is collected for human-readable convenience but is not part of
+the checksum and its absence does not change the entry's `status`. Future evidence-pack
+consumers must treat `soup_register` as single-file; promoting it to a directory mirror
+(e.g. shipping per-supplier breakouts as separate files inside `soup_register/`) would
+be a backward-incompatible schema change requiring a major `_meta.schema` bump. New SOUP
+artifacts beyond `soup.yaml` and `soup.md` should land under a separate `kind`.
+
 ### Status Field
 
 The `status` value is set by the collector in Phase 3 and then frozen.
@@ -152,7 +163,7 @@ commits (a project that has not yet wired up `gh` or a risk file):
 
 ```yaml
 _meta:
-  schema: "1.0.0"
+  schema: "1.1.0"
   generated: "2026-05-04T12:34:56Z"
   generator: "evidence-pack"
   version: "v0.1.0"
@@ -161,9 +172,9 @@ _meta:
   tool_versions:
     git: "git version 2.43.0"
     gh: "unavailable"
-  artifacts: 6
+  artifacts: 7
   collected: 2
-  skipped: 4
+  skipped: 5
   failed: 0
 
 artifacts:
@@ -231,6 +242,17 @@ artifacts:
       - IEC-62304-7.1.1
       - IEC-62304-7.2.1
     notes: ""
+
+  - kind: soup_register
+    source: "docs/.index/soup.yaml"
+    collected_at: "2026-05-04T12:34:54Z"
+    sha256: null
+    status: skipped
+    reason: "source_absent"
+    related_clauses:
+      - IEC-62304-5.3.3
+      - IEC-62304-8.1.1
+    notes: ""
 ```
 
 ## Example: Failed Entry
@@ -287,6 +309,13 @@ The `evidence-pack` skill writes the matching schema version into `_meta.schema`
 generation. External tooling that consumes `manifest.yaml` should refuse to parse when the
 major does not match the schema this file documents.
 
+### CHANGES
+
+| Schema | Date | Change |
+|--------|------|--------|
+| `1.0.0` | 2026-04 | Initial release. Allowed kinds: `matrix`, `ci_run_log`, `pr_review`, `signed_commits`, `research_artifact`, `risk_file`. |
+| `1.1.0` | 2026-05 | Added allowed kind `soup_register` for the SOUP register produced by the sibling `soup-inventory` skill (`docs/.index/soup.yaml` plus optional `docs/.index/soup.md`). Backward-compatible: pre-1.1.0 manifests remain valid (the new kind only adds an enum value), and consumers that ignore unknown kinds continue to work without modification. |
+
 ## Cross-references
 
 - Per-kind collection commands and target subdirectories: `source-mapping.md`

global/skills/_internal/evidence-pack/reference/source-mapping.md

@@ -138,6 +138,33 @@ attempt to mirror a `risk-file/` directory. Future evidence-pack consumers must
 those should be introduced under a new `kind` rather than by promoting `risk_file` to a
 directory mirror (which would be a backward-incompatible schema change).
 
+## kind: soup_register
+
+Snapshot of the project's SOUP (Software Of Unknown Provenance) register produced by the
+sibling `soup-inventory` skill.
+
+| Field | Value |
+|-------|-------|
+| **Source presence check** | `[[ -f docs/.index/soup.yaml ]]` |
+| **Required tools** | None (plain file copy). |
+| **Collection command(s)** | `mkdir -p evidence/<version>/soup_register`<br>`cp docs/.index/soup.yaml evidence/<version>/soup_register/soup.yaml`<br>`[[ -f docs/.index/soup.md ]] && cp docs/.index/soup.md evidence/<version>/soup_register/soup.md \|\| true` |
+| **Output layout** | Primary file: `evidence/<version>/soup_register/soup.yaml`. Optional companion: `evidence/<version>/soup_register/soup.md` when the source `docs/.index/soup.md` exists. |
+| **sha256 strategy** | Single file: `sha256sum evidence/<version>/soup_register/soup.yaml`. The optional `soup.md` companion is documentation only and is not factored into the kind's checksum. |
+| **Related clauses** | `IEC-62304-5.3.3`, `IEC-62304-8.1.1` |
+
+The SOUP register is owned by the sibling `soup-inventory` skill (issue #601, PR #604) and
+is emitted as a single normalized YAML file at `docs/.index/soup.yaml`, with an optional
+human-readable per-supplier report at `docs/.index/soup.md` (produced by
+`/soup-inventory report`). The collection contract is **single file**: the canonical
+artifact is `soup.yaml` and the kind's `sha256` is computed over that file alone. The
+`soup.md` companion is collected when present so the audit pack carries the same
+human-readable view the project ships, but its absence does not affect the kind's status
+(`collected` when `soup.yaml` was copied successfully) and it is not part of the checksum.
+Future evidence-pack consumers must treat `soup_register` as a single-file kind -- if a
+project ever needs additional SOUP artifacts beyond the YAML and its Markdown render,
+those should be introduced under a new `kind` rather than by promoting `soup_register` to
+a directory mirror (which would be a backward-incompatible schema change).
+
 ## Atomic Write Pattern
 
 Every collector writes through a temp path, then renames on success:

global/skills/_internal/soup-inventory/SKILL.md

@@ -44,7 +44,8 @@ the regulated-industry track. The skill is the third-party-software counterpart
 `risk-control` (which owns the hazard records) and `traceability` (which owns the
 requirements-to-evidence matrix): it produces and maintains the per-project SOUP file that
 the traceability matrix references via a new `soup_ids[]` field on each requirement row, and
-that the `evidence-pack` skill collects under a future `soup_register` kind.
+that the `evidence-pack` skill collects under the `soup_register` kind (see
+`global/skills/_internal/evidence-pack/reference/source-mapping.md`).
 
 The skill does not invent regulatory content; it provides a structured, validatable home
 for the records that IEC 62304 sections 5.3.3 (specify functional and performance
@@ -92,7 +93,7 @@ The skill never reads source code, never runs builds, and never calls out to ext
 
 | Path | Format | Audience |
 |------|--------|----------|
-| `docs/.index/soup.yaml` | YAML | Single normalized SOUP register. Consumed by `traceability` (via `soup_ids[]`) and `evidence-pack` (via the future `soup_register` kind). Schema: `reference/soup-record-schema.md`. |
+| `docs/.index/soup.yaml` | YAML | Single normalized SOUP register. Consumed by `traceability` (via `soup_ids[]`) and `evidence-pack` (via the `soup_register` kind). Schema: `reference/soup-record-schema.md`. |
 | `docs/.index/soup.md` | Markdown | Human-readable per-supplier report produced by `report`. Suitable for inclusion in audit-time exports. |
 
 Both files are written atomically: the skill writes to a sibling `*.tmp` file and renames on
@@ -322,7 +323,7 @@ verbatim rather than inventing new mappings.
 | Consumer | Use |
 |----------|-----|
 | `traceability` skill (P0-1) | Reads `soup.yaml` to populate `soup_ids[]` on requirement matrix rows. Bidirectional linking comes for free. |
-| `evidence-pack` skill (P1-1) | Will mirror `soup.yaml` (and the per-supplier `soup.md` report when present) under a future `soup_register` kind in the per-release evidence pack. The current `evidence-pack` source-mapping does not yet enumerate this kind; a follow-up issue will add it. |
+| `evidence-pack` skill (P1-1) | Mirrors `soup.yaml` (and the per-supplier `soup.md` report when present) under the `soup_register` kind in the per-release evidence pack. See `global/skills/_internal/evidence-pack/reference/source-mapping.md` (kind: `soup_register`) and `manifest-schema.md` (allowed kinds, schema `1.1.0`). |
 | `risk-control` skill (P1-2) | Cross-references SOUP records when a hazard's failure mode involves third-party software; the link is recorded as a `verification_refs[]` entry pointing to the relevant `H-NN` id. |
 | `traceability-guard` PreToolUse hook (P0-2) | Could be extended to detect when a PR adds or bumps a lockfile entry without updating the SOUP register. |
 | External auditor | Reads `soup.yaml` and `soup.md` directly from the repo at any tagged release; consumes them alongside the matrix as the operational SOUP-management record. |