From 3a15d64f216a81645efdd6f73d30316e98230643 Mon Sep 17 00:00:00 2001 From: hyperpolymath <6759885+hyperpolymath@users.noreply.github.com> Date: Wed, 17 Jun 2026 04:07:44 +0100 Subject: [PATCH] docs: add de-template tidy continuation guide A durable in-repo guide (docs/developer/TIDY-CONTINUATION-GUIDE.adoc) so the context and discipline of the de-templating effort travel with the code: what snifs is + ground-truth numbers; the non-negotiable rules (licence flag-only, signed commits, the strict pre-commit hook, stop-before-push, look-before- delete); the remaining work-packages (WP-4/WP-5) and open decisions (D-a..D-f); the working method; and the repo-specific gotchas (snif vs snifs + the substring trap, phantom recipes, DOC-FORMAT, the AI-manifest convention, Containerfile-at- root, settings.yml rename risk). Live PR state is a dated snapshot that points at `gh pr list` so it does not go stale. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/developer/TIDY-CONTINUATION-GUIDE.adoc | 141 ++++++++++++++++++++ 1 file changed, 141 insertions(+) create mode 100644 docs/developer/TIDY-CONTINUATION-GUIDE.adoc diff --git a/docs/developer/TIDY-CONTINUATION-GUIDE.adoc b/docs/developer/TIDY-CONTINUATION-GUIDE.adoc new file mode 100644 index 0000000..12658eb --- /dev/null +++ b/docs/developer/TIDY-CONTINUATION-GUIDE.adoc @@ -0,0 +1,141 @@ +// SPDX-License-Identifier: MPL-2.0 +// Owner: Jonathan D.A. Jewell += snifs De-template Tidy — Continuation Guide +:toc: preamble +:icons: font + +Guide for any agent or maintainer continuing the snifs repository de-templating +effort. The durable parts (rules, method, gotchas) below do not go stale; the +live PR state in <> is a dated snapshot — always re-check `gh pr list` and +`git log --oneline -15` first. The full, evolving plan lives in +`~/developer/dev-notes/2026-06-16-snifs-phase2-detemplate-plan.adoc`. + +== What snifs is (don't misframe it) + +SNIF = *Safer NIF*. Native code (Zig today, Rust wired) is compiled to +`wasm32-freestanding` with `-OReleaseSafe` and run under `wasmtime` via `wasmex`, +so a guest trap becomes a catchable `{:error, reason}` and the BEAM survives. It is +a *research + reference repository* (architecture paper + working BEAM/WASM +implementation + formal proofs), *not* an installable app. It is one realized point +on the `cleave` dial — not "the cleave"; keep cleave/groove ambitions out. + +Ground-truth numbers (verify before repeating any claim): *21/21* in-BEAM ExUnit; +*10* machine-checked proofs (6 Idris2 ABI + 1 Idris2 core + 1 Lean4 + 2 Agda); ABI +conformance gates *15 of 20* Zig sites; `zig/src/safe_nif.zig` has *8 exports of +which 5 are `crash_*`*. "Six crash modes", "11/11", or "7 proofs" = stale. + +[[state]] +== Live state — snapshot 2026-06-17 (re-verify with `gh pr list`) + +[cols="1,2,3", options="header"] +|=== +| PR | Branch | Scope +| #42 | `chore/repo-tidy-2026-06-16` | A–D tidy + safe-subset identity (11 commits) +| #43 | `fix/manifest-parent-pointers` | WP-1: 5 manifest parent pointers +| #44 | `chore/identity-snif-to-snifs` | WP-2: snif/rsr-template-repo → snifs (20 files) +|=== + +All disjoint, signed, awaiting owner merge (admin-merge is owner-only). WP-1 and +WP-2 done. WP-3 (CLADE clade-prefix) *dropped by owner decision* — leave the +`[clade]` block in `.machine_readable/CLADE.a2ml` as-is. + +== Hard rules — non-negotiable + +. *Licence / SPDX = owner-only, flag-only.* Never auto-edit a LICENSE file, an + `SPDX-License-Identifier`, or relicense — even if policy-correct. PMPL is forbidden + outside `palimpsest-license` / `palimpsest-plasma` / `consent-aware-http`. + `AFFIRMATION.adoc`'s dual `MPL-2.0 OR CC-BY-SA-4.0` is correct — leave it. +. *Sign every commit:* `git commit -S` with `id_ed25519_signing` (NEVER the auth-only + `id_ed25519`). Verify with `git verify-commit HEAD`. Never `--no-verify`. +. *Keep the pre-commit hook strict.* It checks staged A/M files matching + `\.(zig|ex|idr|eph|py|js|ts|rs|c|h|adoc|md)$` for *both* `SPDX-License-Identifier: + MPL-2.0` *and* the literal `Jonathan D.A. Jewell `. + `.a2ml`/`.toml`/`.yml`/`.txt`/deletions/renames are exempt. It also bars raw NIFs + and C files. +. *Stop before anything outward-facing.* Build and commit locally freely; STOP before + push / PR / merge and let the owner decide. +. *Scope discipline.* Do exactly the approved work-package. When you find more drift + (you will), flag it — don't sweep it. +. *Look before you delete or overwrite.* This bit twice already (a "paper stub" was a + full superseded paper; a "placeholder MAINTAINERS" was filled). If a target + contradicts how it was described, re-surface to the owner. Deletions are owner-gated, + per file. + +== Remaining work + +*WP-4 — load-bearing config (its own PR; re-verify after).* + +* Root `Justfile`: `project := "rsr-template-repo"` → `snifs` (*16 `{{project}}` + interpolation sites* — `just --list` + smoke recipes after); retarget help/tour/issues + URLs; fix the self-check (~line 337) + template-derivation message (~870). `REPO :=` + is defined but unused. +* Contractile `Mustfile`/`Trustfile`/`Intentfile`/`Adjustfile` + generated `Justfile`: + de-brand prose, and fix the two self-contradicting Mustfile checks — + `no-placeholder-values` over-matches just-syntax `{{recipe}}` (scope to `{{[A-Z_]+}}`), + and `template-readonly` greps a `RSR_TEMPLATE_DO_NOT_EDIT` marker that no longer exists + (remove/repurpose). *Fix the check, never the repo, to satisfy a stale gate.* + +*WP-5 — deletions + format (its own PR; per-file owner approval).* + +* `docs/QUICKSTART.adoc` (dup of the root `QUICKSTART-*.adoc` trio) → delete. +* `.machine_readable/ai/PLACEHOLDERS.adoc` (the init recipe says `rm` it) → delete. +* `docs/RSR_OUTLINE.adoc` (pure template doc) → delete or rewrite as a snifs outline. +* `READINESS.md` → `READINESS.adoc` (convert + fill `{{DATE}}` + snif→snifs). + +*Open decisions (get from owner before executing):* D-a (keep/remove bootstrap +tooling: `scripts/validate-template.sh`, `setup.sh`, self-validating `k9` examples), +D-c (Mustfile-check fix approach), D-d (confirm WP-5 deletions + RSR_OUTLINE +delete-vs-rewrite), D-e (`docs/decisions/0000-template.adoc` keep-vs-neutralize), +D-f (`docs/governance/` subtree numbering: normalize vs promote to root pillar). + +*Already deferred / flagged (don't silently absorb):* `docs/whitepapers/academic/snif.tex` +(two `\url{}` → `snif`; published DOI'd paper — owner action: fix + `just paper` rebuild + +re-deposit); the non-identity `{{PLACEHOLDER}}`s in `container/`/`security.txt`/`dep5` +(separate fill task); `llm-warmup-*.md` thin boilerplate (phantom `just setup`); +`.machine_readable/STATE.a2ml` stale overall. + +== Method that has worked + +. Cut every branch from *fresh `origin/main`* (`git fetch && git checkout -b + origin/main`) — local clones carry divergence; basing on a stale tip silently reverts + other work. +. One work-package = one small, disjoint PR. +. Read-only map → owner-approve → execute → adversarially verify → STOP before push. +. Verify deterministically before each commit: re-run every Mustfile `run:` check; + simulate the hook; phantom-recipe scan (`just ` in `just --list`); dangling-reference + scan; manifest parent-pointer resolution; `git verify-commit` each commit; confirm + `AFFIRMATION.adoc` SPDX unchanged. +. For substantive review, spin a short adversarial workflow (content-drift / + cross-reference / completeness) — it caught a botched README header a self-check missed. + +== Gotchas that will bite + +* *`snif` vs `snifs`:* repo name/URLs are `snifs`, but the crate prefix `snif-` and the + paper file `snif.pdf` are intentional — leave them. A blind sweep corrupts both; + `hyperpolymath/snif`→`snifs` turns an existing `…/snifs` into `…/snifss` (substring + trap) — collision-check first. +* *Recipes: `just --list` is the only truth.* Real: `build-wasm`, `assail`, + `container-build`/`-run`, `proof-check-all`, `abi-conformance`, `tour`, `doctor`, + `paper`. Phantom (never reference): `setup`, `setup-dev`, `heal`, `uninstall`, + `panic-scan`, `stapeln-export`/`-run`, `llm-context`. +* *DOC-FORMAT:* AsciiDoc primary; `.md` only for GitHub-required files (SECURITY, + CONTRIBUTING, CODE_OF_CONDUCT, CHANGELOG, copilot-instructions) and the standards root + pointers (TOPOLOGY, PROOF-NEEDS, PROOF-STATUS, TEST-NEEDS, llm-warmup-*). +* *AI-manifest convention:* a dir at depth N → `0.N-AI-MANIFEST.a2ml`, `level: N`, + `parent: ../0.{N-1}-AI-MANIFEST.a2ml` (root children use `../0-AI-MANIFEST.a2ml`). + `docs/governance/` violates this (D-f). +* *`Containerfile` must stay at repo root* — `dogfood-gate.yml` checks `[ -f + "Containerfile" ]` there. +* *`.github/settings.yml`* is the probot/settings sync source — a wrong `name:` can rename + the repo. +* *`dogfood-gate.yml`'s `rsr-template-repo` refs are legitimate* (point users to the real + template) — leave them. + +== Canonical facts + +* Owner literal: `Jonathan D.A. Jewell `. +* Citation: _SNIFs: Safer Native Implemented Functions for the BEAM via WebAssembly + Sandboxing_, Jewell, Jonathan D. A., 2026, DOI `10.5281/zenodo.19520245`, MPL-2.0. + Canonical record = root `CITATION.cff`. +* One-line purpose: _Safer NIFs: crash-isolated native interfaces for the BEAM via + WebAssembly sandboxing._