process: PR template, evaluate-report convention, swh-save.sh, fellows SWHID

.github/pull_request_template.md

@@ -0,0 +1,28 @@
+<!-- PNT pull-request template. Delete the sections that don't apply. -->
+
+## What this PR does
+
+<!-- One-paragraph summary. -->
+
+## Type
+
+- [ ] Reference design (new or updated), or a spec/contracts change → complete the checklists below
+- [ ] Toolkit fix / docs / tooling (no reference-design attestation needed)
+
+## Reference-design / spec contribution checklist
+
+<!-- Only if this PR adds or updates a reference design, or changes spec/contracts. See CONTRIBUTING.md. -->
+
+- [ ] **Architecture document** present (in the design's own repo) declaring its **`Toolkit-Version`**, axis picks + versions, and an **AC attestation table** with a **Verification** entry on *every* applicable AC. *(A row missing Verification is grounds for rejection.)*
+- [ ] **Exceptions** — if the design raises any, each is declared with `Relaxes:` / `Reversible:` and a per-dimension strength profile (`spec/exceptions.md`).
+- [ ] **Evaluate flow run.** The evaluate flow (`pna-build-eval-contrib/SKILL.md`) was run against the design and the typed report is committed at `reference_designs/<name>/evaluate-report.json` (an instance of `tools/evaluate-report.schema.json`), or linked here.
+- [ ] **Lint green** — `python tools/lint-spec-ids.py` passes (CI-enforced).
+- [ ] **License** is OSI-approved and permits Software Heritage archival.
+
+## Maintainer acceptance
+
+<!-- Filled by the maintainer at merge. The merge itself is the acceptance; this records what was validated. -->
+
+- [ ] **Validation attested.** The evaluate-flow report and the AC attestation table were reviewed and check out against the cited code, at **Toolkit-Version `<x.y>`**.
+- [ ] **Acceptance recorded** in `reference_designs/<name>/README.md` (date · accepted-by · Toolkit-Version validated against).
+- [ ] **Post-merge:** Software Heritage archival triggered (`tools/swh-save.sh <repo-url> <tag>`) and the returned **SWHID recorded** in the design entry.

CONTRIBUTING.md

@@ -41,7 +41,8 @@ The skill's contribute flow (driven by [`docs/users-guide.md` § Goal 3](docs/us
 - **Spec diff (if any)** — changes to `spec/PNA_Spec.md`, `spec/axes.md`, `spec/use_cases.md`, or `contracts/` files
 - **A design record** at `reference_designs/<design-name>/README.md` per [`reference_designs/templates/TEMPLATE.md`](reference_designs/templates/TEMPLATE.md)
 - **A copy of the design's Architecture document** at `reference_designs/<design-name>/Architecture.md` per [`reference_designs/templates/ARCHITECTURE_TEMPLATE.md`](reference_designs/templates/ARCHITECTURE_TEMPLATE.md)
-- **The design's canonical repo URL and the commit SHA being submitted**
+- **The design's canonical repo URL and the commit SHA (and tag, if any) being submitted**
+- **The evaluate-flow report** at `reference_designs/<design-name>/evaluate-report.json` — an instance of [`tools/evaluate-report.schema.json`](tools/evaluate-report.schema.json), produced by running the skill's evaluate flow against the design. It is the typed, diffable record of *what was validated*, and the input the maintainer attests to at acceptance.
 
 ## Acceptance process
 
@@ -54,10 +55,13 @@ Maintainer review focuses on the judgment-and-review layer of conformance verifi
 
 On merge:
 
-- Spec changes land (including any new AC IDs, sub-contracts, or axis-pick additions)
-- Maintainer triggers Software Heritage archival (planned tooling: `tools/swh-save.sh <repo-url> <commit-sha>`, landing in Phase 5; until then, archival is performed manually via Software Heritage's Save Code Now) and records the returned SWHID (Software Heritage Persistent IDentifier) in the design record
-- Maintainer decides whether the design warrants an additional `archive/<design-name>` fork in the `pnt-archive` GitHub organization (high-signal designs only; SWHID alone is sufficient for the archival promise)
-- Toolkit version bumped per the versioning rules below
+- Spec changes land (including any new AC IDs, sub-contracts, or axis-pick additions).
+- **Maintainer attests validation.** The maintainer confirms the evaluate-flow report and the AC attestation table check out against the cited code, at a specific **Toolkit-Version**, and records an acceptance line in the design record (`reference_designs/<design-name>/README.md`): *date · accepted-by · Toolkit-Version validated against*. The merge is the acceptance; this line is the durable record of *what* was validated. While there is a single maintainer this stays lightweight — and the first reference design, `fellows_local_db`, is accepted *by definition* as the design the toolkit was distilled from.
+- Maintainer triggers Software Heritage archival with [`tools/swh-save.sh <repo-url> [<git-ref>] [<clone-path>]`](tools/swh-save.sh) — a thin wrapper over Save Code Now that also prints the git-compatible SWHIDs — and records the returned `swh:1:dir` SWHID (Software Heritage Persistent IDentifier) in the design record.
+- Maintainer decides whether the design warrants an additional `archive/<design-name>` fork in the `pnt-archive` GitHub organization (high-signal designs only; SWHID alone is sufficient for the archival promise).
+- Toolkit version bumped per the versioning rules below.
+
+> **Re-validation on a version bump.** A design is validated against a specific Toolkit-Version (recorded above). A later toolkit bump does not retroactively re-validate it; the design's `Toolkit-Version` declares what it was checked against, and re-validation is a fresh evaluate-flow run when the maintainer chooses to re-attest it.
 
 ## Versioning
 

reference_designs/fellows_local_db/README.md

@@ -2,8 +2,18 @@
 
 **Maintainer:** Rich Bodo (https://github.com/richbodo/fellows_local_db)
 **License:** see upstream repo
-**First accepted:** Toolkit-Version 0.1, <YYYY-MM-DD pending>
-**Status:** active (Software Heritage SWHID pending maintainer archival post-merge; AC + exception attestation now present in `Architecture.md`)
+**First accepted:** Toolkit-Version 0.1, 2026-05-31
+**Status:** active
+
+## Acceptance & validation
+
+- **Accepted:** 2026-05-31, by the maintainer (Rich Bodo). As the design the toolkit was distilled from, `fellows_local_db` is accepted *by definition* for Toolkit-Version 0.1 (see [`CONTRIBUTING.md` § Acceptance process](../../CONTRIBUTING.md#acceptance-process)).
+- **Validated against:** Toolkit-Version 0.1. The AC + `EX-CLOUD-LLM` exception attestation is in [`Architecture.md`](Architecture.md); its Verification column cites real tests that are lint-green in CI.
+- **Accepted commit / tag:** [`v0.1.0`](https://github.com/richbodo/fellows_local_db/releases/tag/v0.1.0) — `046584cb61df269746d5bab2694952749971552f`.
+- **Software Heritage SWHID:**
+  - `swh:1:dir:2fff6ff966bf26ee2a041ee17cbea876a33215a2` (the archived source tree — canonical permanent identifier)
+  - `swh:1:rev:046584cb61df269746d5bab2694952749971552f` (the accepted revision)
+  - These are git-compatible (SH's `dir`/`rev` identifiers equal the git tree/commit hashes), computed at the tagged commit. Software Heritage archival (Save Code Now) for `https://github.com/richbodo/fellows_local_db` realizes the permanence promise; the identifiers are content-addressed and resolve unchanged once ingest completes. Re-run any time via [`tools/swh-save.sh`](../../tools/swh-save.sh).
 
 ## Summary
 

tools/lint-spec-ids.py

@@ -69,6 +69,7 @@
     "spec/PNA_Spec.md", "spec/axes.md", "spec/use_cases.md", "spec/exceptions.md",
     "pna-build-eval-contrib/SKILL.md", "CONTRIBUTING.md", "README.md",
     "tools/lint-spec-ids.py", "tools/egress-lint.py", "tools/evaluate-report.schema.json",
+    "tools/swh-save.sh",
     "reference_designs/templates/TEMPLATE.md",
     "reference_designs/templates/ARCHITECTURE_TEMPLATE.md",
 ]

tools/swh-save.sh

@@ -0,0 +1,63 @@
+#!/usr/bin/env bash
+# Toolkit-Version: 0.1
+#
+# swh-save.sh — request Software Heritage archival of a reference design's
+# source and print the git-compatible SWHIDs to record in its design entry.
+#
+# Why: PNT records a Software Heritage Persistent IDentifier (SWHID) for each
+# accepted reference design so the source survives even if the upstream repo
+# is deleted (spec/PNA_Spec.md § Vocabulary "reference design"; CONTRIBUTING
+# § Archival). SH's content/dir/rev identifiers are git-compatible, so
+# swh:1:dir / swh:1:rev can be computed locally from a clone the moment it's
+# tagged — Save Code Now then makes them resolvable and permanent.
+#
+# Usage:
+#   tools/swh-save.sh <repo-url> [<git-ref>] [<local-clone-path>]
+#
+# Examples:
+#   tools/swh-save.sh https://github.com/richbodo/fellows_local_db v0.1.0 ~/src/fellows_local_db
+#   tools/swh-save.sh https://github.com/you/your-pna     # save default branch; no local SWHID computed
+set -euo pipefail
+
+URL="${1:?usage: swh-save.sh <repo-url> [git-ref] [local-clone-path]}"
+REF="${2:-HEAD}"
+CLONE="${3:-}"
+URL="${URL%/}"
+SAVE_API="https://archive.softwareheritage.org/api/1/origin/save/git/url/${URL}/"
+
+echo "→ Requesting Software Heritage archival (Save Code Now) for:"
+echo "    ${URL}"
+if curl -fsS -X POST -H 'Accept: application/json' "$SAVE_API"; then
+  echo
+  echo "  queued — track at https://archive.softwareheritage.org/save/ (ingest can take minutes to hours)"
+else
+  echo
+  echo "  ⚠ Save request failed (network or rate-limit). Submit manually:"
+  echo "    https://archive.softwareheritage.org/save/  → paste ${URL}"
+fi
+
+echo
+# Compute the git-compatible SWHIDs from a local clone if one is available.
+GITDIR=""
+if [ -n "$CLONE" ]; then
+  GITDIR="$CLONE"
+elif git rev-parse --git-dir >/dev/null 2>&1; then
+  GITDIR="."
+fi
+
+if [ -n "$GITDIR" ] && git -C "$GITDIR" rev-parse "$REF" >/dev/null 2>&1; then
+  fmt=$(git -C "$GITDIR" rev-parse --show-object-format 2>/dev/null || echo sha1)
+  commit=$(git -C "$GITDIR" rev-parse "$REF")
+  tree=$(git -C "$GITDIR" rev-parse "${REF}^{tree}")
+  echo "SWHIDs for ${URL} @ ${REF} (${commit:0:12}):"
+  echo "  swh:1:rev:${commit}"
+  echo "  swh:1:dir:${tree}   <- record this in reference_designs/<name>/README.md"
+  if [ "$fmt" != "sha1" ]; then
+    echo "  ⚠ repo object-format is ${fmt}, not sha1 — these are NOT git-compatible;"
+    echo "    take the canonical swh:1:dir from the SH archive after ingest instead."
+  fi
+else
+  echo "No local clone provided — re-run with a clone path to compute the SWHID locally:"
+  echo "    tools/swh-save.sh ${URL} ${REF} <clone-path>"
+  echo "or read swh:1:dir from the SH archive UI once ingest completes."
+fi