Skip to content

Repo tidy: de-template, de-dupe, format-conform (snifs)#42

Merged
hyperpolymath merged 11 commits into
mainfrom
chore/repo-tidy-2026-06-16
Jun 16, 2026
Merged

Repo tidy: de-template, de-dupe, format-conform (snifs)#42
hyperpolymath merged 11 commits into
mainfrom
chore/repo-tidy-2026-06-16

Conversation

@hyperpolymath

Copy link
Copy Markdown
Owner

Comprehensive repo tidy-up: lean root, no duplicates, AsciiDoc-primary format, and conformance to the estate rsr-/standards conventions. Read-only mapping → owner-approved tiers → executed → adversarially verified. 11 signed commits.

What changed

Tier A — hygiene

  • Ignore Agda/Zig/bench/priv build artifacts (.gitignore).
  • Track the bag-of-actions owned-compute gate manifest (ci-checks.exs).

Tier B — manifests + authoring standard

  • Add nested AI manifests to benches/, demo/, rust/, rust-guest/, zig/, docs/templates/.
  • Bring README.adoc / EXPLAINME.adoc to the authoring standard (TOC/icons, Documentation index, Dogfooded + Known-gaps sections).

Tier C — de-template + format

  • De-template the root 0-AI-MANIFEST.a2ml, the three QUICKSTART-*.adoc (rewritten around snifs's real flows, using only recipes that exist), and the load-bearing contractiles README.adoc.
  • Convert proof-debt / tech-debt-2026-05-26 / session/README from .md.adoc; relocate the invariant-scan output into verification/.

Tier D — de-dupe + archive

  • Remove five .github/ community-health files that were unbootstrapped RSR templates (literal TEMPLATE INSTRUCTIONS, {{PLACEHOLDER}}s, wrong snif slug) — GitHub's .github > root precedence meant it was serving that cruft publicly; deletion falls back to the clean, filled root copies (and removes a placeholder offender from the OpenSSF gate).
  • Remove the placeholder docs/attribution/CITATION.cff and the duplicate docs/attribution/MAINTAINERS.adoc.
  • Archive the point-in-time TEMPLATE-STANDARDS-AUDIT.adoc and the superseded docs/papers/snifs.tex (a full but stale-numbered earlier paper draft) into docs/archive/.

Verification follow-ups

  • Fixed a botched README.adoc header (duplicate attributes, stray author line, wrong/orphan Zenodo DOI), six→five crash-mode counts, the bench working dir, and a dangling .claude/CLAUDE.md reference.
  • Removed the residual PMPL-1.0 licence badge that contradicted MPL-2.0 (owner-authorized; no LICENSE/SPDX changed).
  • De-templated the machine-readable identity strings to snifs (CLADE.a2ml, ECOSYSTEM.a2ml ×2, AI.a2ml, ANCHOR.a2ml, stapeln/selur-compose/eclexiaiser/cliff configs).

Verification

Adversarial 3-reviewer pass (content-drift / cross-reference / completeness, 26 findings) + a deterministic sweep. All blockers/highs in touched files are resolved. Green: Mustfile presence checks, pre-commit hook (SPDX + owner on every changed .adoc/.md), no phantom recipes, no dangling refs, all manifests added are correct, all commits signed, AFFIRMATION dual-SPDX untouched, OpenSSF gate.

Deferred to a follow-up plan (intentionally NOT in this PR)

  • CLADE prefixed-name + [clade] block (needs the real gv-clade-index entry).
  • Load-bearing root Justfile (project :=) and contractile Mustfile/Trustfile/Intentfile/Adjustfile gate logic.
  • Template-doc removals (docs/RSR_OUTLINE.adoc, docs/QUICKSTART.adoc, .machine_readable/ai/PLACEHOLDERS.adoc) — owner-gated deletions.
  • READINESS.md.adoc conversion.
  • 5 pre-existing manifest-parent defects (container/, examples/, .github/, verification/tests/ missing parent; docs/governance/ wrong parent).

🤖 Generated with Claude Code

hyperpolymath and others added 11 commits June 16, 2026 18:12
Stops six untracked build outputs from cluttering the tree: Agda .agdai
interface files, benches/eval_tmp + eval_results.json, demo guest wasm,
priv/snif_eval.json, and zig/buffer_abi_build. All are regenerated by the
proof/bench/build recipes.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…ifest)

The manifest the bag-of-actions `mix bag.report` dispatcher runs to execute the
snifs proof + ABI gates on an owned nix-capable node and post each verdict back
as a GitHub commit status (snifs-proofs -> 'bag / Formal proofs (owned compute)',
snifs-abi -> 'bag / ABI conformance (owned compute)'). Both Justfile recipes it
names (proof-check-all, abi-conformance) exist. Pairs with bag-of-actions PR #7.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…est/zig/docs-templates

Closes the manifest-hierarchy gap: every substantive top-level source dir now
declares its scope and invariants via a nested 0.N-AI-MANIFEST.a2ml, matching the
estate convention already followed by docs/, src/, features/, container/, examples/.
docs/templates notes that the load-bearing contractiles live under
.machine_readable/contractiles/ (this is the template copy).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
README: add the required :toc: preamble + :icons: font header attributes and a
Documentation section linking EXPLAINME/PROOF-STATUS/CONTRIBUTING/SECURITY/CHANGELOG/paper.
EXPLAINME: add the two required sections it lacked — a Dogfooded-Across-The-Account
table (Idris2 ABI proofs, Zig wasm32 guests, --safe Agda; cross-referenced to
bag-of-actions/proven/gossamer/echo-types) and an honest Known-gaps section
(SEC-1 TCB boundary, ABI 15/20, dual-sourced Rust guest).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The root 0-AI-MANIFEST.a2ml and the three QUICKSTART-*.adoc files still
carried RSR-template placeholders (rsr-template-repo, {{LANG_STACK}},
{{BUILD_CMD}}, and phantom recipes like `just setup`/`heal`/`panic-scan`/
`stapeln-*`). Replace with snifs-specific content using only recipes that
actually exist (verified against `just --list`): build-wasm, assail,
container-build, proof-check-all, abi-conformance, etc. Reframe the three
role quickstarts around snifs's real flows (run the demo / contribute /
cut a release) and drop the inapplicable app install/uninstall/heal/
multi-tenant scaffolding.

Fix the load-bearing .machine_readable/contractiles/README.adoc stale
names (Trustfile.hs, lust/Intentfile) to the files actually present
(Trustfile.a2ml, Adjustfile.a2ml, Intentfile.a2ml, bust/, dust/) and drop
the "copy into a new repo" framing — this is the real load-bearing
instance, not the template (that lives in docs/templates/contractiles/).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…te invariants scan

Estate DOC-FORMAT rule + the docs/ pillar manifest both require AsciiDoc as
the primary documentation format ("if .adoc exists, don't also have .md").
Convert three lingering .md docs to .adoc:

  docs/proof-debt.md            -> docs/proof-debt.adoc
  docs/tech-debt-2026-05-26.md  -> docs/tech-debt-2026-05-26.adoc
  session/README.md             -> session/README.adoc

Markdown -> AsciiDoc (headings, lists, tables, listing blocks, links) and the
SPDX comment delimiter <!-- --> -> //. The new .adoc files carry the full
owner SPDX + literal owner string the pre-commit hook requires (the source
.md SPDX-FileCopyrightText used the "(hyperpolymath)" form, not the
<…@open.ac.uk> form the hook greps for). Fix the one inbound reference
(tech-debt -> proof-debt) to the new .adoc path.

Relocate the tracked README.adoc.invariants.md (an Invariant-Path scan
output) out of the repo root into verification/, where verification tooling
output belongs. No content change; zero inbound references.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…der CITATION, archive audit

GitHub community-health precedence is .github/ > root > docs/. The .github/
copies of CODE_OF_CONDUCT.md, CONTRIBUTING.md, and SECURITY.md were never
bootstrapped — they still carry literal "TEMPLATE INSTRUCTIONS (delete this
block before publishing)" blocks, unfilled {{PROJECT_NAME}}/{{SECURITY_EMAIL}}/
{{AUTHOR}} placeholders, and the wrong repo slug (`snif`, not `snifs`). Because
of the precedence rule, GitHub has been serving that placeholder cruft publicly
and shadowing the clean, filled root copies. Remove the five .github community-
health files so GitHub falls back to the root copies:

  .github/CODE_OF_CONDUCT.md  (root CODE_OF_CONDUCT.md is the filled Contributor Covenant)
  .github/CONTRIBUTING.md     (root CONTRIBUTING.md is filled)
  .github/SECURITY.md         (root SECURITY.md is filled)
  .github/GOVERNANCE.md       (dupe of root GOVERNANCE.adoc)
  .github/MAINTAINERS         (unfilled {{AUTHOR}} placeholder; root MAINTAINERS.adoc is filled)

.github/CODEOWNERS is kept (the Mustfile requires it).

Also remove docs/attribution/CITATION.cff — an unfilled placeholder
({{AUTHOR_LAST}}/{{PROJECT_NAME}}, slug `snif`) that duplicates the filled,
canonical root CITATION.cff (real DOI 10.5281/zenodo.19520245).

Archive the point-in-time TEMPLATE-STANDARDS-AUDIT.adoc (v1.0, 2026-04-07) out
of the repo root into docs/archive/ with a level-2 manifest marking the
directory as frozen, append-only history. No inbound references.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
docs/papers/snifs.tex is a complete but SUPERSEDED paper draft: the canonical
paper is the richer docs/whitepapers/academic/snif.tex (+ snif.pdf), and this
earlier draft carries stale figures (it claims 11/11 tests and 7 proofs; the
repo is now at 21/21 in-BEAM tests and 10 machine-checked proofs). Per owner
decision, archive it for provenance rather than delete: git mv into docs/archive/
(recorded in the frozen-history manifest) and remove the now-empty, undeclared
docs/papers/ directory.

Remove docs/attribution/MAINTAINERS.adoc — a filled but redundant second copy of
the canonical root MAINTAINERS.adoc (which the Mustfile requires at root). One
maintainers file, no drift surface.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Adversarial verification of the tidy caught defects in files this branch
already touched:

README.adoc — the Tier-B "authoring standard" edit left a botched, duplicated
document header: a second :toc:/:source-highlighter: attribute block sitting
AFTER body content (so it was inert and rendered as stray text), a stray
mid-body author line, and an orphan bare DOI URL citing the WRONG Zenodo record
(19680824 vs the canonical 19520245 used by the badge, the Citation block, and
CITATION.cff). Collapse to a single clean header: attributes before any body,
all badges grouped, one correct DOI.

Factual fixes (verified against zig/src/safe_nif.zig, which has 8 exports of
which FIVE are crash_*): "six crash modes" -> "five" in README repo-layout and
QUICKSTART-DEV project-structure. Make the benchmark command's working directory
explicit (run from demo/). Drop the dangling `.claude/CLAUDE.md` reference in
QUICKSTART-DEV (no such file in this repo) and the inaccurate "signing-key
policy" pointer (CONTRIBUTING.md documents the contribution flow, not keys).

NOT touched: the residual PMPL-1.0 license badge in README is left verbatim for
manual owner review (licence markup is owner-only; flagged, not auto-edited).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The README carried a leftover RSR-template badge declaring
"license-PMPL--1.0--or--later", contradicting the repo's actual MPL-2.0
licence (asserted by the SPDX header, the MPL-2.0 badge, and the License
section) and violating the estate rule that PMPL appears only in
palimpsest-license / palimpsest-plasma / consent-aware-http. Owner
explicitly authorized removing this badge this occasion. No LICENSE file
or SPDX-License-Identifier is changed; only the incorrect badge markup is
deleted (the correct MPL-2.0 badge already exists).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…fs (safe subset)

Verification found the machine-readable identity/config layer still declared
the repo as "rsr-template-repo" or "snif" while the human-facing surface was
already de-templated. Per owner decision, fix the SAFE, non-load-bearing
identity strings now and defer the load-bearing + identity-sensitive parts to
a plan:

  .machine_readable/CLADE.a2ml           canonical-name + forge URLs + lineage -> snifs
  .machine_readable/ECOSYSTEM.a2ml       name snif -> snifs; fill {{REPO_DESCRIPTION}}
  .machine_readable/6a2/ECOSYSTEM.a2ml   name rsr-template-repo -> snifs; fill purpose
  .machine_readable/ai/AI.a2ml           rsr-template-repo -> snifs
  .machine_readable/6a2/anchor/ANCHOR.a2ml  fill identity block (project/kind/one-sentence/
                                            domain), repo hyperpolymath/snif -> snifs,
                                            copyright + date placeholders
  stapeln.toml / selur-compose.toml / eclexiaiser.toml   name -> snifs
  .machine_readable/configs/git-cliff/cliff.toml         remote URLs snif -> snifs; copyright

DEFERRED to a follow-up plan (NOT touched here): CLADE prefixed-name + [clade]
block (needs the real gv-clade-index entry), the load-bearing root Justfile
(project :=) and contractile Mustfile/Trustfile/Intentfile/Adjustfile gate
logic, all template-doc deletions (RSR_OUTLINE/QUICKSTART/PLACEHOLDERS), the
READINESS.md format conversion, and the 5 pre-existing manifest-parent defects.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@github-actions

Copy link
Copy Markdown

🔍 Hypatia Security Scan

Findings: 53 issues detected

Severity Count
🔴 Critical 5
🟠 High 23
🟡 Medium 25

⚠️ Action Required: Critical security issues found!

View findings
[
  {
    "reason": "Action actions/checkout@v4 needs attention",
    "type": "unpinned_action",
    "file": "rust-guest-verify.yml",
    "action": "pin_sha",
    "rule_module": "workflow_audit",
    "severity": "medium"
  },
  {
    "reason": "Issue in rust-guest-verify.yml",
    "type": "missing_timeout_minutes",
    "file": "rust-guest-verify.yml",
    "action": "flag",
    "rule_module": "workflow_audit",
    "severity": "medium"
  },
  {
    "reason": "Issue in scorecard-enforcer.yml",
    "type": "scorecard_publish_with_run_step",
    "file": "scorecard-enforcer.yml",
    "action": "split_scorecard_publish_job",
    "rule_module": "workflow_audit",
    "severity": "high"
  },
  {
    "reason": "Issue in instant-sync.yml",
    "type": "secret_action_without_presence_gate",
    "file": "instant-sync.yml",
    "action": "peter-evans/repository-dispatch",
    "rule_module": "workflow_audit",
    "severity": "high"
  },
  {
    "reason": "Issue in scorecard.yml",
    "type": "scorecard_wrapper_missing_job_permissions",
    "file": "scorecard.yml",
    "action": "flag",
    "rule_module": "workflow_audit",
    "severity": "high"
  },
  {
    "reason": "Issue in codeql.yml",
    "type": "codeql_missing_actions_language",
    "file": "codeql.yml",
    "action": "flag",
    "rule_module": "workflow_audit",
    "severity": "medium"
  },
  {
    "reason": "Python file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/snifs/snifs/benches/assert_safer.py",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "Python file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/snifs/snifs/verification/tools/abi_conformance.py",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "unsafe block -- requires SAFETY comment (4 occurrences, CWE-676)",
    "type": "unsafe_block",
    "file": "/home/runner/work/snifs/snifs/rust/crates/snif-abi/src/lib.rs",
    "action": "flag",
    "rule_module": "code_safety",
    "severity": "medium"
  },
  {
    "reason": "unsafe block -- requires SAFETY comment (1 occurrences, CWE-676)",
    "type": "unsafe_block",
    "file": "/home/runner/work/snifs/snifs/rust/crates/demo-guest/src/lib.rs",
    "action": "flag",
    "rule_module": "code_safety",
    "severity": "medium"
  }
]

Powered by Hypatia Neurosymbolic CI/CD Intelligence

@hyperpolymath hyperpolymath merged commit a798f2c into main Jun 16, 2026
14 of 17 checks passed
@hyperpolymath hyperpolymath deleted the chore/repo-tidy-2026-06-16 branch June 16, 2026 18:37
hyperpolymath added a commit that referenced this pull request Jun 16, 2026
… pointer

Five nested AI-manifests had parent pointers that did not resolve (caught by
the PR #42 tidy's manifest-integrity audit, but pre-existing and out of that
PR's scope):

  examples/0.1-AI-MANIFEST.a2ml            one-line stub -> add META + AI_MANIFEST
  .github/0.1-AI-MANIFEST.a2ml             one-line stub -> add META + AI_MANIFEST
  verification/tests/0.2-AI-MANIFEST.a2ml  one-line stub -> add META (level 2)
  container/0.1-AI-MANIFEST.a2ml           full body, no level/parent -> add them
  docs/governance/0.1-AI-MANIFEST.a2ml     parent pointed at non-existent
                                           ../0-AI-MANIFEST.a2ml -> repoint to the
                                           docs pillar ../0.1-AI-MANIFEST.a2ml

Every manifest parent pointer in the repo now resolves.

NOTE (flagged, not fixed here): the docs/governance/ subtree uses an off-by-one
numbering — it calls itself a top-level "governance-pillar" (level 1) while
sitting under docs/, and its children are numbered relative to it. Normalizing
that subtree (or promoting governance to a repo-root pillar) is a separate
structural decision; this commit only makes the dangling pointer resolve.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
hyperpolymath added a commit that referenced this pull request Jun 16, 2026
**Phase-2 WP-2** — repository-identity reconciliation (`snif`-singular /
`rsr-template-repo` → `snifs`). Cut from fresh `origin/main`; disjoint
from #42, #43.

20 files: `.github/settings.yml` (name/homepage — the probot/settings
sync source), the 6 `.github/ISSUE_TEMPLATE/*` + `SUPPORT`,
`.well-known/security.txt`, `container/manifest.toml` + `Containerfile`,
`STATE.a2ml`/`META.a2ml`/`groove.a2ml`/`compliance/reuse/dep5`,
`TEST-NEEDS.md` + `llm-warmup-{dev,user}.md` titles, a filled
`docs/attribution/CITATIONS.adoc` (from `CITATION.cff`), and filled
copyright placeholders in `copilot-instructions.md`.

**Preserved deliberately:** the `snif-` crate prefix and `snif.pdf`
filename, the methodology-guard reject-patterns, and
`dogfood-gate.yml`'s legitimate pointers to the real
`rsr-template-repo`.

**Deferred / flagged (not here):**
- `docs/whitepapers/academic/snif.tex` — two `\url{}` point at
`hyperpolymath/snif`; it's the published, DOI'd paper, so the URL fix +
PDF rebuild + re-deposit is a deliberate owner action.
- Other `{{PLACEHOLDER}}` tokens in the `container/` / `security.txt` /
`dep5` templates (`SERVICE_NAME`, `PORT`, `SECURITY_EMAIL`, …) — a
separate fill task, not identity.
- D-a-gated bootstrap tooling (`scripts/validate-template.sh`,
`setup.sh`, the self-validating `k9` examples) — awaits the
keep-or-remove decision.
- `llm-warmup-*.md` are thin boilerplate (reference the phantom `just
setup`) — name fixed; content refresh is separate.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant