diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..686fbdf --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,28 @@ + + +## What this PR does + + + +## 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 + + + +- [ ] **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//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 + + + +- [ ] **Validation attested.** The evaluate-flow report and the AC attestation table were reviewed and check out against the cited code, at **Toolkit-Version ``**. +- [ ] **Acceptance recorded** in `reference_designs//README.md` (date · accepted-by · Toolkit-Version validated against). +- [ ] **Post-merge:** Software Heritage archival triggered (`tools/swh-save.sh `) and the returned **SWHID recorded** in the design entry. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 06814dd..c117ea7 100644 --- a/CONTRIBUTING.md +++ b/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//README.md` per [`reference_designs/templates/TEMPLATE.md`](reference_designs/templates/TEMPLATE.md) - **A copy of the design's Architecture document** at `reference_designs//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//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 `, 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/` 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//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 [] []`](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/` 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 diff --git a/reference_designs/fellows_local_db/README.md b/reference_designs/fellows_local_db/README.md index a6ffaeb..e93bf78 100644 --- a/reference_designs/fellows_local_db/README.md +++ b/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, -**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 diff --git a/tools/lint-spec-ids.py b/tools/lint-spec-ids.py index da17e6e..4ea78af 100755 --- a/tools/lint-spec-ids.py +++ b/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", ] diff --git a/tools/swh-save.sh b/tools/swh-save.sh new file mode 100755 index 0000000..96a5829 --- /dev/null +++ b/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 [] [] +# +# 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 [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//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} " + echo "or read swh:1:dir from the SH archive UI once ingest completes." +fi