From cf516150eed4890470842c5915a4c20f13a9d981 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Sun, 26 Jul 2026 14:48:05 +0100 Subject: [PATCH 1/4] chore: estate-wide security compliance --- .github/workflows/ada.yml | 1 + .github/workflows/codeql.yml | 1 + .../generator-generic-ossf-slsa3-publish.yml | 1 + .github/workflows/governance.yml | 1 + .github/workflows/hypatia-scan.yml | 1 + .github/workflows/instant-sync.yml | 1 + .github/workflows/mirror.yml | 1 + .github/workflows/pages.yml | 1 + .github/workflows/push-email-notify.yml | 1 + .github/workflows/scorecard.yml | 1 + .github/workflows/secret-scanner.yml | 1 + .github/workflows/spark-theatre-gate.yml | 1 + .github/workflows/workflow-linter.yml | 1 + CONTRIBUTING.md | 116 ++++++++++++++++++ 14 files changed, 129 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/.github/workflows/ada.yml b/.github/workflows/ada.yml index a45ea75..709e036 100644 --- a/.github/workflows/ada.yml +++ b/.github/workflows/ada.yml @@ -8,6 +8,7 @@ on: branches: [ "main" ] permissions: read-all + actions: read jobs: build: diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml index 600983d..c1ce7d3 100644 --- a/.github/workflows/codeql.yml +++ b/.github/workflows/codeql.yml @@ -19,6 +19,7 @@ concurrency: permissions: read-all + actions: read jobs: analyze: diff --git a/.github/workflows/generator-generic-ossf-slsa3-publish.yml b/.github/workflows/generator-generic-ossf-slsa3-publish.yml index 8cc5dbd..c890be6 100644 --- a/.github/workflows/generator-generic-ossf-slsa3-publish.yml +++ b/.github/workflows/generator-generic-ossf-slsa3-publish.yml @@ -18,6 +18,7 @@ on: types: [created] permissions: read-all + actions: read jobs: build: diff --git a/.github/workflows/governance.yml b/.github/workflows/governance.yml index 794182a..be87a9b 100644 --- a/.github/workflows/governance.yml +++ b/.github/workflows/governance.yml @@ -21,6 +21,7 @@ concurrency: cancel-in-progress: true permissions: + actions: read contents: read jobs: diff --git a/.github/workflows/hypatia-scan.yml b/.github/workflows/hypatia-scan.yml index 2e7e939..013c95a 100644 --- a/.github/workflows/hypatia-scan.yml +++ b/.github/workflows/hypatia-scan.yml @@ -19,6 +19,7 @@ concurrency: cancel-in-progress: true permissions: + actions: read contents: read security-events: write pull-requests: write diff --git a/.github/workflows/instant-sync.yml b/.github/workflows/instant-sync.yml index 01646a7..4a11f86 100644 --- a/.github/workflows/instant-sync.yml +++ b/.github/workflows/instant-sync.yml @@ -9,6 +9,7 @@ on: types: [published] permissions: + actions: read contents: read jobs: diff --git a/.github/workflows/mirror.yml b/.github/workflows/mirror.yml index 81e9903..c25d3bc 100644 --- a/.github/workflows/mirror.yml +++ b/.github/workflows/mirror.yml @@ -7,6 +7,7 @@ on: workflow_dispatch: permissions: + actions: read contents: read jobs: diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml index def2d51..2cf079d 100644 --- a/.github/workflows/pages.yml +++ b/.github/workflows/pages.yml @@ -5,6 +5,7 @@ on: branches: [main, master] workflow_dispatch: permissions: + actions: read contents: read pages: write id-token: write diff --git a/.github/workflows/push-email-notify.yml b/.github/workflows/push-email-notify.yml index 2a95f5d..c08ea16 100644 --- a/.github/workflows/push-email-notify.yml +++ b/.github/workflows/push-email-notify.yml @@ -7,6 +7,7 @@ name: Push email notification on: push: {} permissions: + actions: read contents: read jobs: notify: diff --git a/.github/workflows/scorecard.yml b/.github/workflows/scorecard.yml index 2d9ea22..8afb3f3 100644 --- a/.github/workflows/scorecard.yml +++ b/.github/workflows/scorecard.yml @@ -9,6 +9,7 @@ on: branches: [main] permissions: read-all + actions: read jobs: analysis: diff --git a/.github/workflows/secret-scanner.yml b/.github/workflows/secret-scanner.yml index 9ed74ef..4c2ee4b 100644 --- a/.github/workflows/secret-scanner.yml +++ b/.github/workflows/secret-scanner.yml @@ -11,6 +11,7 @@ concurrency: cancel-in-progress: true permissions: + actions: read contents: read jobs: diff --git a/.github/workflows/spark-theatre-gate.yml b/.github/workflows/spark-theatre-gate.yml index a6030a9..651e420 100644 --- a/.github/workflows/spark-theatre-gate.yml +++ b/.github/workflows/spark-theatre-gate.yml @@ -11,6 +11,7 @@ on: branches: [main, master] permissions: + actions: read contents: read jobs: diff --git a/.github/workflows/workflow-linter.yml b/.github/workflows/workflow-linter.yml index 67b6a82..9ad08b3 100644 --- a/.github/workflows/workflow-linter.yml +++ b/.github/workflows/workflow-linter.yml @@ -11,6 +11,7 @@ on: - '.github/workflows/**' permissions: read-all + actions: read jobs: lint-workflows: diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..594b265 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,116 @@ +# Clone the repository +git clone https://github.com/hyperpolymath/squisher-corpus.git +cd squisher-corpus + +# Using Nix (recommended for reproducibility) +nix develop + +# Or using toolbox/distrobox +toolbox create squisher-corpus-dev +toolbox enter squisher-corpus-dev +# Install dependencies manually + +# Verify setup +just check # or: cargo check / mix compile / etc. +just test # Run test suite +``` + +### Repository Structure +``` +squisher-corpus/ +├── src/ # Source code (Perimeter 1-2) +├── lib/ # Library code (Perimeter 1-2) +├── extensions/ # Extensions (Perimeter 2) +├── plugins/ # Plugins (Perimeter 2) +├── tools/ # Tooling (Perimeter 2) +├── docs/ # Documentation (Perimeter 3) +│ ├── architecture/ # ADRs, specs (Perimeter 2) +│ └── proposals/ # RFCs (Perimeter 3) +├── examples/ # Examples (Perimeter 3) +├── spec/ # Spec tests (Perimeter 3) +├── tests/ # Test suite (Perimeter 2-3) +├── .well-known/ # Protocol files (Perimeter 1-3) +├── .github/ # GitHub config (Perimeter 1) +│ ├── ISSUE_TEMPLATE/ +│ └── workflows/ +├── CHANGELOG.md +├── CODE_OF_CONDUCT.md +├── CONTRIBUTING.md # This file +├── GOVERNANCE.md +├── LICENSE +├── MAINTAINERS.md +├── README.adoc +├── SECURITY.md +├── flake.nix # Nix flake (Perimeter 1) +└── Justfile # Task runner (Perimeter 1) +``` + +--- + +## How to Contribute + +### Reporting Bugs + +**Before reporting**: +1. Search existing issues +2. Check if it's already fixed in `main` +3. Determine which perimeter the bug affects + +**When reporting**: + +Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) and include: + +- Clear, descriptive title +- Environment details (OS, versions, toolchain) +- Steps to reproduce +- Expected vs actual behaviour +- Logs, screenshots, or minimal reproduction + +### Suggesting Features + +**Before suggesting**: +1. Check the [roadmap](ROADMAP.md) if available +2. Search existing issues and discussions +3. Consider which perimeter the feature belongs to + +**When suggesting**: + +Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) and include: + +- Problem statement (what pain point does this solve?) +- Proposed solution +- Alternatives considered +- Which perimeter this affects + +### Your First Contribution + +Look for issues labelled: + +- [`good first issue`](https://github.com/hyperpolymath/squisher-corpus/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://github.com/hyperpolymath/squisher-corpus/labels/help%20wanted) — Community help needed +- [`documentation`](https://github.com/hyperpolymath/squisher-corpus/labels/documentation) — Docs improvements +- [`perimeter-3`](https://github.com/hyperpolymath/squisher-corpus/labels/perimeter-3) — Community sandbox scope + +--- + +## Development Workflow + +### Branch Naming +``` +docs/short-description # Documentation (P3) +test/what-added # Test additions (P3) +feat/short-description # New features (P2) +fix/issue-number-description # Bug fixes (P2) +refactor/what-changed # Code improvements (P2) +security/what-fixed # Security fixes (P1-2) +``` + +### Commit Messages + +We follow [Conventional Commits](https://www.conventionalcommits.org/): +``` +(): + +[optional body] + +[optional footer] From 57d7f424439471b3af8d46645c21d9c4e7911ac3 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Sun, 26 Jul 2026 15:10:11 +0100 Subject: [PATCH 2/4] chore: remove duplicate GOVERNANCE files, keep GOVERNANCE.md --- GOVERNANCE.adoc | 162 ------------------------------------------------ 1 file changed, 162 deletions(-) delete mode 100644 GOVERNANCE.adoc diff --git a/GOVERNANCE.adoc b/GOVERNANCE.adoc deleted file mode 100644 index e41020d..0000000 --- a/GOVERNANCE.adoc +++ /dev/null @@ -1,162 +0,0 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell -= Governance Model -:toc: preamble - -This document describes the governance model for this repository. - -== Overview - -This repository follows a **Sole Maintainer Governance Model**: - -* Single maintainer (@hyperpolymath) has full authority over the project -* All contributions are welcome and reviewed by the maintainer -* Decisions are made transparently through GitHub issues and discussions -* The project adheres to the hyperpolymath estate policies where applicable - -== Core Principles - -[cols="1,2"] -|=== -| Principle | Description - -| **Benevolent Dictatorship** | Maintainer has final decision authority but seeks community input - -| **Meritocracy** | Contributions are judged on technical merit, not contributor identity - -| **Transparency** | All significant decisions are documented publicly - -| **Consensus-Seeking** | Maintainer prefers consensus but will decide when necessary - -| **Open Contribution** | Anyone can contribute via fork and pull request - -|=== - -== Roles and Permissions - -[cols="1,2,2"] -|=== -| Role | Permissions | Assignment - -| **Maintainer** | Write access, merge rights, admin | @hyperpolymath -| **Contributors** | Read access, fork, submit PRs | All GitHub users -| **Users** | Use the software, report issues | All GitHub users - -|=== - -== Decision Making Framework - -=== Routine Decisions - -* Bug fixes -* Documentation improvements -* Minor feature additions -* Dependency updates - -**Process**: Maintainer reviews and merges PRs that meet quality standards. - -=== Significant Changes - -* New major features -* API changes -* Architecture modifications -* Breaking changes - -**Process**: -. Open issue describing the change -. Discuss with community (minimum 72 hours) -. Maintainer makes final decision -. Document rationale in issue/PR - -=== Structural Decisions - -* Repository purpose/renaming -* License changes -* Ownership transfer -* Deprecation/archival - -**Process**: -. Extended discussion (minimum 1 week) -. Maintainer makes final decision -. Document in CHANGELOG and governance docs - -== Contribution Lifecycle - -[cols="1,2"] -|=== -| Stage | Process - -| **Ideation** | Open issue, discuss feasibility - -| **Development** | Fork, implement, test thoroughly - -| **Review** | Submit PR, maintainer reviews within 7 days - -| **Merge** | Maintainer merges or requests changes - -| **Release** | Maintainer publishes according to project conventions - -|=== - -== Conflict Resolution - -In case of disagreements: - -. Discuss in the relevant GitHub issue or PR -. Provide technical justification for positions -. Maintainer mediates and makes final decision -. Decision is documented and can be revisited later - -== Project Policies - -This repository adheres to hyperpolymath estate-wide policies: - -* **License**: MPL-2.0 for code, CC-BY-SA-4.0 for prose (per standards/LICENCE-POLICY.adoc) -* **Code of Conduct**: Follows hyperpolymath CODE_OF_CONDUCT.md -* **Security**: Follows hyperpolymath SECURITY.md -* **Contributing**: Follows hyperpolymath CONTRIBUTING.adoc conventions - -== Repository-Specific Conventions - -[cols="1,2"] -|=== -| Convention | Description - -| **Signing** | All commits must be signed (SSH or GPG) - -| **SPDX Headers** | All source files must have SPDX license identifiers - -| **Contractiles** | Mustfile, Trustfile, Intendfile, Adjustfile in root - -| **Machine Readable** | META.a2ml in .machine_readable/6a2/ - -| **CI/CD** | GitHub Actions workflows in .github/workflows/ - -|=== - -== Governance Evolution - -As the project grows, this governance model may evolve: - -* **Adding Co-Maintainers**: When contribution volume warrants it -* **Forming a Team**: For complex multi-maintainer projects -* **Adopting TPCF**: For large, multi-repository projects (see rhodium-standard-repositories) - -Changes to this document require the same process as Significant Changes above. - -== See Also - -* link:MAINTAINERS.adoc[Maintainers] -* link:CODE_OF_CONDUCT.md[Code of Conduct] -* link:CONTRIBUTING.adoc[Contributing Guide] -* link:https://github.com/hyperpolymath/standards/blob/main/LICENCE-POLICY.adoc[Estate License Policy] -* link:https://github.com/hyperpolymath/standards[rhodium-standard-repositories (TPCF)] - -== Changelog - -[cols="1,1,1"] -|=== -| Date | Change | By - -| 2026-06-07 | Initial governance model established | @hyperpolymath -|=== From 8106e3955febd3f57451f38ac1a32a669a2d9acb Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Sun, 26 Jul 2026 15:44:12 +0100 Subject: [PATCH 3/4] fix: update CodeQL actions to SHA-pinned v3 (29b1f65c) --- .github/workflows/codeql.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml index c1ce7d3..4f25ca2 100644 --- a/.github/workflows/codeql.yml +++ b/.github/workflows/codeql.yml @@ -46,12 +46,12 @@ jobs: uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - name: Initialize CodeQL - uses: github/codeql-action/init@e4fba868fa4b1b91e1fdab776edc8cfbe6e9fb81 # v3.28.1 + uses: github/codeql-action/init@29b1f65c1f735799893313399435a59f54045865 # v3 with: languages: ${{ matrix.language }} build-mode: ${{ matrix.build-mode }} - name: Perform CodeQL Analysis - uses: github/codeql-action/analyze@e4fba868fa4b1b91e1fdab776edc8cfbe6e9fb81 # v3.28.1 + uses: github/codeql-action/analyze@29b1f65c1f735799893313399435a59f54045865 # v3 with: category: "/language:${{ matrix.language }}" From 1050ed8b7d6a89e8e9c66ac0a2833481aff6587c Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Mon, 27 Jul 2026 19:07:36 +0100 Subject: [PATCH 4/4] fix(ci): repoint codeql-action at a SHA that exists github/codeql-action@29b1f65c1f735799893313399435a59f54045865 is pinned here but exists in no repository -- the GitHub API returns 422 for it. CodeQL therefore could not start: the run graph fails to build and the job reports startup_failure, so this repository has had no CodeQL scanning at all. Repointed at 4187e74d05793876e9989daffde9c3e66b4acd07, which is what the v3 tag currently resolves to (v3.37.3), verified against the API. Found while auditing the estate: the same non-existent SHA is pinned in over 100 repositories, so CodeQL is dead across nearly all of them. Co-Authored-By: Claude Opus 5 Signed-off-by: Jonathan D.A. Jewell <6759885+hyperpolymath@users.noreply.github.com> --- .github/workflows/codeql.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml index 4f25ca2..a1d28bd 100644 --- a/.github/workflows/codeql.yml +++ b/.github/workflows/codeql.yml @@ -46,12 +46,12 @@ jobs: uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - name: Initialize CodeQL - uses: github/codeql-action/init@29b1f65c1f735799893313399435a59f54045865 # v3 + uses: github/codeql-action/init@4187e74d05793876e9989daffde9c3e66b4acd07 # v3 with: languages: ${{ matrix.language }} build-mode: ${{ matrix.build-mode }} - name: Perform CodeQL Analysis - uses: github/codeql-action/analyze@29b1f65c1f735799893313399435a59f54045865 # v3 + uses: github/codeql-action/analyze@4187e74d05793876e9989daffde9c3e66b4acd07 # v3 with: category: "/language:${{ matrix.language }}"