diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 00000000..3a3b7f20 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,34 @@ +# SPDX-License-Identifier: MPL-2.0 +# CODEOWNERS - Define code review assignments for GitHub +# See: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners + +# Default: sole maintainer for all files +* @hyperpolymath + +# Security-sensitive files require explicit ownership +SECURITY.md @hyperpolymath +.github/workflows/ @hyperpolymath +.machine_readable/ @hyperpolymath +contractiles/ @hyperpolymath + +# License files +LICENSE @hyperpolymath +LICENSES/ @hyperpolymath + +# Configuration +.gitignore @hyperpolymath +.github/ @hyperpolymath + +# Documentation +README* @hyperpolymath +CONTRIBUTING* @hyperpolymath +CODE_OF_CONDUCT* @hyperpolymath +GOVERNANCE* @hyperpolymath +MAINTAINERS* @hyperpolymath +CHANGELOG* @hyperpolymath +ROADMAP* @hyperpolymath + +# Build and CI +Justfile @hyperpolymath +Makefile @hyperpolymath +*.sh @hyperpolymath diff --git a/.github/ISSUES/2026-06-05-cicd-optimization-roadmap.md b/.github/ISSUES/2026-06-05-cicd-optimization-roadmap.md new file mode 100644 index 00000000..bcaf4af4 --- /dev/null +++ b/.github/ISSUES/2026-06-05-cicd-optimization-roadmap.md @@ -0,0 +1,265 @@ +// SPDX-License-Identifier: MPL-2.0 +// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell + +# CICD Optimization Roadmap — Ultra-Zotta-Plan + +**Date:** 2026-06-05 +**Status:** DRAFT +**Owner:** estate-wide +**Priority:** CRITICAL (cost + velocity blocker) + +--- + +## Executive Summary + +The estate currently runs **~281 secret-scanner deployments** + **redundant build workflows** across 1,191+ repos. Analysis of `verisimdb#114` reveals **duplicate job names** (`bench-compile`, `audit`) across `rust-ci.yml`, `elixir-ci.yml`, and `build-validation.yml`, causing CI queuing delays and unnecessary minute consumption. + +**Estimated waste:** ~30-40% of CI minutes from redundancy + path-filter misses. + +--- + +## Track 1: Immediate Redundancy Elimination (Week 1) + +### 1.1 Remove trufflehog from secret-scanner ✅ **DONE** +- **File:** `standards/.github/workflows/secret-scanner-reusable.yml` +- **Change:** Deleted `trufflehog:` job (13s saved per run × 1,191 repos) +- **Impact:** ~5,000+ minutes/month saved + +### 1.2 Consolidate build workflows in verisimdb +- **Problem:** `build-validation.yml` + `rust-ci.yml` + `elixir-ci.yml` = duplicate `bench-compile` + `audit` jobs +- **Action:** + - Merge `build-validation.yml` into `rust-ci.yml` and `elixir-ci.yml` with path filters + - OR: Delete `build-validation.yml`, rely on full CI workflows + - **Estimated savings:** ~2-3 minutes per PR + +### 1.3 Rust-secrets waste elimination +- **Problem:** 300+ repos run `rust-secrets` but have NO `Cargo.toml` (aspasia, bgp-backbone-lab, branch-newspaper, etc.) +- **Action:** Add path filter to rust-secrets job: + ```yaml + rust-secrets: + if: contains(github.event.pull_request.changed_files, 'Cargo.toml') || contains(github.event.pull_request.changed_files, '**.rs') + # or: if: hashFiles('Cargo.toml') != '' + ``` +- **Estimated savings:** ~300 repos × 3s = 900s per estate-wide push + +### 1.4 Estate-wide workflow audit +| Workflow | Purpose | Redundant? | Action | +|----------|---------|------------|--------| +| `build-validation.yml` | Quick build check | YES (rust-ci + elixir-ci cover it) | DELETE or merge | +| `rust-ci.yml` | Full Rust CI | NO | Keep, add path filters | +| `elixir-ci.yml` | Full Elixir CI | NO | Keep, add path filters | +| `secret-scanner.yml` | Secret detection | NO (but had trufflehog+gitleaks overlap) | ✅ Fixed | +| `codeql.yml` | Security analysis | NO | Keep, schedule weekly | +| `scorecard.yml` | Supply chain | NO | Keep, schedule weekly | +| `hypatia-scan.yml` | Neurosymbolic | NO | Keep, schedule weekly | + +--- + +## Track 2: Workflow Naming + Clarity (Week 1-2) + +### 2.1 Standardize naming convention +**Current chaos:** +- `rust-ci.yml` vs `elixir-ci.yml` vs `build-validation.yml` (inconsistent) +- `secret-scanner.yml` vs `security-scan.yml` (overlap) +- `scorecard.yml` vs `scorecard-enforcer.yml` (unclear difference) + +**Proposed standard:** +``` +-.yml + OR +-.yml + +Examples: +- rust-build-test.yml +- elixir-build-test.yml +- security-secret-scan.yml +- security-codeql.yml +- security-scorecard.yml +- governance-license.yml +- governance-workflow-linter.yml +``` + +### 2.2 Add descriptive metadata +Every workflow should have: +```yaml +# SPDX-License-Identifier: MPL-2.0 +name: Rust — Build + Test + Lint +# Purpose: Validates Rust code compiles, passes tests, clippy lint +# Owner: @hyperpolymath +# Schedule: On push/PR (path-filtered to Rust files) +# Timeout: 30m total +# Est. Cost: 5-8 minutes per run +``` + +--- + +## Track 3: Path Filter Optimization (Week 2) + +### 3.1 Language-specific filtering +```yaml +# rust-ci.yml +on: + push: + paths: + - '**.rs' + - 'Cargo.toml' + - 'Cargo.lock' + - 'rust-toolchain' + - '.github/workflows/rust-ci.yml' + pull_request: + paths: + - '**.rs' + - 'Cargo.toml' + - 'Cargo.lock' +``` + +### 3.2 Docs-only PR fast path +```yaml +# For workflows that don't need docs changes: +if: > + contains(github.event.pull_request.changed_files, '.md') == false && + contains(github.event.pull_request.changed_files, '.adoc') == false +``` + +--- + +## Track 4: Test + Bench Standards (Week 2-3) + +### 4.1 Audit existing test standards +- **Location:** `standards/.github/workflows/` + `standards/templates/` +- **Check:** + - Are test workflows applied estate-wide? + - Are there contradictions between repos? + - Are panic-attack tests integrated? + - Are benchmarks proven/safe? + +### 4.2 Panic-Attack integration +- **Current:** `panic-attack` workflow exists but may not be in all repos +- **Action:** Add to all repos that have Rust code +- **Patterns to detect:** + - Unsafe blocks + - Unwraps/expects + - Integer overflows + - Race conditions + +### 4.3 Proven Tests Repo (Idris2) +**New repo:** `proven-tests-and-benches` + +**Purpose:** Formal guarantees for test correctness using Idris2 + +**Coverage targets:** +- Echo-type safety tests +- Identity/projection/invariance traversal +- Set concepts +- Interdimensional transfer +- Higher-order constructs + +**Properties to prove:** +```idris +-- Tests are valid +TestValid : (t : Test) -> Type +TestValid t = ... + +-- Tests are sound (catch what they claim) +TestSound : (t : Test) -> Prop +TestSound t = ... + +-- Tests are tamper-proof +TestTamperProof : (t : Test) -> Prop +TestTamperProof t = ... + +-- Tests are unpanickable +TestUnpanickable : (t : Test) -> Prop +TestUnpanickable t = ... +``` + +--- + +## Track 5: Acceleration Opportunities (Week 3-4) + +### 5.1 Self-hosted runners for heavy work +- **Targets:** fuzzing, E2E, Hypatia scans +- **Estimated savings:** 80-90% for targeted workflows +- **Security:** Rootless Podman containers + +### 5.2 Caching optimization +- **Current:** Some repos use `Swatinem/rust-cache`, others don't +- **Action:** Standardize caching across all language workflows +- **Targets:** + - Rust: `cargo` cache + `target/` directory + - Elixir: `deps/` + `_build/` + - Node: `node_modules/` + - Go: `go.mod` hash-based + +### 5.3 Matrix strategy optimization +- **Problem:** Many workflows test every combination (Rust nightly/stable/beta × OS) +- **Action:** Reduce matrix for PRs, full matrix for nightly/main + +--- + +## Track 6: Estate-Wide Workflow Inventory (Week 1) + +### 6.1 Generate current inventory +```bash +# List all unique workflow files +find . -path "*/.github/workflows/*.yml" -type f | sort | uniq + +# Count per workflow name +find . -path "*/.github/workflows/*.yml" -type f | xargs -I {} basename {} | sort | uniq -c | sort -rn + +# Identify duplicates (same name, different content) +find . -path "*/.github/workflows/*.yml" -type f -exec sha256sum {} \; | awk '{print $1, $2}' | sort | uniq -d -w 64 +``` + +### 6.2 Categorize workflows +| Category | Workflow | Count | Action | +|----------|----------|-------|--------| +| Security | secret-scanner.yml | 1,191 | ✅ Optimized | +| Security | codeql.yml | ~500 | Schedule weekly | +| Security | scorecard.yml | ~500 | Schedule weekly | +| Security | hypatia-scan.yml | ~500 | Schedule weekly | +| Build | rust-ci.yml | ~200 | Path filter | +| Build | elixir-ci.yml | ~50 | Path filter | +| Build | build-validation.yml | ~50 | DELETE | +| Governance | governance.yml | ~1000 | N/A | +| Lint | workflow-linter.yml | ~500 | N/A | +| Mirror | mirror.yml | ~300 | N/A | + +--- + +## Immediate Action Items (Next 48 Hours) + +1. ✅ **DONE:** Remove trufflehog from secret-scanner-reusable.yml +2. **TODO:** Merge `build-validation.yml` into language-specific CI workflows in verisimdb +3. **TODO:** Add path filters to rust-secrets job in secret-scanner-reusable.yml +4. **TODO:** Create `proven-tests-and-benches` repo skeleton with Idris2 proofs +5. **TODO:** Open per-repo issues for workflow consolidation (verisimdb, then propagate) + +--- + +## Success Metrics + +| Metric | Current | Target (4 weeks) | Target (12 weeks) | +|--------|---------|------------------|-------------------| +| CI minutes/month | ~50,000 | <25,000 (-50%) | <15,000 (-70%) | +| Workflow count | ~1,200 | <800 | <600 | +| PR merge time | ~30min | <15min | <10min | +| Test coverage | ~80% | >90% | >95% | +| Proven tests | 0 | >10 modules | >50 modules | + +--- + +## Tags + +`cicd-optimization`, `cost-reduction`, `performance`, `security`, `ultra-zotta-plan`, `estate-wide`, `high-priority` + +--- + +## Related Issues + +- [ ] Track 1: Immediate Redundancy Elimination +- [ ] Track 2: Workflow Naming + Clarity +- [ ] Track 3: Path Filter Optimization +- [ ] Track 4: Test + Bench Standards +- [ ] Track 5: Acceleration Opportunities +- [ ] Track 6: Estate-Wide Workflow Inventory diff --git a/.github/ISSUES/cicd-optimization/001-immediate-redundancy-elimination.md b/.github/ISSUES/cicd-optimization/001-immediate-redundancy-elimination.md new file mode 100644 index 00000000..eea13506 --- /dev/null +++ b/.github/ISSUES/cicd-optimization/001-immediate-redundancy-elimination.md @@ -0,0 +1,95 @@ +// SPDX-License-Identifier: MPL-2.0 +// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell + +# Issue #001: Immediate Redundancy Elimination + +**Track:** CICD Optimization — Ultra-Zotta-Plan +**Priority:** CRITICAL +**Status:** IN PROGRESS +**Owner:** @hyperpolymath +**Date:** 2026-06-05 + +--- + +## Description + +Estate-wide CICD has significant redundancy causing unnecessary CI minute consumption and queuing delays. This issue tracks immediate wins that can be deployed within Week 1. + +--- + +## Tasks + +### ✅ Task 1.1: Remove trufflehog from secret-scanner (DONE) +- **File:** `standards/.github/workflows/secret-scanner-reusable.yml` +- **Change:** Deleted `trufflehog:` job (13s saved per run) +- **Status:** ✅ COMPLETED +- **Impact:** ~5,000+ minutes/month saved across 1,191 repos + +### Task 1.2: Consolidate verisimdb build workflows +- **Repo:** `databases/verisimdb` +- **Problem:** Three workflows with overlapping jobs: + - `build-validation.yml` — quick Rust + Elixir build checks + - `rust-ci.yml` — full Rust suite (including `bench-compile`, `audit`) + - `elixir-ci.yml` — full Elixir suite (including `bench-compile`, `hex audit`) +- **Duplicate jobs:** + - `bench-compile` appears in both rust-ci and elixir-ci + - `audit` appears as `cargo audit` (rust-ci) and `hex audit` (elixir-ci) +- **Action:** + - Option A: Delete `build-validation.yml` (rust-ci + elixir-ci already cover it) + - Option B: Merge build-validation into language workflows with path filters +- **Estimated savings:** 2-3 minutes per PR +- **Status:** TODO +- **Priority:** HIGH + +### Task 1.3: Eliminate rust-secrets waste +- **Problem:** 300+ repos run `rust-secrets` job but have NO `Cargo.toml` +- **Examples:** aspasia, bgp-backbone-lab, branch-newspaper, and ~297 others +- **Current behavior:** Job self-skips with "No Cargo.toml found" message (safe but wasteful) +- **Action:** Add conditional to rust-secrets job in `secret-scanner-reusable.yml`: + ```yaml + rust-secrets: + if: > + github.event_name != 'schedule' && + (contains(github.event.pull_request.changed_files, 'Cargo.toml') || + contains(github.event.pull_request.changed_files, '**.rs')) + # OR simpler: + if: hashFiles('**/Cargo.toml') != '' + ``` +- **Estimated savings:** ~300 repos × 3s = 900s per estate-wide push +- **Status:** TODO +- **Priority:** HIGH + +### Task 1.4: Schedule-heavy workflows +- **Problem:** `codeql.yml`, `scorecard.yml`, `hypatia-scan.yml` run on every push +- **Action:** Change to weekly schedule, keep push trigger for main +- **Estimated savings:** ~5-10 minutes per push +- **Status:** TODO +- **Priority:** MEDIUM + +--- + +## Success Criteria + +- [ ] verisimdb has no duplicate job names across workflows +- [ ] rust-secrets runs only on repos with Rust code +- [ ] CI minutes reduced by >20% from Week 0 baseline + +--- + +## Dependencies + +- None (independent tasks) + +--- + +## Tags + +`cicd-optimization`, `redundancy`, `cost-reduction`, `week-1`, `high-priority`, `track-1` + +--- + +## Related + +- Roadmap: `2026-06-05-cicd-optimization-roadmap.md` +- Issue #002: Workflow Naming + Clarity +- Issue #003: Path Filter Optimization diff --git a/.github/ISSUES/cicd-optimization/002-workflow-naming-clarity.md b/.github/ISSUES/cicd-optimization/002-workflow-naming-clarity.md new file mode 100644 index 00000000..c5bb30dd --- /dev/null +++ b/.github/ISSUES/cicd-optimization/002-workflow-naming-clarity.md @@ -0,0 +1,175 @@ +// SPDX-License-Identifier: MPL-2.0 +// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell + +# Issue #002: Workflow Naming + Clarity Standardization + +**Track:** CICD Optimization — Ultra-Zotta-Plan +**Priority:** HIGH +**Status:** TODO +**Owner:** @hyperpolymath +**Date:** 2026-06-05 + +--- + +## Description + +Current workflow naming across the estate is inconsistent and unclear, making it difficult to: +- Understand what each workflow does +- Identify redundancies +- Maintain consistency across repos +- Onboard new contributors + +--- + +## Current State: Chaos + +### Inconsistent Patterns +``` +rust-ci.yml # Good: language-purpose +elixir-ci.yml # Good: language-purpose +build-validation.yml # Bad: purpose only, unclear scope +secret-scanner.yml # OK: purpose only +security-scan.yml # Overlaps with secret-scanner? +scorecard.yml # OK: tool name +scorecard-enforcer.yml # What's the difference? +governance.yml # Too broad +hypatia-scan.yml # OK: tool name +workflow-linter.yml # OK: purpose +mirror.yml # Too vague +cflite_batch.yml # Project-specific, unclear +cflite_pr.yml # Project-specific, unclear +``` + +### Duplicate/Overlapping Names +- `secret-scanner.yml` vs `security-scan.yml` +- `scorecard.yml` vs `scorecard-enforcer.yml` +- `build-validation.yml` vs `rust-ci.yml` vs `elixir-ci.yml` + +--- + +## Proposed Standard + +### Naming Convention + +**Format:** `-.yml` OR `-.yml` + +**Language prefixes:** +- `rust-` — Rust language +- `elixir-` — Elixir language +- `go-` — Go language +- `javascript-` / `typescript-` — JS/TS +- `python-` — Python +- `java-` — Java +- `c-` / `cpp-` — C/C++ + +**Purpose suffixes:** +- `-build` — Compilation only +- `-test` — Testing only +- `-build-test` — Compilation + testing +- `-lint` — Linting/formatting +- `-audit` — Security auditing +- `-fuzz` — Fuzzing +- `-bench` — Benchmarks +- `-docs` — Documentation + +**Category prefixes (for non-language-specific):** +- `security-` — Security-related +- `governance-` — Governance/policy +- `lint-` — Linting/formatting +- `test-` — Testing +- `build-` — Build-related +- `deploy-` — Deployment +- `sync-` — Synchronization +- `scan-` — Scanning (security/secrets) + +### Examples of Good Names + +``` +# Language-specific +rust-build-test.yml # Rust: build + test +rust-lint.yml # Rust: clippy + rustfmt +elixir-build-test.yml # Elixir: mix compile + test +go-build-test.yml # Go: build + test + +# Security +security-secret-scan.yml # Secret detection (gitleaks) +security-codeql.yml # CodeQL analysis +security-scorecard.yml # OSSF Scorecard +security-trivy.yml # Container scanning + +# Governance +governance-license.yml # License compliance +governance-workflow.yml # Workflow validation +governance-spdx.yml # SPDX header checks + +# Build/Deploy +build-validation.yml # Quick build check (keep if cross-language) +deploy-github-pages.yml # GitHub Pages deployment +deploy-container.yml # Container image build + push +``` + +### Required Metadata in Every Workflow + +Add to the top of every workflow file: + +```yaml +# SPDX-License-Identifier: MPL-2.0 +name: Rust — Build + Test + Lint +# ==== METADATA ==== +# Purpose: Validates Rust code compiles, passes tests, and clippy lint +# Language: Rust +# Owner: @hyperpolymath +# Schedule: On push/PR (path-filtered to Rust files) +# Timeout: 30m total +# Est. Cost: 5-8 minutes per run +# Paths: **/*.rs, Cargo.toml, Cargo.lock +# ==== /METADATA ==== +``` + +--- + +## Tasks + +### Task 2.1: Rename workflows in standards repo +- **Action:** Rename workflows in `standards/.github/workflows/` to follow convention +- **Examples:** + - `secret-scanner.yml` → `security-secret-scan.yml` + - `build-validation.yml` → `build-validation.yml` (keep, it's OK) + - `scorecard-enforcer.yml` → `security-scorecard-enforcer.yml` +- **Status:** TODO +- **Priority:** MEDIUM + +### Task 2.2: Create naming lint rule +- **Action:** Add workflow-linter rule to enforce naming convention +- **Check:** Workflow filename matches regex: `^[a-z]+(-[a-z]+)+\.yml$` +- **Status:** TODO +- **Priority:** MEDIUM + +### Task 2.3: Estate-wide rename propagation +- **Action:** Script to rename workflows across all repos +- **Approach:** Use `gh api` to list repos, then batch update +- **Status:** TODO +- **Priority:** LOW (after standards repo is done) + +--- + +## Success Criteria + +- [ ] All new workflows follow naming convention +- [ ] All existing workflows have metadata comments +- [ ] No duplicate/overlapping workflow names in any repo +- [ ] Naming lint rule prevents regressions + +--- + +## Tags + +`cicd-optimization`, `naming`, `clarity`, `standards`, `week-1`, `high-priority`, `track-2` + +--- + +## Related + +- Roadmap: `2026-06-05-cicd-optimization-roadmap.md` +- Issue #001: Immediate Redundancy Elimination +- Issue #003: Path Filter Optimization diff --git a/.github/ISSUES/cicd-optimization/003-path-filter-optimization.md b/.github/ISSUES/cicd-optimization/003-path-filter-optimization.md new file mode 100644 index 00000000..aec152a2 --- /dev/null +++ b/.github/ISSUES/cicd-optimization/003-path-filter-optimization.md @@ -0,0 +1,244 @@ +// SPDX-License-Identifier: MPL-2.0 +// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell + +# Issue #003: Path Filter Optimization + +**Track:** CICD Optimization — Ultra-Zotta-Plan +**Priority:** HIGH +**Status:** TODO +**Owner:** @hyperpolymath +**Date:** 2026-06-05 + +--- + +## Description + +Currently, many workflows run on **every push/PR** regardless of what files changed. This causes unnecessary CI minute consumption when only docs or config files are modified. + +**Estimated waste:** 40-60% of CI minutes on repos with active documentation. + +--- + +## Current State + +### Workflows WITHOUT path filters (run on every change): +```yaml +# These run even when only README.md is edited: +- rust-ci.yml # Should only run on Rust file changes +- elixir-ci.yml # Should only run on Elixir file changes +- codeql.yml # Could be scheduled only +- scorecard.yml # Could be scheduled only +- hypatia-scan.yml # Could be scheduled only +- build-validation.yml # Should only run on code changes +``` + +### Workflows WITH path filters (good): +```yaml +# elixir-ci.yml in verisimdb (partial): +on: + push: + paths: + - "elixir-orchestration/**" + - ".github/workflows/elixir-ci.yml" + pull_request: + paths: + - "elixir-orchestration/**" + - ".github/workflows/elixir-ci.yml" +``` + +--- + +## Proposed Path Filters + +### 1. Language-Specific Workflows + +#### Rust (`rust-ci.yml`) +```yaml +on: + push: + branches: [main, master] + paths: + - '**.rs' + - 'Cargo.toml' + - 'Cargo.lock' + - 'rust-toolchain' + - 'rust-toolchain.toml' + - '.github/workflows/rust-ci.yml' + pull_request: + branches: [main, master] + paths: + - '**.rs' + - 'Cargo.toml' + - 'Cargo.lock' + - 'rust-toolchain' + - 'rust-toolchain.toml' + - '.github/workflows/rust-ci.yml' +``` + +#### Elixir (`elixir-ci.yml`) +```yaml +on: + push: + branches: [main, master] + paths: + - '**/*.ex' + - '**/*.exs' + - 'mix.exs' + - 'mix.lock' + - '.github/workflows/elixir-ci.yml' + pull_request: + branches: [main, master] + paths: + - '**/*.ex' + - '**/*.exs' + - 'mix.exs' + - 'mix.lock' + - '.github/workflows/elixir-ci.yml' +``` + +#### Go +```yaml +on: + push: + branches: [main, master] + paths: + - '**.go' + - 'go.mod' + - 'go.sum' + - '.github/workflows/go-ci.yml' + pull_request: + branches: [main, master] + paths: + - '**.go' + - 'go.mod' + - 'go.sum' + - '.github/workflows/go-ci.yml' +``` + +### 2. Security Workflows + +#### Secret Scanner (`secret-scanner.yml`) +**Should run on ALL changes** (secrets can be added anywhere) +- Keep current: `on: [pull_request, push]` +- NO path filters + +#### CodeQL (`codeql.yml`) +**Can be scheduled** (deep analysis, not needed on every commit) +```yaml +on: + push: + branches: [main, master] + pull_request: + branches: [main, master] + schedule: + - cron: '0 4 * * 1' # Weekly Monday at 4am +``` + +#### Scorecard (`scorecard.yml`) +**Can be scheduled** (repo metadata doesn't change often) +```yaml +on: + push: + branches: [main, master] + schedule: + - cron: '0 3 * * 0' # Weekly Sunday at 3am +``` + +#### Hypatia Scan (`hypatia-scan.yml`) +**Can be scheduled** (neurosymbolic analysis is slow) +```yaml +on: + push: + branches: [main, master] + schedule: + - cron: '0 2 * * 1' # Weekly Monday at 2am +``` + +### 3. Governance Workflows + +#### SPDX Check +**Should run on code changes only** (not on docs) +```yaml +on: + push: + branches: [main, master] + paths-ignore: + - '**.md' + - '**.adoc' + - '**.txt' + - 'LICENSE' + - '.gitignore' + pull_request: + branches: [main, master] + paths-ignore: + - '**.md' + - '**.adoc' + - '**.txt' + - 'LICENSE' + - '.gitignore' +``` + +#### Workflow Linter +**Should run on workflow changes only** +```yaml +on: + push: + branches: [main, master] + paths: + - '.github/workflows/**' + - '.github/**' + pull_request: + branches: [main, master] + paths: + - '.github/workflows/**' + - '.github/**' +``` + +--- + +## Tasks + +### Task 3.1: Add path filters to language workflows +- **Repos:** Start with high-impact repos (verisimdb, 007, hypatia, etc.) +- **Action:** Add language-specific path filters to rust-ci.yml, elixir-ci.yml, etc. +- **Status:** TODO +- **Priority:** HIGH + +### Task 3.2: Schedule heavy security workflows +- **Action:** Change codeql.yml, scorecard.yml, hypatia-scan.yml to weekly schedule +- **Status:** TODO +- **Priority:** HIGH + +### Task 3.3: Add path-ignore for docs-only changes +- **Action:** Add `paths-ignore` for markdown/adoc files to governance workflows +- **Status:** TODO +- **Priority:** MEDIUM + +### Task 3.4: Create path-filter templates +- **Action:** Add reusable path-filter configs in standards repo +- **Location:** `standards/templates/github/workflows/path-filters/` +- **Status:** TODO +- **Priority:** MEDIUM + +--- + +## Success Criteria + +- [ ] All language workflows have path filters +- [ ] Heavy workflows (codeql, scorecard, hypatia) run on schedule +- [ ] Docs-only PRs complete in <5 minutes +- [ ] CI minutes reduced by >30% from Week 0 baseline + +--- + +## Tags + +`cicd-optimization`, `path-filters`, `performance`, `cost-reduction`, `week-2`, `high-priority`, `track-3` + +--- + +## Related + +- Roadmap: `2026-06-05-cicd-optimization-roadmap.md` +- Issue #001: Immediate Redundancy Elimination +- Issue #002: Workflow Naming + Clarity diff --git a/.github/ISSUES/cicd-optimization/004-tests-benches-standards.md b/.github/ISSUES/cicd-optimization/004-tests-benches-standards.md new file mode 100644 index 00000000..204fe209 --- /dev/null +++ b/.github/ISSUES/cicd-optimization/004-tests-benches-standards.md @@ -0,0 +1,366 @@ +// SPDX-License-Identifier: MPL-2.0 +// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell + +# Issue #004: Test + Bench Standards Audit & Proven Tests Repo + +**Track:** CICD Optimization — Ultra-Zotta-Plan +**Priority:** HIGH +**Status:** TODO +**Owner:** @hyperpolymath +**Date:** 2026-06-05 + +--- + +## Description + +This issue covers: +1. **Audit** of existing test/bench standards across the estate +2. **Panic-Attack** integration for runtime safety +3. **Proven Tests Repo** creation using Idris2 for formal guarantees + +--- + +## Part 1: Audit Existing Test Standards + +### 1.1 Current State + +**Standards repo location:** `standards/.github/workflows/` + `standards/templates/` + +**Questions to answer:** +- [ ] Are test workflows applied estate-wide? +- [ ] Are there contradictions between repos? +- [ ] Are panic-attack tests integrated everywhere? +- [ ] Are benchmarks proven/safe? +- [ ] Do test workflows cover echo-type safety? + +### 1.2 Inventory of Test Workflows + +```bash +# Find all test-related workflows +find . -path "*/.github/workflows/*.yml" -exec grep -l "test\|bench" {} \; | sort | uniq +``` + +**Expected findings:** +- `rust-ci.yml` (includes `cargo test`) +- `elixir-ci.yml` (includes `mix test`) +- `test.yml` / `tests.yml` (various repos) +- `bench.yml` / `benchmarks.yml` (various repos) +- `panic-attack.yml` (if exists) + +### 1.3 Contradictions Check + +**Compare:** +- Rust test patterns across 5+ repos +- Elixir test patterns across 5+ repos +- Benchmark configurations +- Panic-attack integration depth + +--- + +## Part 2: Panic-Attack Integration + +### 2.1 Current State + +**Panic-attack repo:** Likely in `panic-attack/` or `standards/` + +**Patterns to detect:** +- [ ] Unsafe blocks (`unsafe { }`) +- [ ] Unwraps/expects (`.unwrap()`, `.expect()`) +- [ ] Integer overflows +- [ ] Race conditions (send/recv without proper synchronization) +- [ ] Memory safety issues +- [ ] Null pointer dereferences + +### 2.2 Integration Tasks + +#### Task 2.2.1: Add panic-attack to all Rust repos +- **Action:** Add panic-attack workflow to repos with `Cargo.toml` +- **Template:** + ```yaml + name: Panic Attack + on: [push, pull_request] + jobs: + panic-attack: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v6 + - uses: hyperpolymath/panic-attack-action@main + ``` +- **Status:** TODO +- **Priority:** HIGH + +#### Task 2.2.2: Configure panic-attack for estate-specific patterns +- **Echo-type safety:** Detect violations of echo-type invariants +- **Higher-order patterns:** Identity, projection, invariance, traversal +- **Custom rules:** Based on estate proofs +- **Status:** TODO +- **Priority:** HIGH + +--- + +## Part 3: Proven Tests Repo (Idris2) + +### 3.1 Repo Creation + +**New repo:** `proven-tests-and-benches` + +**Purpose:** Formal guarantees for test correctness using Idris2 + +**Structure:** +``` +proven-tests-and-benches/ +├── README.adoc # Explanation of approach +├── PROOFS.adoc # Catalog of proven properties +├── src/ +│ ├── Core/ +│ │ ├── Test.idr # Test type definitions +│ │ ├── Valid.idr # Validity proofs +│ │ ├── Sound.idr # Soundness proofs +│ │ └── Safe.idr # Safety proofs +│ ├── EchoTypes/ +│ │ ├── Safety.idr # Echo-type safety +│ │ └── Invariance.idr # Echo-type invariance +│ ├── HigherOrder/ +│ │ ├── Identity.idr # Identity tests +│ │ ├── Projection.idr # Projection tests +│ │ ├── Traversal.idr # Traversal tests +│ │ └── Transfer.idr # Interdimensional transfer +│ └── SetTheory/ +│ ├── Basics.idr # Set operations +│ └── Advanced.idr # Higher set concepts +├── tests/ +│ └── examples/ # Example proven tests +├── templates/ +│ └── test-template.idr # Template for new tests +└── Justfile # Build recipes +``` + +### 3.2 Properties to Prove + +#### Test Validity +```idris +-- A test is valid if it has a well-formed structure +TestValid : (t : Test) -> Type +TestValid t = + (Test.HasName t) × + (Test.HasInput t) × + (Test.HasExpectedOutput t) +``` + +#### Test Soundness +```idris +-- A test is sound if it catches what it claims to catch +TestSound : (t : Test) -> Prop +TestSound t = + ∀ input, + Test.Runs t input → + (Test.Passes t input ↔ MeetsSpec input (Test.Expected t)) +``` + +#### Test Safety +```idris +-- A test is safe if it cannot cause undefined behavior +TestSafe : (t : Test) -> Prop +TestSafe t = + ∀ input, + Test.Runs t input → + ¬ (Crashes t input ∨ UndefinedBehavior t input) +``` + +#### Test Tamper-Proof +```idris +-- A test is tamper-proof if modifications are detectable +TestTamperProof : (t : Test) -> Prop +TestTamperProof t = + ∀ t', + t' ≠ t → + DetectsTampering (Test.Signature t) (Test.Signature t') +``` + +#### Test Unpanickable +```idris +-- A test cannot panic +TestUnpanickable : (t : Test) -> Prop +TestUnpanickable t = + ∀ input, + Test.Runs t input → + ¬ Panics t input +``` + +### 3.3 Echo-Type Specific Tests + +#### Echo-Type Safety +```idris +-- Echo types preserve structure through transformations +echoTypeSafety : (T : Type) → (op : EchoOp T) → Prop +echoTypeSafety T op = + ∀ (x : T), + Let y = applyEchoOp op x in + PreservesStructure x y +``` + +#### Identity Tests +```idris +-- Identity operations preserve value +identityPreservation : (T : Type) → (x : T) → Prop +identityPreservation T x = + identity T x = x +``` + +#### Projection Tests +```idris +-- Projections extract correct components +projectionCorrectness : (T : Type) → (p : Projection T) → Prop +projectionCorrectness T p = + ∀ (x : T), + Let y = project p x in + ValidProjection p x y +``` + +#### Invariance Tests +```idris +-- Invariants are preserved through operations +invariancePreservation : (T : Type) → (inv : Invariant T) → Prop +invariancePreservation T inv = + ∀ (x : T) (op : Op T), + inv x → + inv (applyOp op x) +``` + +#### Traversal Tests +```idris +-- Traversals visit all elements correctly +traversalCompleteness : (T : Type) → (traverse : Traversal T) → Prop +traversalCompleteness T traverse = + ∀ (x : T), + Let visited = traverse x in + AllElementsVisited x visited +``` + +#### Set Concept Tests +```idris +-- Set operations maintain set properties +setOperationCorrectness : (A : Type) → Prop +setOperationCorrectness A = + (SetUnionAssociative A) × + (SetIntersectionAssociative A) × + (SetDistributive A) +``` + +#### Interdimensional Transfer Tests +```idris +-- Transfers between dimensions preserve meaning +interdimensionalPreservation : (D1 D2 : Dimension) → Prop +interdimensionalPreservation D1 D2 = + ∀ (x : D1), + Let y = transfer D1 D2 x in + Semantics.Preserved x y +``` + +--- + +## Part 4: Estate-Specific Test Patterns + +### 4.1 Patterns to Cover + +| Pattern | Description | Test Approach | +|---------|-------------|---------------| +| Echo-type safety | Structure preservation | Idris2 proofs | +| Higher-order constructs | Function-level properties | Type-level tests | +| Identity | Value preservation | Equality proofs | +| Projection | Component extraction | Property-based tests | +| Invariance | Preservation through ops | Inductive proofs | +| Traversal | Complete visitation | Coverage proofs | +| Set concepts | Mathematical properties | Formal verification | +| Interdimensional transfer | Meaning preservation | Bisimulation proofs | + +### 4.2 Integration with CI + +**New workflow:** `proven-tests.yml` + +```yaml +name: Proven Tests +on: + push: + branches: [main] + paths: + - 'proven-tests/**' + - '**.idr' + pull_request: + branches: [main] + paths: + - 'proven-tests/**' + - '**.idr' + +jobs: + idris-prove: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v6 + - uses: idris-lang/setup-idris2@v1 + - run: idris2 --build proven-tests.ipkg + - run: idris2 --exec proven-tests-exec + + coq-prove: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v6 + - uses: coq-community/setup-coq@v1 + - run: make -C coq-proofs +``` + +--- + +## Tasks + +### Task 4.1: Audit existing test standards +- **Action:** Document current state, contradictions, gaps +- **Output:** `audits/2026-06-05-test-standards-audit.adoc` +- **Status:** TODO +- **Priority:** HIGH + +### Task 4.2: Integrate panic-attack estate-wide +- **Action:** Add panic-attack to all Rust repos +- **Status:** TODO +- **Priority:** HIGH + +### Task 4.3: Create proven-tests-and-benches repo +- **Action:** Initialize repo with structure + example proofs +- **Status:** TODO +- **Priority:** HIGH + +### Task 4.4: Prove echo-type safety +- **Action:** Implement echo-type safety proofs in Idris2 +- **Status:** TODO +- **Priority:** MEDIUM + +### Task 4.5: Add proven tests CI workflow +- **Action:** Add workflow to run Idris2/Coq proofs on PR +- **Status:** TODO +- **Priority:** MEDIUM + +--- + +## Success Criteria + +- [ ] Test standards audit completed +- [ ] Panic-attack integrated in all Rust repos +- [ ] proven-tests-and-benches repo created +- [ ] First 10 proven test modules implemented +- [ ] Proven tests CI workflow running + +--- + +## Tags + +`cicd-optimization`, `tests`, `benchmarks`, `formal-proofs`, `idris2`, `panic-attack`, `proven-tests`, `week-2`, `high-priority`, `track-4` + +--- + +## Related + +- Roadmap: `2026-06-05-cicd-optimization-roadmap.md` +- Issue #001: Immediate Redundancy Elimination +- Issue #002: Workflow Naming + Clarity +- Issue #003: Path Filter Optimization +- Issue #005: Acceleration Opportunities diff --git a/.github/ISSUES/cicd-optimization/005-acceleration-opportunities.md b/.github/ISSUES/cicd-optimization/005-acceleration-opportunities.md new file mode 100644 index 00000000..60a6d7fd --- /dev/null +++ b/.github/ISSUES/cicd-optimization/005-acceleration-opportunities.md @@ -0,0 +1,335 @@ +// SPDX-License-Identifier: MPL-2.0 +// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell + +# Issue #005: Acceleration Opportunities + +**Track:** CICD Optimization — Ultra-Zotta-Plan +**Priority:** MEDIUM +**Status:** TODO +**Owner:** @hyperpolymath +**Date:** 2026-06-05 + +--- + +## Description + +Explore opportunities to **dramatically reduce CI costs** through caching, self-hosted runners, and matrix optimization. These are longer-term investments with high ROI. + +--- + +## Opportunity 1: Self-Hosted Runners (80-90% savings for heavy work) + +### 1.1 Target Workflows + +| Workflow | Avg Duration | Monthly Cost Estimate | Savings Potential | +|----------|---------------|----------------------|-------------------| +| `oracle-fuzz.yml` | 10-60m | ~$5,000 | 90% | +| `hypatia-scan.yml` | 5-15m | ~$3,000 | 80% | +| `codeql.yml` | 5-10m | ~$2,000 | 80% | +| E2E tests | 15-45m | ~$4,000 | 90% | +| Fuzz targets | 10-30m | ~$3,000 | 90% | +| **Total** | | **~$17,000** | **~$13,600 (80%)** | + +### 1.2 Implementation Plan + +#### Phase 1: Pilot (Week 3) +- **Target:** 1-2 highest-cost repos (verisimdb, 007) +- **Runner:** Self-hosted on Eclipse infrastructure +- **Security:** Rootless Podman containers +- **Setup:** + ```bash + # Install Podman + sudo apt install podman + + # Create runner container + podman run -d --name github-runner \ + -e REPO_URL=https://github.com/hyperpolymath/verisimdb \ + -e RUNNER_TOKEN= \ + -e RUNNER_NAME=verisimdb-runner \ + -e RUNNER_GROUP=verisimdb \ + --restart always \ + ghcr.io/actions/actions-runner:latest + ``` + +#### Phase 2: Scale (Week 4-5) +- **Target:** All repos with fuzzing/E2E/Hypatia workflows +- **Runner pool:** 3-5 runners (shared across repos) +- **Labels:** Use runner labels to route heavy jobs + ```yaml + jobs: + fuzz: + runs-on: [self-hosted, fuzz-runner] + ``` + +#### Phase 3: Estate-wide (Week 6+) +- **Target:** All repos +- **Runner pool:** 10+ runners +- **Auto-scaling:** Use Kubernetes for dynamic scaling + +### 1.3 Security Requirements + +- [ ] Rootless containers (no root access) +- [ ] Read-only root filesystem +- [ ] No new privileges +- [ ] Network isolation +- [ ] Regular runner image updates +- [ ] Audit logging + +--- + +## Opportunity 2: Caching Optimization (30-50% savings) + +### 2.1 Current State + +**Inconsistent caching:** +- Some repos use `Swatinem/rust-cache` +- Others use manual cache actions +- Some have no caching +- Cache keys vary (some good, some not) + +### 2.2 Standard Caching Strategy + +#### Rust +```yaml +- uses: Swatinem/rust-cache@v2 + with: + key: rust-cache-${{ hashFiles('**/Cargo.lock') }} + cache-directories: | + ~/.cargo/registry/ + ~/.cargo/git/ + target/ +``` + +#### Elixir +```yaml +- uses: actions/cache@v5 + with: + path: | + elixir-orchestration/deps + elixir-orchestration/_build + key: elixir-cache-${{ hashFiles('elixir-orchestration/mix.lock') }} +``` + +#### Node.js +```yaml +- uses: actions/cache@v5 + with: + path: node_modules/ + key: node-cache-${{ hashFiles('package-lock.json') }} +``` + +#### Go +```yaml +- uses: actions/cache@v5 + with: + path: ~/go/pkg/mod/ + key: go-cache-${{ hashFiles('go.sum') }} +``` + +### 2.3 Cache Key Optimization + +**Problem:** Cache keys that are too broad cause cache misses. + +**Solution:** Use precise, hierarchical cache keys: +```yaml +key: ${{ runner.os }}-${{ hashFiles('Cargo.lock') }}-${{ hashFiles('rust-toolchain') }} +restore-keys: | + ${{ runner.os }}-${{ hashFiles('Cargo.lock') }}- + ${{ runner.os }}- +``` + +### 2.4 Tasks + +#### Task 2.4.1: Create caching standards +- **Output:** `standards/templates/github/workflows/caching.yml` +- **Status:** TODO +- **Priority:** HIGH + +#### Task 2.4.2: Apply caching to top 10 repos +- **Target:** verisimdb, 007, hypatia, gossamer, etc. +- **Status:** TODO +- **Priority:** HIGH + +#### Task 2.4.3: Estate-wide caching propagation +- **Approach:** Use reusable workflow with caching +- **Status:** TODO +- **Priority:** MEDIUM + +--- + +## Opportunity 3: Matrix Strategy Optimization (20-40% savings) + +### 3.1 Current State + +**Typical matrix (wasteful):** +```yaml +strategy: + matrix: + rust: + - stable + - beta + - nightly + os: + - ubuntu-latest + - macos-latest + - windows-latest + # 3 × 3 = 9 combinations, most redundant for PRs +``` + +### 3.2 Optimized Matrix + +**For PRs:** Only test primary combination +**For main/schedule:** Test full matrix + +```yaml +jobs: + test: + strategy: + matrix: + include: + # PR trigger: only stable on ubuntu + - rust: stable + os: ubuntu-latest + if: github.event_name == 'pull_request' + # Main/schedule: full matrix + - rust: stable + os: ubuntu-latest + if: github.event_name != 'pull_request' + - rust: beta + os: ubuntu-latest + if: github.event_name != 'pull_request' + - rust: nightly + os: ubuntu-latest + if: github.event_name != 'pull_request' + - rust: stable + os: macos-latest + if: github.event_name != 'pull_request' + - rust: stable + os: windows-latest + if: github.event_name != 'pull_request' +``` + +### 3.3 Even Better: Separate Workflows + +```yaml +# rust-ci-pr.yml (runs on PRs) +name: Rust CI (PR) +on: + pull_request: + paths: [**.rs, Cargo.toml] +jobs: + test: + strategy: + matrix: + rust: [stable] + os: [ubuntu-latest] + +# rust-ci-full.yml (runs on schedule/main) +name: Rust CI (Full) +on: + push: + branches: [main] + schedule: + - cron: '0 3 * * 0' +jobs: + test: + strategy: + matrix: + rust: [stable, beta, nightly] + os: [ubuntu-latest, macos-latest, windows-latest] +``` + +### 3.4 Tasks + +#### Task 3.4.1: Optimize matrix for top 5 repos +- **Targets:** verisimdb, 007, hypatia, gossamer, aspasia +- **Status:** TODO +- **Priority:** HIGH + +#### Task 3.4.2: Create matrix templates +- **Output:** `standards/templates/github/workflows/matrix-strategies.yml` +- **Status:** TODO +- **Priority:** MEDIUM + +--- + +## Opportunity 4: Alternative Tools (10-30% better) + +### 4.1 Secret Scanning + +| Tool | Strengths | Weaknesses | Recommendation | +|------|-----------|------------|----------------| +| **Gitleaks** | Fast, regex-based, good CVE coverage | Can miss entropy-based secrets | ✅ KEEP (primary) | +| **TruffleHog** | Entropy + verified detection | Slower, ~90% overlap with gitleaks | ❌ REMOVED | +| **GitGuardian** | Commercial, good UI | Paid | ⚠️ EVALUATE | +| **Semgrep** | Multi-purpose, fast | Needs custom rules for secrets | ⚠️ EVALUATE | + +**Decision:** Gitleaks is sufficient. TruffleHog removed. Evaluate Semgrep for multi-purpose scanning. + +### 4.2 Code Analysis + +| Tool | Strengths | Weaknesses | Recommendation | +|------|-----------|------------|----------------| +| **CodeQL** | Deep semantic analysis | Slow, heavy | ✅ KEEP (scheduled) | +| **Clippy** | Rust-specific lint | Rust only | ✅ KEEP | +| **SonarQube** | Multi-language | Heavy, commercial | ❌ REPLACE with CodeQL | +| **PVS-Studio** | Commercial, deep | Paid | ❌ DROP | + +### 4.3 Fuzzing + +| Tool | Strengths | Weaknesses | Recommendation | +|------|-----------|------------|----------------| +| **cargo-fuzz** | Rust-native | Good | +| **AFL** | Generic | Older | ⚠️ EVALUATE | +| **libFuzzer** | LLVM-based | Integration complexity | ⚠️ EVALUATE | +| **Honggfuzz** | Multi-language | Less maintained | ❌ DROP | + +--- + +## Tasks + +### Task 5.1: Pilot self-hosted runners +- **Repos:** verisimdb, 007 +- **Workflows:** fuzz, hypatia-scan, codeql +- **Status:** TODO +- **Priority:** HIGH + +### Task 5.2: Apply standard caching +- **Repos:** Top 10 by CI minute consumption +- **Status:** TODO +- **Priority:** HIGH + +### Task 5.3: Optimize matrix strategies +- **Repos:** All repos with matrix builds +- **Status:** TODO +- **Priority:** MEDIUM + +### Task 5.4: Evaluate alternative tools +- **Tools:** Semgrep, GitGuardian +- **Status:** TODO +- **Priority:** LOW + +--- + +## Success Criteria + +- [ ] Self-hosted runners handling 50% of heavy workflows +- [ ] Caching applied to 80% of repos +- [ ] Matrix optimization applied to 50% of repos +- [ ] CI cost reduced by >50% from Week 0 baseline + +--- + +## Tags + +`cicd-optimization`, `acceleration`, `self-hosted`, `caching`, `matrix`, `cost-reduction`, `week-3`, `medium-priority`, `track-5` + +--- + +## Related + +- Roadmap: `2026-06-05-cicd-optimization-roadmap.md` +- Issue #001: Immediate Redundancy Elimination +- Issue #002: Workflow Naming + Clarity +- Issue #003: Path Filter Optimization +- Issue #004: Test + Bench Standards diff --git a/.github/ISSUES/cicd-optimization/006-verisimdb-114-specific.md b/.github/ISSUES/cicd-optimization/006-verisimdb-114-specific.md new file mode 100644 index 00000000..00d090f9 --- /dev/null +++ b/.github/ISSUES/cicd-optimization/006-verisimdb-114-specific.md @@ -0,0 +1,292 @@ +// SPDX-License-Identifier: MPL-2.0 +// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell + +# Issue #006: verisimdb#114 — HexAudit + Benchee Duplicate Jobs + +**Track:** CICD Optimization — Ultra-Zotta-Plan +**Priority:** HIGH +**Status:** IN PROGRESS +**Owner:** @hyperpolymath +**Date:** 2026-06-05 +**Related PR:** hyperpolymath/verisimdb#114 + +--- + +## Problem Statement + +PR #114 in `databases/verisimdb` shows **duplicate job names** causing CI confusion: + +| Job Name | Source Workflow | Purpose | Duration | +|----------|----------------|---------|----------| +| `bench-compile` | `rust-ci.yml` | Rust benchmarks compile | 3m50s | +| `benchee scripts compile` | `elixir-ci.yml` | Elixir benchee compile | (not shown in checks) | +| `audit` | `rust-ci.yml` | Cargo audit | 3m10s | +| `hex audit` | `elixir-ci.yml` | Hex package audit | (not shown in checks) | +| `Elixir build validation` | `build-validation.yml` | Elixir compile check | 1m33s | +| `Rust build validation` | `build-validation.yml` | Rust compile check | (merged into Rust build validation?) | + +**Issue:** The checks output shows `benchmarks compile` and `cargo audit` passing, but the `benchee scripts compile` and `hex audit` jobs from `elixir-ci.yml` may be: +1. Not running (path filters prevent them) +2. Running but not shown in GH PR checks UI +3. Queued behind other jobs + +--- + +## Root Cause Analysis + +### Current Workflow Structure in verisimdb + +``` +databases/verisimdb/.github/workflows/ +├── build-validation.yml # Quick build checks (Rust + Elixir) +├── rust-ci.yml # Full Rust CI (test, clippy, doc, audit, bench-compile) +├── elixir-ci.yml # Full Elixir CI (test, coverage, bench-compile, hex audit) +└── ... (other workflows) +``` + +### Overlap Analysis + +| Job | build-validation.yml | rust-ci.yml | elixir-ci.yml | +|-----|----------------------|-------------|---------------| +| Rust compile | ✅ `validate-rust` | ✅ `test` (implicit) | ❌ | +| Elixir compile | ✅ `validate-elixir` | ❌ | ✅ `build-test` | +| Rust benchmarks | ❌ | ✅ `bench-compile` | ❌ | +| Elixir benchee | ❌ | ❌ | ✅ `bench-compile` | +| Cargo audit | ❌ | ✅ `audit` | ❌ | +| Hex audit | ❌ | ❌ | ✅ `audit` | + +**Duplicate coverage:** Both `build-validation.yml` and language-specific CI workflows check compilation. + +--- + +## Solution Options + +### Option A: Delete build-validation.yml (RECOMMENDED) + +**Rationale:** `rust-ci.yml` and `elixir-ci.yml` already cover build validation. The `build-validation.yml` is redundant. + +**Changes:** +```bash +cd databases/verisimdb +rm .github/workflows/build-validation.yml +``` + +**Impact:** +- ✅ Eliminates duplicate `Rust build validation` + `Elixir build validation` jobs +- ✅ Saves ~2-3 minutes per PR +- ⚠️ Need to verify rust-ci + elixir-ci have equivalent coverage + +**Verification:** +- [ ] `rust-ci.yml` has `cargo check` or equivalent +- [ ] `elixir-ci.yml` has `mix compile` or equivalent +- [ ] Both run on all relevant branches + +### Option B: Merge build-validation into language workflows + +**Rationale:** Keep quick validation but merge into existing workflows. + +**Changes:** +- Add `build-validation` job to `rust-ci.yml` with path filters +- Add `build-validation` job to `elixir-ci.yml` with path filters +- Delete `build-validation.yml` + +**Impact:** Same savings, but keeps the validation concept. + +### Option C: Keep all, but add concurrency groups + +**Rationale:** If there's a reason to keep all three workflows separate. + +**Changes:** +- Add `concurrency:` groups to all workflows to prevent queuing +- Already present in rust-ci.yml and elixir-ci.yml +- Add to build-validation.yml: + ```yaml + concurrency: + group: build-validation-${{ github.ref }} + cancel-in-progress: true + ``` + +**Impact:** Minimal savings (still runs all jobs). + +--- + +## Recommended Action: Option A + +**Step 1:** Verify rust-ci.yml and elixir-ci.yml have build validation +```bash +# Check rust-ci.yml has cargo check +grep -n "cargo check\|cargo test\|cargo build" databases/verisimdb/.github/workflows/rust-ci.yml + +# Check elixir-ci.yml has mix compile +grep -n "mix compile\|mix test" databases/verisimdb/.github/workflows/elixir-ci.yml +``` + +**Step 2:** Delete build-validation.yml +```bash +rm databases/verisimdb/.github/workflows/build-validation.yml +``` + +**Step 3:** Commit and monitor PR #114 +```bash +cd databases/verisimdb +git add .github/workflows/build-validation.yml +git commit -m "ci: remove redundant build-validation.yml (covered by rust-ci + elixir-ci)" +git push +``` + +**Expected result:** PR #114 checks will show fewer jobs, complete faster. + +--- + +## Benchee + HexAudit Specifics + +### Current State in elixir-ci.yml + +```yaml +bench-compile: + name: benchee scripts compile + runs-on: ubuntu-latest + timeout-minutes: 10 + defaults: + run: + working-directory: elixir-orchestration + steps: + - uses: actions/checkout@v6 + - uses: erlef/setup-beam@v1 + - run: mix deps.get + - name: Syntax check all bench scripts + run: | + for f in bench/*.exs; do + elixir -e "Code.string_to_quoted!(File.read!(\"$f\"))" + echo " ✓ $f parses" + done + +audit: + name: hex audit + runs-on: ubuntu-latest + timeout-minutes: 10 + defaults: + run: + working-directory: elixir-orchestration + steps: + - uses: actions/checkout@v6 + - uses: erlef/setup-beam@v1 + - run: mix deps.get + - run: mix hex.audit + - run: mix deps.unlock --check-unused +``` + +### Issue: Path Filters Missing + +The `elixir-ci.yml` has path filters: +```yaml +on: + push: + paths: + - "elixir-orchestration/**" + - ".github/workflows/elixir-ci.yml" + pull_request: + paths: + - "elixir-orchestration/**" + - ".github/workflows/elixir-ci.yml" +``` + +**Problem:** If PR #114 doesn't modify files under `elixir-orchestration/`, the entire workflow (including benchee + hex audit) is **skipped**. + +**Check PR #114 files:** +```bash +# Get PR #114 changed files +gh pr view 114 --repo hyperpolymath/verisimdb --json files | jq -r '.files[].path' +``` + +If the PR only touches machine_readable/ files and not elixir-orchestration/, then: +- ✅ elixir-ci.yml is correctly skipped (path filters working) +- ✅ benchee + hex audit are NOT hanging — they're being skipped +- ❌ The "hanging" perception is actually correct behavior + +**Resolution:** The jobs aren't hanging — they're being skipped due to path filters. This is GOOD, not BAD. + +--- + +## Verification for PR #114 + +**Check what files changed:** +```bash +cd databases/verisimdb +gh pr diff 114 --name-only +``` + +**If no elixir-orchestration/ files changed:** +- elixir-ci.yml is correctly skipped +- benchee + hex audit jobs don't run +- This is **expected behavior**, not a bug + +**If elixir-orchestration/ files DID change:** +- Check if elixir-ci.yml jobs appear in PR checks +- If not, there's a different issue (permissions, syntax error, etc.) + +--- + +## Final Recommendation + +1. **For PR #114 specifically:** + - Verify if it modifies `elixir-orchestration/` files + - If NOT: elixir-ci.yml is correctly skipped (path filters working) + - If YES: Check workflow syntax and permissions + +2. **For estate-wide:** + - ✅ Delete `build-validation.yml` (redundant) + - ✅ Keep path filters in elixir-ci.yml (they're working correctly) + - ✅ Add similar path filters to rust-ci.yml + +3. **For verisimdb:** + - Delete `build-validation.yml` + - Add path filters to rust-ci.yml + - Result: Faster PRs, no duplicate jobs + +--- + +## Tasks + +### Task 6.1: Verify PR #114 file changes +- **Action:** Check if PR modifies elixir-orchestration/ or only machine_readable/ +- **Status:** TODO +- **Priority:** HIGH + +### Task 6.2: Delete build-validation.yml from verisimdb +- **Action:** `rm .github/workflows/build-validation.yml` +- **Status:** TODO +- **Priority:** HIGH + +### Task 6.3: Add path filters to rust-ci.yml in verisimdb +- **Action:** Add `paths:` filter matching elixir-ci.yml pattern +- **Status:** TODO +- **Priority:** MEDIUM + +### Task 6.4: Propagate fix estate-wide +- **Action:** Find all repos with both `build-validation.yml` and language-specific CI +- **Status:** TODO +- **Priority:** MEDIUM + +--- + +## Success Criteria + +- [ ] PR #114 shows clear, non-duplicate job names +- [ ] PR #114 completes in <10 minutes (currently ~15+ minutes) +- [ ] verisimdb has no build-validation.yml +- [ ] rust-ci.yml in verisimdb has path filters + +--- + +## Tags + +`cicd-optimization`, `verisimdb`, `redundancy`, `duplicate-jobs`, `path-filters`, `high-priority`, `track-1`, `pr-114` + +--- + +## Related + +- Roadmap: `2026-06-05-cicd-optimization-roadmap.md` +- Issue #001: Immediate Redundancy Elimination +- PR: hyperpolymath/verisimdb#114 diff --git a/.machine_readable/6a2/META.a2ml b/.machine_readable/6a2/META.a2ml index b7ff027c..6fc78bbc 100644 --- a/.machine_readable/6a2/META.a2ml +++ b/.machine_readable/6a2/META.a2ml @@ -12,7 +12,7 @@ version = "1.0.0" last-updated = "2026-05-15" [project-info] -license = "PMPL-1.0-or-later" +license = "MPL-2.0" author = "Jonathan D.A. Jewell (hyperpolymath)" [architecture-decisions] diff --git a/0-ai-gatekeeper-protocol/.machine_readable/6a2/META.a2ml b/0-ai-gatekeeper-protocol/.machine_readable/6a2/META.a2ml index 36c49567..adb7595c 100644 --- a/0-ai-gatekeeper-protocol/.machine_readable/6a2/META.a2ml +++ b/0-ai-gatekeeper-protocol/.machine_readable/6a2/META.a2ml @@ -7,7 +7,7 @@ version = "1.0.0" last-updated = "2026-04-11" [project-info] -license = "PMPL-1.0-or-later" +license = "MPL-2.0" author = "Jonathan D.A. Jewell (hyperpolymath)" [architecture-decisions] diff --git a/0-ai-gatekeeper-protocol/mcp-repo-guardian/.machine_readable/6a2/META.a2ml b/0-ai-gatekeeper-protocol/mcp-repo-guardian/.machine_readable/6a2/META.a2ml index 0377b7e2..ce79d14e 100644 --- a/0-ai-gatekeeper-protocol/mcp-repo-guardian/.machine_readable/6a2/META.a2ml +++ b/0-ai-gatekeeper-protocol/mcp-repo-guardian/.machine_readable/6a2/META.a2ml @@ -7,7 +7,7 @@ version = "1.0.0" last-updated = "2026-04-11" [project-info] -license = "PMPL-1.0-or-later" +license = "MPL-2.0" author = "Jonathan D.A. Jewell (hyperpolymath)" [architecture-decisions] diff --git a/0-ai-gatekeeper-protocol/repo-guardian-fs/.machine_readable/6a2/META.a2ml b/0-ai-gatekeeper-protocol/repo-guardian-fs/.machine_readable/6a2/META.a2ml index 1d1d5b66..36d00998 100644 --- a/0-ai-gatekeeper-protocol/repo-guardian-fs/.machine_readable/6a2/META.a2ml +++ b/0-ai-gatekeeper-protocol/repo-guardian-fs/.machine_readable/6a2/META.a2ml @@ -7,7 +7,7 @@ version = "1.0.0" last-updated = "2026-04-11" [project-info] -license = "PMPL-1.0-or-later" +license = "MPL-2.0" author = "Jonathan D.A. Jewell (hyperpolymath)" [architecture-decisions] diff --git a/GOVERNANCE.adoc b/GOVERNANCE.adoc new file mode 100644 index 00000000..e41020d3 --- /dev/null +++ b/GOVERNANCE.adoc @@ -0,0 +1,162 @@ +// 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 +|=== diff --git a/a2ml/actions/validate/flake.nix b/a2ml/actions/validate/flake.nix deleted file mode 100644 index 322a8aad..00000000 --- a/a2ml/actions/validate/flake.nix +++ /dev/null @@ -1,170 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -# -# Nix flake for a2ml-validate-action -# -# NOTE: guix.scm is the PRIMARY development environment. This flake is provided -# as a FALLBACK for contributors who use Nix instead of Guix. The .envrc checks -# for Guix first, then falls back to Nix. -# -# Usage: -# nix develop # Enter development shell -# nix build # Build the project -# nix flake check # Run checks -# nix flake show # Show flake outputs -# -# With direnv (.envrc already configured): -# direnv allow # Auto-enters shell on cd -# -# TODO: Replace a2ml-validate-action and with actual values. - -{ - description = "a2ml-validate-action — RSR-compliant project"; - - inputs = { - nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable"; - flake-utils.url = "github:numtide/flake-utils"; - }; - - outputs = { self, nixpkgs, flake-utils }: - flake-utils.lib.eachSystem [ "x86_64-linux" "aarch64-linux" ] (system: - let - pkgs = import nixpkgs { inherit system; }; - - # Common development tools present in every RSR project. - commonTools = with pkgs; [ - git - just - nickel - curl - bash - coreutils - ]; - - # --------------------------------------------------------------- - # Language-specific packages: uncomment the stacks you need. - # --------------------------------------------------------------- - # - # Rust: - # rustc cargo clippy rustfmt rust-analyzer - # - # Elixir: - # elixir erlang - # - # Gleam: - # gleam erlang - # - # Zig: - # zig zls - # - # Haskell: - # ghc cabal-install haskell-language-server - # - # Idris2: - # idris2 - # - # OCaml: - # ocaml dune_3 ocaml-lsp - # - # ReScript (via Deno): - # deno - # - # Julia: - # julia - # - # Ada/SPARK: - # gnat gprbuild - # - # --------------------------------------------------------------- - languageTools = with pkgs; [ - # TODO: Uncomment or add packages for your stack. - # Example for a Rust project: - # rustc - # cargo - # clippy - # rustfmt - # rust-analyzer - ]; - - in - { - # --------------------------------------------------------------- - # Development shell — `nix develop` - # --------------------------------------------------------------- - devShells.default = pkgs.mkShell { - name = "a2ml-validate-action-dev"; - - buildInputs = commonTools ++ languageTools; - - # Environment variables available inside the shell. - env = { - PROJECT_NAME = "a2ml-validate-action"; - RSR_TIER = "infrastructure"; - }; - - shellHook = '' - echo "" - echo " a2ml-validate-action — development shell" - echo " Nix: $(nix --version 2>/dev/null || echo 'unknown')" - echo " Just: $(just --version 2>/dev/null || echo 'not found')" - echo "" - echo " Run 'just' to see available recipes." - echo "" - - # Source .envrc manually when direnv is not managing the shell. - # This keeps project env vars (PROJECT_NAME, DATABASE_URL, etc.) - # consistent whether you enter via 'nix develop' or 'direnv allow'. - if [ -z "''${DIRENV_IN_ENVRC:-}" ] && [ -f .envrc ]; then - # Only source the non-nix parts to avoid recursion. - export PROJECT_NAME="a2ml-validate-action" - export RSR_TIER="infrastructure" - if [ -f .env ]; then - set -a - . .env - set +a - fi - fi - ''; - }; - - # --------------------------------------------------------------- - # Package — `nix build` - # --------------------------------------------------------------- - packages.default = pkgs.stdenv.mkDerivation { - pname = "a2ml-validate-action"; - version = "0.1.0"; - - src = self; - - # TODO: Replace with real build instructions. - # Examples: - # - # Rust (use rustPlatform.buildRustPackage instead of stdenv): - # packages.default = pkgs.rustPlatform.buildRustPackage { ... }; - # - # Elixir (use mixRelease): - # packages.default = pkgs.beamPackages.mixRelease { ... }; - # - # Zig: - # buildPhase = "zig build -Doptimize=ReleaseSafe"; - - buildPhase = '' - echo "TODO: Add build commands for a2ml-validate-action" - ''; - - installPhase = '' - mkdir -p $out/share/doc - cp README.adoc $out/share/doc/ 2>/dev/null || true - ''; - - meta = with pkgs.lib; { - description = ""; - homepage = "https://github.com/hyperpolymath/a2ml-validate-action"; - license = licenses.mpl20; # PMPL-1.0-or-later extends MPL-2.0 - maintainers = []; - platforms = [ "x86_64-linux" "aarch64-linux" ]; - }; - }; - } - ); -} diff --git a/a2ml/bindings/deno/flake.nix b/a2ml/bindings/deno/flake.nix deleted file mode 100644 index ded161e3..00000000 --- a/a2ml/bindings/deno/flake.nix +++ /dev/null @@ -1,170 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}> -# -# Nix flake for {{PROJECT_NAME}} -# -# NOTE: guix.scm is the PRIMARY development environment. This flake is provided -# as a FALLBACK for contributors who use Nix instead of Guix. The .envrc checks -# for Guix first, then falls back to Nix. -# -# Usage: -# nix develop # Enter development shell -# nix build # Build the project -# nix flake check # Run checks -# nix flake show # Show flake outputs -# -# With direnv (.envrc already configured): -# direnv allow # Auto-enters shell on cd -# -# TODO: Replace {{PROJECT_NAME}} and {{PROJECT_DESCRIPTION}} with actual values. - -{ - description = "{{PROJECT_NAME}} — RSR-compliant project"; - - inputs = { - nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable"; - flake-utils.url = "github:numtide/flake-utils"; - }; - - outputs = { self, nixpkgs, flake-utils }: - flake-utils.lib.eachSystem [ "x86_64-linux" "aarch64-linux" ] (system: - let - pkgs = import nixpkgs { inherit system; }; - - # Common development tools present in every RSR project. - commonTools = with pkgs; [ - git - just - nickel - curl - bash - coreutils - ]; - - # --------------------------------------------------------------- - # Language-specific packages: uncomment the stacks you need. - # --------------------------------------------------------------- - # - # Rust: - # rustc cargo clippy rustfmt rust-analyzer - # - # Elixir: - # elixir erlang - # - # Gleam: - # gleam erlang - # - # Zig: - # zig zls - # - # Haskell: - # ghc cabal-install haskell-language-server - # - # Idris2: - # idris2 - # - # OCaml: - # ocaml dune_3 ocaml-lsp - # - # ReScript (via Deno): - # deno - # - # Julia: - # julia - # - # Ada/SPARK: - # gnat gprbuild - # - # --------------------------------------------------------------- - languageTools = with pkgs; [ - # TODO: Uncomment or add packages for your stack. - # Example for a Rust project: - # rustc - # cargo - # clippy - # rustfmt - # rust-analyzer - ]; - - in - { - # --------------------------------------------------------------- - # Development shell — `nix develop` - # --------------------------------------------------------------- - devShells.default = pkgs.mkShell { - name = "{{PROJECT_NAME}}-dev"; - - buildInputs = commonTools ++ languageTools; - - # Environment variables available inside the shell. - env = { - PROJECT_NAME = "{{PROJECT_NAME}}"; - RSR_TIER = "infrastructure"; - }; - - shellHook = '' - echo "" - echo " {{PROJECT_NAME}} — development shell" - echo " Nix: $(nix --version 2>/dev/null || echo 'unknown')" - echo " Just: $(just --version 2>/dev/null || echo 'not found')" - echo "" - echo " Run 'just' to see available recipes." - echo "" - - # Source .envrc manually when direnv is not managing the shell. - # This keeps project env vars (PROJECT_NAME, DATABASE_URL, etc.) - # consistent whether you enter via 'nix develop' or 'direnv allow'. - if [ -z "''${DIRENV_IN_ENVRC:-}" ] && [ -f .envrc ]; then - # Only source the non-nix parts to avoid recursion. - export PROJECT_NAME="{{PROJECT_NAME}}" - export RSR_TIER="infrastructure" - if [ -f .env ]; then - set -a - . .env - set +a - fi - fi - ''; - }; - - # --------------------------------------------------------------- - # Package — `nix build` - # --------------------------------------------------------------- - packages.default = pkgs.stdenv.mkDerivation { - pname = "{{PROJECT_NAME}}"; - version = "0.1.0"; - - src = self; - - # TODO: Replace with real build instructions. - # Examples: - # - # Rust (use rustPlatform.buildRustPackage instead of stdenv): - # packages.default = pkgs.rustPlatform.buildRustPackage { ... }; - # - # Elixir (use mixRelease): - # packages.default = pkgs.beamPackages.mixRelease { ... }; - # - # Zig: - # buildPhase = "zig build -Doptimize=ReleaseSafe"; - - buildPhase = '' - echo "TODO: Add build commands for {{PROJECT_NAME}}" - ''; - - installPhase = '' - mkdir -p $out/share/doc - cp README.adoc $out/share/doc/ 2>/dev/null || true - ''; - - meta = with pkgs.lib; { - description = "{{PROJECT_DESCRIPTION}}"; - homepage = "https://github.com/{{OWNER}}/{{PROJECT_NAME}}"; - license = licenses.mpl20; # PMPL-1.0-or-later extends MPL-2.0 - maintainers = []; - platforms = [ "x86_64-linux" "aarch64-linux" ]; - }; - }; - } - ); -} diff --git a/a2ml/bindings/haskell/flake.nix b/a2ml/bindings/haskell/flake.nix deleted file mode 100644 index ded161e3..00000000 --- a/a2ml/bindings/haskell/flake.nix +++ /dev/null @@ -1,170 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}> -# -# Nix flake for {{PROJECT_NAME}} -# -# NOTE: guix.scm is the PRIMARY development environment. This flake is provided -# as a FALLBACK for contributors who use Nix instead of Guix. The .envrc checks -# for Guix first, then falls back to Nix. -# -# Usage: -# nix develop # Enter development shell -# nix build # Build the project -# nix flake check # Run checks -# nix flake show # Show flake outputs -# -# With direnv (.envrc already configured): -# direnv allow # Auto-enters shell on cd -# -# TODO: Replace {{PROJECT_NAME}} and {{PROJECT_DESCRIPTION}} with actual values. - -{ - description = "{{PROJECT_NAME}} — RSR-compliant project"; - - inputs = { - nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable"; - flake-utils.url = "github:numtide/flake-utils"; - }; - - outputs = { self, nixpkgs, flake-utils }: - flake-utils.lib.eachSystem [ "x86_64-linux" "aarch64-linux" ] (system: - let - pkgs = import nixpkgs { inherit system; }; - - # Common development tools present in every RSR project. - commonTools = with pkgs; [ - git - just - nickel - curl - bash - coreutils - ]; - - # --------------------------------------------------------------- - # Language-specific packages: uncomment the stacks you need. - # --------------------------------------------------------------- - # - # Rust: - # rustc cargo clippy rustfmt rust-analyzer - # - # Elixir: - # elixir erlang - # - # Gleam: - # gleam erlang - # - # Zig: - # zig zls - # - # Haskell: - # ghc cabal-install haskell-language-server - # - # Idris2: - # idris2 - # - # OCaml: - # ocaml dune_3 ocaml-lsp - # - # ReScript (via Deno): - # deno - # - # Julia: - # julia - # - # Ada/SPARK: - # gnat gprbuild - # - # --------------------------------------------------------------- - languageTools = with pkgs; [ - # TODO: Uncomment or add packages for your stack. - # Example for a Rust project: - # rustc - # cargo - # clippy - # rustfmt - # rust-analyzer - ]; - - in - { - # --------------------------------------------------------------- - # Development shell — `nix develop` - # --------------------------------------------------------------- - devShells.default = pkgs.mkShell { - name = "{{PROJECT_NAME}}-dev"; - - buildInputs = commonTools ++ languageTools; - - # Environment variables available inside the shell. - env = { - PROJECT_NAME = "{{PROJECT_NAME}}"; - RSR_TIER = "infrastructure"; - }; - - shellHook = '' - echo "" - echo " {{PROJECT_NAME}} — development shell" - echo " Nix: $(nix --version 2>/dev/null || echo 'unknown')" - echo " Just: $(just --version 2>/dev/null || echo 'not found')" - echo "" - echo " Run 'just' to see available recipes." - echo "" - - # Source .envrc manually when direnv is not managing the shell. - # This keeps project env vars (PROJECT_NAME, DATABASE_URL, etc.) - # consistent whether you enter via 'nix develop' or 'direnv allow'. - if [ -z "''${DIRENV_IN_ENVRC:-}" ] && [ -f .envrc ]; then - # Only source the non-nix parts to avoid recursion. - export PROJECT_NAME="{{PROJECT_NAME}}" - export RSR_TIER="infrastructure" - if [ -f .env ]; then - set -a - . .env - set +a - fi - fi - ''; - }; - - # --------------------------------------------------------------- - # Package — `nix build` - # --------------------------------------------------------------- - packages.default = pkgs.stdenv.mkDerivation { - pname = "{{PROJECT_NAME}}"; - version = "0.1.0"; - - src = self; - - # TODO: Replace with real build instructions. - # Examples: - # - # Rust (use rustPlatform.buildRustPackage instead of stdenv): - # packages.default = pkgs.rustPlatform.buildRustPackage { ... }; - # - # Elixir (use mixRelease): - # packages.default = pkgs.beamPackages.mixRelease { ... }; - # - # Zig: - # buildPhase = "zig build -Doptimize=ReleaseSafe"; - - buildPhase = '' - echo "TODO: Add build commands for {{PROJECT_NAME}}" - ''; - - installPhase = '' - mkdir -p $out/share/doc - cp README.adoc $out/share/doc/ 2>/dev/null || true - ''; - - meta = with pkgs.lib; { - description = "{{PROJECT_DESCRIPTION}}"; - homepage = "https://github.com/{{OWNER}}/{{PROJECT_NAME}}"; - license = licenses.mpl20; # PMPL-1.0-or-later extends MPL-2.0 - maintainers = []; - platforms = [ "x86_64-linux" "aarch64-linux" ]; - }; - }; - } - ); -} diff --git a/a2ml/bindings/rust/flake.nix b/a2ml/bindings/rust/flake.nix deleted file mode 100644 index ded161e3..00000000 --- a/a2ml/bindings/rust/flake.nix +++ /dev/null @@ -1,170 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}> -# -# Nix flake for {{PROJECT_NAME}} -# -# NOTE: guix.scm is the PRIMARY development environment. This flake is provided -# as a FALLBACK for contributors who use Nix instead of Guix. The .envrc checks -# for Guix first, then falls back to Nix. -# -# Usage: -# nix develop # Enter development shell -# nix build # Build the project -# nix flake check # Run checks -# nix flake show # Show flake outputs -# -# With direnv (.envrc already configured): -# direnv allow # Auto-enters shell on cd -# -# TODO: Replace {{PROJECT_NAME}} and {{PROJECT_DESCRIPTION}} with actual values. - -{ - description = "{{PROJECT_NAME}} — RSR-compliant project"; - - inputs = { - nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable"; - flake-utils.url = "github:numtide/flake-utils"; - }; - - outputs = { self, nixpkgs, flake-utils }: - flake-utils.lib.eachSystem [ "x86_64-linux" "aarch64-linux" ] (system: - let - pkgs = import nixpkgs { inherit system; }; - - # Common development tools present in every RSR project. - commonTools = with pkgs; [ - git - just - nickel - curl - bash - coreutils - ]; - - # --------------------------------------------------------------- - # Language-specific packages: uncomment the stacks you need. - # --------------------------------------------------------------- - # - # Rust: - # rustc cargo clippy rustfmt rust-analyzer - # - # Elixir: - # elixir erlang - # - # Gleam: - # gleam erlang - # - # Zig: - # zig zls - # - # Haskell: - # ghc cabal-install haskell-language-server - # - # Idris2: - # idris2 - # - # OCaml: - # ocaml dune_3 ocaml-lsp - # - # ReScript (via Deno): - # deno - # - # Julia: - # julia - # - # Ada/SPARK: - # gnat gprbuild - # - # --------------------------------------------------------------- - languageTools = with pkgs; [ - # TODO: Uncomment or add packages for your stack. - # Example for a Rust project: - # rustc - # cargo - # clippy - # rustfmt - # rust-analyzer - ]; - - in - { - # --------------------------------------------------------------- - # Development shell — `nix develop` - # --------------------------------------------------------------- - devShells.default = pkgs.mkShell { - name = "{{PROJECT_NAME}}-dev"; - - buildInputs = commonTools ++ languageTools; - - # Environment variables available inside the shell. - env = { - PROJECT_NAME = "{{PROJECT_NAME}}"; - RSR_TIER = "infrastructure"; - }; - - shellHook = '' - echo "" - echo " {{PROJECT_NAME}} — development shell" - echo " Nix: $(nix --version 2>/dev/null || echo 'unknown')" - echo " Just: $(just --version 2>/dev/null || echo 'not found')" - echo "" - echo " Run 'just' to see available recipes." - echo "" - - # Source .envrc manually when direnv is not managing the shell. - # This keeps project env vars (PROJECT_NAME, DATABASE_URL, etc.) - # consistent whether you enter via 'nix develop' or 'direnv allow'. - if [ -z "''${DIRENV_IN_ENVRC:-}" ] && [ -f .envrc ]; then - # Only source the non-nix parts to avoid recursion. - export PROJECT_NAME="{{PROJECT_NAME}}" - export RSR_TIER="infrastructure" - if [ -f .env ]; then - set -a - . .env - set +a - fi - fi - ''; - }; - - # --------------------------------------------------------------- - # Package — `nix build` - # --------------------------------------------------------------- - packages.default = pkgs.stdenv.mkDerivation { - pname = "{{PROJECT_NAME}}"; - version = "0.1.0"; - - src = self; - - # TODO: Replace with real build instructions. - # Examples: - # - # Rust (use rustPlatform.buildRustPackage instead of stdenv): - # packages.default = pkgs.rustPlatform.buildRustPackage { ... }; - # - # Elixir (use mixRelease): - # packages.default = pkgs.beamPackages.mixRelease { ... }; - # - # Zig: - # buildPhase = "zig build -Doptimize=ReleaseSafe"; - - buildPhase = '' - echo "TODO: Add build commands for {{PROJECT_NAME}}" - ''; - - installPhase = '' - mkdir -p $out/share/doc - cp README.adoc $out/share/doc/ 2>/dev/null || true - ''; - - meta = with pkgs.lib; { - description = "{{PROJECT_DESCRIPTION}}"; - homepage = "https://github.com/{{OWNER}}/{{PROJECT_NAME}}"; - license = licenses.mpl20; # PMPL-1.0-or-later extends MPL-2.0 - maintainers = []; - platforms = [ "x86_64-linux" "aarch64-linux" ]; - }; - }; - } - ); -} diff --git a/a2ml/docs/paper/manifest.scm b/a2ml/docs/paper/manifest.scm new file mode 100644 index 00000000..dd942c7f --- /dev/null +++ b/a2ml/docs/paper/manifest.scm @@ -0,0 +1,24 @@ +;;; SPDX-License-Identifier: MPL-2.0 +;;; manifest.scm — Generic Guix manifest for RSR-compliant projects +;;; +;;; Usage: +;;; guix shell -m manifest.scm +;;; + +(specifications->manifest + '(;; Core development tools + "git" + "just" + "nickel" + "curl" + "bash" + "coreutils" + + ;; Documentation + "asciidoctor" + "pandoc" + + ;; Common build dependencies + "openssl" + "zlib" + "pkg-config")) diff --git a/a2ml/editors/vscode/flake.nix b/a2ml/editors/vscode/flake.nix deleted file mode 100644 index ded161e3..00000000 --- a/a2ml/editors/vscode/flake.nix +++ /dev/null @@ -1,170 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}> -# -# Nix flake for {{PROJECT_NAME}} -# -# NOTE: guix.scm is the PRIMARY development environment. This flake is provided -# as a FALLBACK for contributors who use Nix instead of Guix. The .envrc checks -# for Guix first, then falls back to Nix. -# -# Usage: -# nix develop # Enter development shell -# nix build # Build the project -# nix flake check # Run checks -# nix flake show # Show flake outputs -# -# With direnv (.envrc already configured): -# direnv allow # Auto-enters shell on cd -# -# TODO: Replace {{PROJECT_NAME}} and {{PROJECT_DESCRIPTION}} with actual values. - -{ - description = "{{PROJECT_NAME}} — RSR-compliant project"; - - inputs = { - nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable"; - flake-utils.url = "github:numtide/flake-utils"; - }; - - outputs = { self, nixpkgs, flake-utils }: - flake-utils.lib.eachSystem [ "x86_64-linux" "aarch64-linux" ] (system: - let - pkgs = import nixpkgs { inherit system; }; - - # Common development tools present in every RSR project. - commonTools = with pkgs; [ - git - just - nickel - curl - bash - coreutils - ]; - - # --------------------------------------------------------------- - # Language-specific packages: uncomment the stacks you need. - # --------------------------------------------------------------- - # - # Rust: - # rustc cargo clippy rustfmt rust-analyzer - # - # Elixir: - # elixir erlang - # - # Gleam: - # gleam erlang - # - # Zig: - # zig zls - # - # Haskell: - # ghc cabal-install haskell-language-server - # - # Idris2: - # idris2 - # - # OCaml: - # ocaml dune_3 ocaml-lsp - # - # ReScript (via Deno): - # deno - # - # Julia: - # julia - # - # Ada/SPARK: - # gnat gprbuild - # - # --------------------------------------------------------------- - languageTools = with pkgs; [ - # TODO: Uncomment or add packages for your stack. - # Example for a Rust project: - # rustc - # cargo - # clippy - # rustfmt - # rust-analyzer - ]; - - in - { - # --------------------------------------------------------------- - # Development shell — `nix develop` - # --------------------------------------------------------------- - devShells.default = pkgs.mkShell { - name = "{{PROJECT_NAME}}-dev"; - - buildInputs = commonTools ++ languageTools; - - # Environment variables available inside the shell. - env = { - PROJECT_NAME = "{{PROJECT_NAME}}"; - RSR_TIER = "infrastructure"; - }; - - shellHook = '' - echo "" - echo " {{PROJECT_NAME}} — development shell" - echo " Nix: $(nix --version 2>/dev/null || echo 'unknown')" - echo " Just: $(just --version 2>/dev/null || echo 'not found')" - echo "" - echo " Run 'just' to see available recipes." - echo "" - - # Source .envrc manually when direnv is not managing the shell. - # This keeps project env vars (PROJECT_NAME, DATABASE_URL, etc.) - # consistent whether you enter via 'nix develop' or 'direnv allow'. - if [ -z "''${DIRENV_IN_ENVRC:-}" ] && [ -f .envrc ]; then - # Only source the non-nix parts to avoid recursion. - export PROJECT_NAME="{{PROJECT_NAME}}" - export RSR_TIER="infrastructure" - if [ -f .env ]; then - set -a - . .env - set +a - fi - fi - ''; - }; - - # --------------------------------------------------------------- - # Package — `nix build` - # --------------------------------------------------------------- - packages.default = pkgs.stdenv.mkDerivation { - pname = "{{PROJECT_NAME}}"; - version = "0.1.0"; - - src = self; - - # TODO: Replace with real build instructions. - # Examples: - # - # Rust (use rustPlatform.buildRustPackage instead of stdenv): - # packages.default = pkgs.rustPlatform.buildRustPackage { ... }; - # - # Elixir (use mixRelease): - # packages.default = pkgs.beamPackages.mixRelease { ... }; - # - # Zig: - # buildPhase = "zig build -Doptimize=ReleaseSafe"; - - buildPhase = '' - echo "TODO: Add build commands for {{PROJECT_NAME}}" - ''; - - installPhase = '' - mkdir -p $out/share/doc - cp README.adoc $out/share/doc/ 2>/dev/null || true - ''; - - meta = with pkgs.lib; { - description = "{{PROJECT_DESCRIPTION}}"; - homepage = "https://github.com/{{OWNER}}/{{PROJECT_NAME}}"; - license = licenses.mpl20; # PMPL-1.0-or-later extends MPL-2.0 - maintainers = []; - platforms = [ "x86_64-linux" "aarch64-linux" ]; - }; - }; - } - ); -} diff --git a/a2ml/manifest.scm b/a2ml/manifest.scm new file mode 100644 index 00000000..dd942c7f --- /dev/null +++ b/a2ml/manifest.scm @@ -0,0 +1,24 @@ +;;; SPDX-License-Identifier: MPL-2.0 +;;; manifest.scm — Generic Guix manifest for RSR-compliant projects +;;; +;;; Usage: +;;; guix shell -m manifest.scm +;;; + +(specifications->manifest + '(;; Core development tools + "git" + "just" + "nickel" + "curl" + "bash" + "coreutils" + + ;; Documentation + "asciidoctor" + "pandoc" + + ;; Common build dependencies + "openssl" + "zlib" + "pkg-config")) diff --git a/a2ml/pandoc/flake.nix b/a2ml/pandoc/flake.nix deleted file mode 100644 index ded161e3..00000000 --- a/a2ml/pandoc/flake.nix +++ /dev/null @@ -1,170 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}> -# -# Nix flake for {{PROJECT_NAME}} -# -# NOTE: guix.scm is the PRIMARY development environment. This flake is provided -# as a FALLBACK for contributors who use Nix instead of Guix. The .envrc checks -# for Guix first, then falls back to Nix. -# -# Usage: -# nix develop # Enter development shell -# nix build # Build the project -# nix flake check # Run checks -# nix flake show # Show flake outputs -# -# With direnv (.envrc already configured): -# direnv allow # Auto-enters shell on cd -# -# TODO: Replace {{PROJECT_NAME}} and {{PROJECT_DESCRIPTION}} with actual values. - -{ - description = "{{PROJECT_NAME}} — RSR-compliant project"; - - inputs = { - nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable"; - flake-utils.url = "github:numtide/flake-utils"; - }; - - outputs = { self, nixpkgs, flake-utils }: - flake-utils.lib.eachSystem [ "x86_64-linux" "aarch64-linux" ] (system: - let - pkgs = import nixpkgs { inherit system; }; - - # Common development tools present in every RSR project. - commonTools = with pkgs; [ - git - just - nickel - curl - bash - coreutils - ]; - - # --------------------------------------------------------------- - # Language-specific packages: uncomment the stacks you need. - # --------------------------------------------------------------- - # - # Rust: - # rustc cargo clippy rustfmt rust-analyzer - # - # Elixir: - # elixir erlang - # - # Gleam: - # gleam erlang - # - # Zig: - # zig zls - # - # Haskell: - # ghc cabal-install haskell-language-server - # - # Idris2: - # idris2 - # - # OCaml: - # ocaml dune_3 ocaml-lsp - # - # ReScript (via Deno): - # deno - # - # Julia: - # julia - # - # Ada/SPARK: - # gnat gprbuild - # - # --------------------------------------------------------------- - languageTools = with pkgs; [ - # TODO: Uncomment or add packages for your stack. - # Example for a Rust project: - # rustc - # cargo - # clippy - # rustfmt - # rust-analyzer - ]; - - in - { - # --------------------------------------------------------------- - # Development shell — `nix develop` - # --------------------------------------------------------------- - devShells.default = pkgs.mkShell { - name = "{{PROJECT_NAME}}-dev"; - - buildInputs = commonTools ++ languageTools; - - # Environment variables available inside the shell. - env = { - PROJECT_NAME = "{{PROJECT_NAME}}"; - RSR_TIER = "infrastructure"; - }; - - shellHook = '' - echo "" - echo " {{PROJECT_NAME}} — development shell" - echo " Nix: $(nix --version 2>/dev/null || echo 'unknown')" - echo " Just: $(just --version 2>/dev/null || echo 'not found')" - echo "" - echo " Run 'just' to see available recipes." - echo "" - - # Source .envrc manually when direnv is not managing the shell. - # This keeps project env vars (PROJECT_NAME, DATABASE_URL, etc.) - # consistent whether you enter via 'nix develop' or 'direnv allow'. - if [ -z "''${DIRENV_IN_ENVRC:-}" ] && [ -f .envrc ]; then - # Only source the non-nix parts to avoid recursion. - export PROJECT_NAME="{{PROJECT_NAME}}" - export RSR_TIER="infrastructure" - if [ -f .env ]; then - set -a - . .env - set +a - fi - fi - ''; - }; - - # --------------------------------------------------------------- - # Package — `nix build` - # --------------------------------------------------------------- - packages.default = pkgs.stdenv.mkDerivation { - pname = "{{PROJECT_NAME}}"; - version = "0.1.0"; - - src = self; - - # TODO: Replace with real build instructions. - # Examples: - # - # Rust (use rustPlatform.buildRustPackage instead of stdenv): - # packages.default = pkgs.rustPlatform.buildRustPackage { ... }; - # - # Elixir (use mixRelease): - # packages.default = pkgs.beamPackages.mixRelease { ... }; - # - # Zig: - # buildPhase = "zig build -Doptimize=ReleaseSafe"; - - buildPhase = '' - echo "TODO: Add build commands for {{PROJECT_NAME}}" - ''; - - installPhase = '' - mkdir -p $out/share/doc - cp README.adoc $out/share/doc/ 2>/dev/null || true - ''; - - meta = with pkgs.lib; { - description = "{{PROJECT_DESCRIPTION}}"; - homepage = "https://github.com/{{OWNER}}/{{PROJECT_NAME}}"; - license = licenses.mpl20; # PMPL-1.0-or-later extends MPL-2.0 - maintainers = []; - platforms = [ "x86_64-linux" "aarch64-linux" ]; - }; - }; - } - ); -} diff --git a/agentic-a2ml/.machine_readable/6a2/META.a2ml b/agentic-a2ml/.machine_readable/6a2/META.a2ml index aa69bacc..ce016642 100644 --- a/agentic-a2ml/.machine_readable/6a2/META.a2ml +++ b/agentic-a2ml/.machine_readable/6a2/META.a2ml @@ -7,7 +7,7 @@ version = "0.1.0" last-updated = "2026-04-11" [project-info] -license = "PMPL-1.0-or-later" +license = "MPL-2.0" author = "Jonathan D.A. Jewell (hyperpolymath)" [architecture-decisions] diff --git a/anchor-a2ml/.machine_readable/6a2/META.a2ml b/anchor-a2ml/.machine_readable/6a2/META.a2ml index 3aef2fb8..0c375aeb 100644 --- a/anchor-a2ml/.machine_readable/6a2/META.a2ml +++ b/anchor-a2ml/.machine_readable/6a2/META.a2ml @@ -7,7 +7,7 @@ version = "0.1.0" last-updated = "2026-04-11" [project-info] -license = "PMPL-1.0-or-later" +license = "MPL-2.0" author = "Jonathan D.A. Jewell (hyperpolymath)" [architecture-decisions] diff --git a/avow-protocol/.machine_readable/6a2/META.a2ml b/avow-protocol/.machine_readable/6a2/META.a2ml index f6b8250f..8fadcdd8 100644 --- a/avow-protocol/.machine_readable/6a2/META.a2ml +++ b/avow-protocol/.machine_readable/6a2/META.a2ml @@ -7,7 +7,7 @@ version = "0.1.0" last-updated = "2026-04-11" [project-info] -license = "PMPL-1.0-or-later" +license = "MPL-2.0" author = "Jonathan D.A. Jewell (hyperpolymath)" [architecture-decisions] diff --git a/avow-protocol/avow-lib/.machine_readable/6a2/META.a2ml b/avow-protocol/avow-lib/.machine_readable/6a2/META.a2ml index c741d789..5e86ce12 100644 --- a/avow-protocol/avow-lib/.machine_readable/6a2/META.a2ml +++ b/avow-protocol/avow-lib/.machine_readable/6a2/META.a2ml @@ -7,7 +7,7 @@ version = "0.1.0" last-updated = "2026-04-11" [project-info] -license = "PMPL-1.0-or-later" +license = "MPL-2.0" author = "Jonathan D.A. Jewell (hyperpolymath)" [architecture-decisions] diff --git a/axel-protocol/.machine_readable/6a2/META.a2ml b/axel-protocol/.machine_readable/6a2/META.a2ml index da43d2ef..9b7f874d 100644 --- a/axel-protocol/.machine_readable/6a2/META.a2ml +++ b/axel-protocol/.machine_readable/6a2/META.a2ml @@ -7,7 +7,7 @@ version = "1.0" last-updated = "2026-04-11" [project-info] -license = "PMPL-1.0-or-later" +license = "MPL-2.0" author = "Jonathan D.A. Jewell (hyperpolymath)" [architecture-decisions] diff --git a/consent-aware-http/manifest.scm b/consent-aware-http/manifest.scm new file mode 100644 index 00000000..dd942c7f --- /dev/null +++ b/consent-aware-http/manifest.scm @@ -0,0 +1,24 @@ +;;; SPDX-License-Identifier: MPL-2.0 +;;; manifest.scm — Generic Guix manifest for RSR-compliant projects +;;; +;;; Usage: +;;; guix shell -m manifest.scm +;;; + +(specifications->manifest + '(;; Core development tools + "git" + "just" + "nickel" + "curl" + "bash" + "coreutils" + + ;; Documentation + "asciidoctor" + "pandoc" + + ;; Common build dependencies + "openssl" + "zlib" + "pkg-config")) diff --git a/docs/decisions/2026-06-06-hypatia-estate-control-plane.md b/docs/decisions/2026-06-06-hypatia-estate-control-plane.md new file mode 100644 index 00000000..f8b7fde9 --- /dev/null +++ b/docs/decisions/2026-06-06-hypatia-estate-control-plane.md @@ -0,0 +1,82 @@ +// SPDX-License-Identifier: MPL-2.0 +// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell + +# Decision: Hypatia As Estate Control-Plane Observer + +Date: 2026-06-06 + +Status: proposed + +## Context + +The standards repository owns reusable workflow glue that many repositories in +the estate consume. During the `echidna` Hypatia triage, a key failure mode was +not in the source repo itself: the standards reusable Hypatia workflow carried +an embedded SARIF converter that could diverge from Hypatia's native SARIF +renderer. That converter was part of a self-echo path in which Hypatia could +read GitHub code-scanning alerts and then re-upload mirror findings as new +Hypatia alerts. + +The standards layer is therefore not passive documentation. It is estate +control-plane infrastructure. + +Related issue: + +## Decision + +Standards should treat reusable workflows, embedded converters, SARIF +categories, and bot/farm interfaces as control-plane components. They must +preserve scanner semantics rather than re-implementing them in ways that drift. + +For Hypatia integration this means: + +- prefer Hypatia's native SARIF renderer when practical; +- when an embedded converter is needed, mirror Hypatia's meta-rule suppression; +- include machine-readable metadata: finding ID, category, class, route, and + dispatch safety; +- keep empty SARIF upload behavior so stale alerts can clear; +- document the route from reusable workflow to GitHub code scanning to + gitbot-fleet and `.git-private-farm`. + +## Estate Roles + +| Component | Role | +| --- | --- | +| Hypatia | Observe repo and environment; classify findings; produce work orders | +| standards | Provide reusable workflow and reporting surfaces; prevent converter drift | +| echidna | Concrete repository under triage; source of deposited evidence reports | +| gitbot-fleet | Bot intake and PR/review execution | +| `.git-private-farm` | Rate-limited estate fanout and canary orchestration | +| repossystem | Portfolio map tying repos, workflows, bots, and control surfaces together | + +## Rules For Reusable Workflows + +Reusable workflows should be conservative: + +- no direct destructive action; +- no new auto-execute route without canary and rollback; +- no unstructured scanner output if structured metadata is available; +- no duplication of a scanner's public alert surface without dedupe; +- no silent failure of the reporting path; +- no mass fanout from a newly introduced rule. + +## Action Economy + +The standards layer should help preserve GitHub Actions credit and human +attention: + +- if CodeQL, Scorecard, Dependabot, governance, or Hypatia is already running, + downstream agents should be able to wait for and consume the result; +- if another tool is better suited to a finding, Hypatia should be able to hand + off or reformat the finding for that tool; +- if another tool is producing a bad or incomplete fix, Hypatia should hold or + route the work for review; +- repeated findings should dedupe by stable ID, not re-open equivalent work. + +## Implication For `Git in the Time of NeSy Agency` + +This decision frames the estate as a NeSy agency portfolio rather than a set of +independent repos. The standards repo provides common reflexes; Hypatia provides +environment-aware observation; the fleet and farm provide controlled action. +The book should treat this as a nervous-system/control-plane pattern: observe, +classify, route, wait or act, verify, and learn. diff --git a/flake.lock b/flake.lock deleted file mode 100644 index 4cee253d..00000000 --- a/flake.lock +++ /dev/null @@ -1,61 +0,0 @@ -{ - "nodes": { - "flake-utils": { - "inputs": { - "systems": "systems" - }, - "locked": { - "lastModified": 1731533236, - "narHash": "sha256-l0KFg5HjrsfsO/JpG+r7fRrqm12kzFHyUHqHCVpMMbI=", - "owner": "numtide", - "repo": "flake-utils", - "rev": "11707dc2f618dd54ca8739b309ec4fc024de578b", - "type": "github" - }, - "original": { - "owner": "numtide", - "repo": "flake-utils", - "type": "github" - } - }, - "nixpkgs": { - "locked": { - "lastModified": 1776169885, - "narHash": "sha256-l/iNYDZ4bGOAFQY2q8y5OAfBBtrDAaPuRQqWaFHVRXM=", - "owner": "NixOS", - "repo": "nixpkgs", - "rev": "4bd9165a9165d7b5e33ae57f3eecbcb28fb231c9", - "type": "github" - }, - "original": { - "owner": "NixOS", - "ref": "nixos-unstable", - "repo": "nixpkgs", - "type": "github" - } - }, - "root": { - "inputs": { - "flake-utils": "flake-utils", - "nixpkgs": "nixpkgs" - } - }, - "systems": { - "locked": { - "lastModified": 1681028828, - "narHash": "sha256-Vy1rq5AaRuLzOxct8nz4T6wlgyUR7zLU309k9mBC768=", - "owner": "nix-systems", - "repo": "default", - "rev": "da67096a3b9bf56a91d16901293e51ba5b49a27e", - "type": "github" - }, - "original": { - "owner": "nix-systems", - "repo": "default", - "type": "github" - } - } - }, - "root": "root", - "version": 7 -} diff --git a/flake.nix b/flake.nix deleted file mode 100644 index 9f5b10bb..00000000 --- a/flake.nix +++ /dev/null @@ -1,35 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -# -# Nix flake development environment for standards. -# Usage: nix develop -{ - description = "Hyperpolymath standards — A2ML, K9, Axel, Groove, eNSAID"; - - inputs = { - nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable"; - flake-utils.url = "github:numtide/flake-utils"; - }; - - outputs = { self, nixpkgs, flake-utils }: - flake-utils.lib.eachDefaultSystem (system: - let pkgs = nixpkgs.legacyPackages.${system}; - in { - devShells.default = pkgs.mkShell { - buildInputs = with pkgs; [ - # Deno — runtime for standard tooling and validators - deno - - # Nickel — configuration language for eNSAID - nickel - - # Build tooling - gnumake - ]; - - shellHook = '' - echo "standards dev shell — deno + nickel" - ''; - }; - }); -} diff --git a/k9-svc/actions/validate/.machine_readable/6a2/META.a2ml b/k9-svc/actions/validate/.machine_readable/6a2/META.a2ml index 9dbb4d71..a7d64e31 100644 --- a/k9-svc/actions/validate/.machine_readable/6a2/META.a2ml +++ b/k9-svc/actions/validate/.machine_readable/6a2/META.a2ml @@ -11,7 +11,7 @@ last-updated = "2026-03-16" [project-info] type = "infrastructure" # library | binary | monorepo | service | website languages = [] # e.g. ["rust", "zig", "idris2"] -license = "PMPL-1.0-or-later" +license = "MPL-2.0" author = "Jonathan D.A. Jewell (hyperpolymath)" [architecture-decisions] diff --git a/k9-svc/actions/validate/flake.nix b/k9-svc/actions/validate/flake.nix deleted file mode 100644 index c12c367f..00000000 --- a/k9-svc/actions/validate/flake.nix +++ /dev/null @@ -1,170 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -# -# Nix flake for k9-validate-action -# -# NOTE: guix.scm is the PRIMARY development environment. This flake is provided -# as a FALLBACK for contributors who use Nix instead of Guix. The .envrc checks -# for Guix first, then falls back to Nix. -# -# Usage: -# nix develop # Enter development shell -# nix build # Build the project -# nix flake check # Run checks -# nix flake show # Show flake outputs -# -# With direnv (.envrc already configured): -# direnv allow # Auto-enters shell on cd -# -# TODO: Replace k9-validate-action and with actual values. - -{ - description = "k9-validate-action — RSR-compliant project"; - - inputs = { - nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable"; - flake-utils.url = "github:numtide/flake-utils"; - }; - - outputs = { self, nixpkgs, flake-utils }: - flake-utils.lib.eachSystem [ "x86_64-linux" "aarch64-linux" ] (system: - let - pkgs = import nixpkgs { inherit system; }; - - # Common development tools present in every RSR project. - commonTools = with pkgs; [ - git - just - nickel - curl - bash - coreutils - ]; - - # --------------------------------------------------------------- - # Language-specific packages: uncomment the stacks you need. - # --------------------------------------------------------------- - # - # Rust: - # rustc cargo clippy rustfmt rust-analyzer - # - # Elixir: - # elixir erlang - # - # Gleam: - # gleam erlang - # - # Zig: - # zig zls - # - # Haskell: - # ghc cabal-install haskell-language-server - # - # Idris2: - # idris2 - # - # OCaml: - # ocaml dune_3 ocaml-lsp - # - # ReScript (via Deno): - # deno - # - # Julia: - # julia - # - # Ada/SPARK: - # gnat gprbuild - # - # --------------------------------------------------------------- - languageTools = with pkgs; [ - # TODO: Uncomment or add packages for your stack. - # Example for a Rust project: - # rustc - # cargo - # clippy - # rustfmt - # rust-analyzer - ]; - - in - { - # --------------------------------------------------------------- - # Development shell — `nix develop` - # --------------------------------------------------------------- - devShells.default = pkgs.mkShell { - name = "k9-validate-action-dev"; - - buildInputs = commonTools ++ languageTools; - - # Environment variables available inside the shell. - env = { - PROJECT_NAME = "k9-validate-action"; - RSR_TIER = "infrastructure"; - }; - - shellHook = '' - echo "" - echo " k9-validate-action — development shell" - echo " Nix: $(nix --version 2>/dev/null || echo 'unknown')" - echo " Just: $(just --version 2>/dev/null || echo 'not found')" - echo "" - echo " Run 'just' to see available recipes." - echo "" - - # Source .envrc manually when direnv is not managing the shell. - # This keeps project env vars (PROJECT_NAME, DATABASE_URL, etc.) - # consistent whether you enter via 'nix develop' or 'direnv allow'. - if [ -z "''${DIRENV_IN_ENVRC:-}" ] && [ -f .envrc ]; then - # Only source the non-nix parts to avoid recursion. - export PROJECT_NAME="k9-validate-action" - export RSR_TIER="infrastructure" - if [ -f .env ]; then - set -a - . .env - set +a - fi - fi - ''; - }; - - # --------------------------------------------------------------- - # Package — `nix build` - # --------------------------------------------------------------- - packages.default = pkgs.stdenv.mkDerivation { - pname = "k9-validate-action"; - version = "0.1.0"; - - src = self; - - # TODO: Replace with real build instructions. - # Examples: - # - # Rust (use rustPlatform.buildRustPackage instead of stdenv): - # packages.default = pkgs.rustPlatform.buildRustPackage { ... }; - # - # Elixir (use mixRelease): - # packages.default = pkgs.beamPackages.mixRelease { ... }; - # - # Zig: - # buildPhase = "zig build -Doptimize=ReleaseSafe"; - - buildPhase = '' - echo "TODO: Add build commands for k9-validate-action" - ''; - - installPhase = '' - mkdir -p $out/share/doc - cp README.adoc $out/share/doc/ 2>/dev/null || true - ''; - - meta = with pkgs.lib; { - description = ""; - homepage = "https://github.com/hyperpolymath/k9-validate-action"; - license = licenses.mpl20; # PMPL-1.0-or-later extends MPL-2.0 - maintainers = []; - platforms = [ "x86_64-linux" "aarch64-linux" ]; - }; - }; - } - ); -} diff --git a/k9-svc/bindings/deno/.machine_readable/6a2/META.a2ml b/k9-svc/bindings/deno/.machine_readable/6a2/META.a2ml index 6e5dda1e..d9b09e68 100644 --- a/k9-svc/bindings/deno/.machine_readable/6a2/META.a2ml +++ b/k9-svc/bindings/deno/.machine_readable/6a2/META.a2ml @@ -11,7 +11,7 @@ last-updated = "2026-04-11" [project-info] type = "library" # TODO: update type (library|binary|service|website|monorepo) # library | binary | monorepo | service | website languages = [] # e.g. ["rust", "zig", "idris2"] -license = "PMPL-1.0-or-later" +license = "MPL-2.0" author = "Jonathan D.A. Jewell (hyperpolymath)" [architecture-decisions] diff --git a/k9-svc/bindings/deno/flake.nix b/k9-svc/bindings/deno/flake.nix deleted file mode 100644 index ded161e3..00000000 --- a/k9-svc/bindings/deno/flake.nix +++ /dev/null @@ -1,170 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}> -# -# Nix flake for {{PROJECT_NAME}} -# -# NOTE: guix.scm is the PRIMARY development environment. This flake is provided -# as a FALLBACK for contributors who use Nix instead of Guix. The .envrc checks -# for Guix first, then falls back to Nix. -# -# Usage: -# nix develop # Enter development shell -# nix build # Build the project -# nix flake check # Run checks -# nix flake show # Show flake outputs -# -# With direnv (.envrc already configured): -# direnv allow # Auto-enters shell on cd -# -# TODO: Replace {{PROJECT_NAME}} and {{PROJECT_DESCRIPTION}} with actual values. - -{ - description = "{{PROJECT_NAME}} — RSR-compliant project"; - - inputs = { - nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable"; - flake-utils.url = "github:numtide/flake-utils"; - }; - - outputs = { self, nixpkgs, flake-utils }: - flake-utils.lib.eachSystem [ "x86_64-linux" "aarch64-linux" ] (system: - let - pkgs = import nixpkgs { inherit system; }; - - # Common development tools present in every RSR project. - commonTools = with pkgs; [ - git - just - nickel - curl - bash - coreutils - ]; - - # --------------------------------------------------------------- - # Language-specific packages: uncomment the stacks you need. - # --------------------------------------------------------------- - # - # Rust: - # rustc cargo clippy rustfmt rust-analyzer - # - # Elixir: - # elixir erlang - # - # Gleam: - # gleam erlang - # - # Zig: - # zig zls - # - # Haskell: - # ghc cabal-install haskell-language-server - # - # Idris2: - # idris2 - # - # OCaml: - # ocaml dune_3 ocaml-lsp - # - # ReScript (via Deno): - # deno - # - # Julia: - # julia - # - # Ada/SPARK: - # gnat gprbuild - # - # --------------------------------------------------------------- - languageTools = with pkgs; [ - # TODO: Uncomment or add packages for your stack. - # Example for a Rust project: - # rustc - # cargo - # clippy - # rustfmt - # rust-analyzer - ]; - - in - { - # --------------------------------------------------------------- - # Development shell — `nix develop` - # --------------------------------------------------------------- - devShells.default = pkgs.mkShell { - name = "{{PROJECT_NAME}}-dev"; - - buildInputs = commonTools ++ languageTools; - - # Environment variables available inside the shell. - env = { - PROJECT_NAME = "{{PROJECT_NAME}}"; - RSR_TIER = "infrastructure"; - }; - - shellHook = '' - echo "" - echo " {{PROJECT_NAME}} — development shell" - echo " Nix: $(nix --version 2>/dev/null || echo 'unknown')" - echo " Just: $(just --version 2>/dev/null || echo 'not found')" - echo "" - echo " Run 'just' to see available recipes." - echo "" - - # Source .envrc manually when direnv is not managing the shell. - # This keeps project env vars (PROJECT_NAME, DATABASE_URL, etc.) - # consistent whether you enter via 'nix develop' or 'direnv allow'. - if [ -z "''${DIRENV_IN_ENVRC:-}" ] && [ -f .envrc ]; then - # Only source the non-nix parts to avoid recursion. - export PROJECT_NAME="{{PROJECT_NAME}}" - export RSR_TIER="infrastructure" - if [ -f .env ]; then - set -a - . .env - set +a - fi - fi - ''; - }; - - # --------------------------------------------------------------- - # Package — `nix build` - # --------------------------------------------------------------- - packages.default = pkgs.stdenv.mkDerivation { - pname = "{{PROJECT_NAME}}"; - version = "0.1.0"; - - src = self; - - # TODO: Replace with real build instructions. - # Examples: - # - # Rust (use rustPlatform.buildRustPackage instead of stdenv): - # packages.default = pkgs.rustPlatform.buildRustPackage { ... }; - # - # Elixir (use mixRelease): - # packages.default = pkgs.beamPackages.mixRelease { ... }; - # - # Zig: - # buildPhase = "zig build -Doptimize=ReleaseSafe"; - - buildPhase = '' - echo "TODO: Add build commands for {{PROJECT_NAME}}" - ''; - - installPhase = '' - mkdir -p $out/share/doc - cp README.adoc $out/share/doc/ 2>/dev/null || true - ''; - - meta = with pkgs.lib; { - description = "{{PROJECT_DESCRIPTION}}"; - homepage = "https://github.com/{{OWNER}}/{{PROJECT_NAME}}"; - license = licenses.mpl20; # PMPL-1.0-or-later extends MPL-2.0 - maintainers = []; - platforms = [ "x86_64-linux" "aarch64-linux" ]; - }; - }; - } - ); -} diff --git a/k9-svc/bindings/haskell/.machine_readable/6a2/META.a2ml b/k9-svc/bindings/haskell/.machine_readable/6a2/META.a2ml index 6e5dda1e..d9b09e68 100644 --- a/k9-svc/bindings/haskell/.machine_readable/6a2/META.a2ml +++ b/k9-svc/bindings/haskell/.machine_readable/6a2/META.a2ml @@ -11,7 +11,7 @@ last-updated = "2026-04-11" [project-info] type = "library" # TODO: update type (library|binary|service|website|monorepo) # library | binary | monorepo | service | website languages = [] # e.g. ["rust", "zig", "idris2"] -license = "PMPL-1.0-or-later" +license = "MPL-2.0" author = "Jonathan D.A. Jewell (hyperpolymath)" [architecture-decisions] diff --git a/k9-svc/bindings/haskell/flake.nix b/k9-svc/bindings/haskell/flake.nix deleted file mode 100644 index ded161e3..00000000 --- a/k9-svc/bindings/haskell/flake.nix +++ /dev/null @@ -1,170 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}> -# -# Nix flake for {{PROJECT_NAME}} -# -# NOTE: guix.scm is the PRIMARY development environment. This flake is provided -# as a FALLBACK for contributors who use Nix instead of Guix. The .envrc checks -# for Guix first, then falls back to Nix. -# -# Usage: -# nix develop # Enter development shell -# nix build # Build the project -# nix flake check # Run checks -# nix flake show # Show flake outputs -# -# With direnv (.envrc already configured): -# direnv allow # Auto-enters shell on cd -# -# TODO: Replace {{PROJECT_NAME}} and {{PROJECT_DESCRIPTION}} with actual values. - -{ - description = "{{PROJECT_NAME}} — RSR-compliant project"; - - inputs = { - nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable"; - flake-utils.url = "github:numtide/flake-utils"; - }; - - outputs = { self, nixpkgs, flake-utils }: - flake-utils.lib.eachSystem [ "x86_64-linux" "aarch64-linux" ] (system: - let - pkgs = import nixpkgs { inherit system; }; - - # Common development tools present in every RSR project. - commonTools = with pkgs; [ - git - just - nickel - curl - bash - coreutils - ]; - - # --------------------------------------------------------------- - # Language-specific packages: uncomment the stacks you need. - # --------------------------------------------------------------- - # - # Rust: - # rustc cargo clippy rustfmt rust-analyzer - # - # Elixir: - # elixir erlang - # - # Gleam: - # gleam erlang - # - # Zig: - # zig zls - # - # Haskell: - # ghc cabal-install haskell-language-server - # - # Idris2: - # idris2 - # - # OCaml: - # ocaml dune_3 ocaml-lsp - # - # ReScript (via Deno): - # deno - # - # Julia: - # julia - # - # Ada/SPARK: - # gnat gprbuild - # - # --------------------------------------------------------------- - languageTools = with pkgs; [ - # TODO: Uncomment or add packages for your stack. - # Example for a Rust project: - # rustc - # cargo - # clippy - # rustfmt - # rust-analyzer - ]; - - in - { - # --------------------------------------------------------------- - # Development shell — `nix develop` - # --------------------------------------------------------------- - devShells.default = pkgs.mkShell { - name = "{{PROJECT_NAME}}-dev"; - - buildInputs = commonTools ++ languageTools; - - # Environment variables available inside the shell. - env = { - PROJECT_NAME = "{{PROJECT_NAME}}"; - RSR_TIER = "infrastructure"; - }; - - shellHook = '' - echo "" - echo " {{PROJECT_NAME}} — development shell" - echo " Nix: $(nix --version 2>/dev/null || echo 'unknown')" - echo " Just: $(just --version 2>/dev/null || echo 'not found')" - echo "" - echo " Run 'just' to see available recipes." - echo "" - - # Source .envrc manually when direnv is not managing the shell. - # This keeps project env vars (PROJECT_NAME, DATABASE_URL, etc.) - # consistent whether you enter via 'nix develop' or 'direnv allow'. - if [ -z "''${DIRENV_IN_ENVRC:-}" ] && [ -f .envrc ]; then - # Only source the non-nix parts to avoid recursion. - export PROJECT_NAME="{{PROJECT_NAME}}" - export RSR_TIER="infrastructure" - if [ -f .env ]; then - set -a - . .env - set +a - fi - fi - ''; - }; - - # --------------------------------------------------------------- - # Package — `nix build` - # --------------------------------------------------------------- - packages.default = pkgs.stdenv.mkDerivation { - pname = "{{PROJECT_NAME}}"; - version = "0.1.0"; - - src = self; - - # TODO: Replace with real build instructions. - # Examples: - # - # Rust (use rustPlatform.buildRustPackage instead of stdenv): - # packages.default = pkgs.rustPlatform.buildRustPackage { ... }; - # - # Elixir (use mixRelease): - # packages.default = pkgs.beamPackages.mixRelease { ... }; - # - # Zig: - # buildPhase = "zig build -Doptimize=ReleaseSafe"; - - buildPhase = '' - echo "TODO: Add build commands for {{PROJECT_NAME}}" - ''; - - installPhase = '' - mkdir -p $out/share/doc - cp README.adoc $out/share/doc/ 2>/dev/null || true - ''; - - meta = with pkgs.lib; { - description = "{{PROJECT_DESCRIPTION}}"; - homepage = "https://github.com/{{OWNER}}/{{PROJECT_NAME}}"; - license = licenses.mpl20; # PMPL-1.0-or-later extends MPL-2.0 - maintainers = []; - platforms = [ "x86_64-linux" "aarch64-linux" ]; - }; - }; - } - ); -} diff --git a/k9-svc/bindings/rust/.machine_readable/6a2/META.a2ml b/k9-svc/bindings/rust/.machine_readable/6a2/META.a2ml index 6e5dda1e..d9b09e68 100644 --- a/k9-svc/bindings/rust/.machine_readable/6a2/META.a2ml +++ b/k9-svc/bindings/rust/.machine_readable/6a2/META.a2ml @@ -11,7 +11,7 @@ last-updated = "2026-04-11" [project-info] type = "library" # TODO: update type (library|binary|service|website|monorepo) # library | binary | monorepo | service | website languages = [] # e.g. ["rust", "zig", "idris2"] -license = "PMPL-1.0-or-later" +license = "MPL-2.0" author = "Jonathan D.A. Jewell (hyperpolymath)" [architecture-decisions] diff --git a/k9-svc/bindings/rust/flake.nix b/k9-svc/bindings/rust/flake.nix deleted file mode 100644 index ded161e3..00000000 --- a/k9-svc/bindings/rust/flake.nix +++ /dev/null @@ -1,170 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}> -# -# Nix flake for {{PROJECT_NAME}} -# -# NOTE: guix.scm is the PRIMARY development environment. This flake is provided -# as a FALLBACK for contributors who use Nix instead of Guix. The .envrc checks -# for Guix first, then falls back to Nix. -# -# Usage: -# nix develop # Enter development shell -# nix build # Build the project -# nix flake check # Run checks -# nix flake show # Show flake outputs -# -# With direnv (.envrc already configured): -# direnv allow # Auto-enters shell on cd -# -# TODO: Replace {{PROJECT_NAME}} and {{PROJECT_DESCRIPTION}} with actual values. - -{ - description = "{{PROJECT_NAME}} — RSR-compliant project"; - - inputs = { - nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable"; - flake-utils.url = "github:numtide/flake-utils"; - }; - - outputs = { self, nixpkgs, flake-utils }: - flake-utils.lib.eachSystem [ "x86_64-linux" "aarch64-linux" ] (system: - let - pkgs = import nixpkgs { inherit system; }; - - # Common development tools present in every RSR project. - commonTools = with pkgs; [ - git - just - nickel - curl - bash - coreutils - ]; - - # --------------------------------------------------------------- - # Language-specific packages: uncomment the stacks you need. - # --------------------------------------------------------------- - # - # Rust: - # rustc cargo clippy rustfmt rust-analyzer - # - # Elixir: - # elixir erlang - # - # Gleam: - # gleam erlang - # - # Zig: - # zig zls - # - # Haskell: - # ghc cabal-install haskell-language-server - # - # Idris2: - # idris2 - # - # OCaml: - # ocaml dune_3 ocaml-lsp - # - # ReScript (via Deno): - # deno - # - # Julia: - # julia - # - # Ada/SPARK: - # gnat gprbuild - # - # --------------------------------------------------------------- - languageTools = with pkgs; [ - # TODO: Uncomment or add packages for your stack. - # Example for a Rust project: - # rustc - # cargo - # clippy - # rustfmt - # rust-analyzer - ]; - - in - { - # --------------------------------------------------------------- - # Development shell — `nix develop` - # --------------------------------------------------------------- - devShells.default = pkgs.mkShell { - name = "{{PROJECT_NAME}}-dev"; - - buildInputs = commonTools ++ languageTools; - - # Environment variables available inside the shell. - env = { - PROJECT_NAME = "{{PROJECT_NAME}}"; - RSR_TIER = "infrastructure"; - }; - - shellHook = '' - echo "" - echo " {{PROJECT_NAME}} — development shell" - echo " Nix: $(nix --version 2>/dev/null || echo 'unknown')" - echo " Just: $(just --version 2>/dev/null || echo 'not found')" - echo "" - echo " Run 'just' to see available recipes." - echo "" - - # Source .envrc manually when direnv is not managing the shell. - # This keeps project env vars (PROJECT_NAME, DATABASE_URL, etc.) - # consistent whether you enter via 'nix develop' or 'direnv allow'. - if [ -z "''${DIRENV_IN_ENVRC:-}" ] && [ -f .envrc ]; then - # Only source the non-nix parts to avoid recursion. - export PROJECT_NAME="{{PROJECT_NAME}}" - export RSR_TIER="infrastructure" - if [ -f .env ]; then - set -a - . .env - set +a - fi - fi - ''; - }; - - # --------------------------------------------------------------- - # Package — `nix build` - # --------------------------------------------------------------- - packages.default = pkgs.stdenv.mkDerivation { - pname = "{{PROJECT_NAME}}"; - version = "0.1.0"; - - src = self; - - # TODO: Replace with real build instructions. - # Examples: - # - # Rust (use rustPlatform.buildRustPackage instead of stdenv): - # packages.default = pkgs.rustPlatform.buildRustPackage { ... }; - # - # Elixir (use mixRelease): - # packages.default = pkgs.beamPackages.mixRelease { ... }; - # - # Zig: - # buildPhase = "zig build -Doptimize=ReleaseSafe"; - - buildPhase = '' - echo "TODO: Add build commands for {{PROJECT_NAME}}" - ''; - - installPhase = '' - mkdir -p $out/share/doc - cp README.adoc $out/share/doc/ 2>/dev/null || true - ''; - - meta = with pkgs.lib; { - description = "{{PROJECT_DESCRIPTION}}"; - homepage = "https://github.com/{{OWNER}}/{{PROJECT_NAME}}"; - license = licenses.mpl20; # PMPL-1.0-or-later extends MPL-2.0 - maintainers = []; - platforms = [ "x86_64-linux" "aarch64-linux" ]; - }; - }; - } - ); -} diff --git a/k9-svc/editors/vscode/.machine_readable/6a2/META.a2ml b/k9-svc/editors/vscode/.machine_readable/6a2/META.a2ml index 6e5dda1e..d9b09e68 100644 --- a/k9-svc/editors/vscode/.machine_readable/6a2/META.a2ml +++ b/k9-svc/editors/vscode/.machine_readable/6a2/META.a2ml @@ -11,7 +11,7 @@ last-updated = "2026-04-11" [project-info] type = "library" # TODO: update type (library|binary|service|website|monorepo) # library | binary | monorepo | service | website languages = [] # e.g. ["rust", "zig", "idris2"] -license = "PMPL-1.0-or-later" +license = "MPL-2.0" author = "Jonathan D.A. Jewell (hyperpolymath)" [architecture-decisions] diff --git a/k9-svc/editors/vscode/flake.nix b/k9-svc/editors/vscode/flake.nix deleted file mode 100644 index ded161e3..00000000 --- a/k9-svc/editors/vscode/flake.nix +++ /dev/null @@ -1,170 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}> -# -# Nix flake for {{PROJECT_NAME}} -# -# NOTE: guix.scm is the PRIMARY development environment. This flake is provided -# as a FALLBACK for contributors who use Nix instead of Guix. The .envrc checks -# for Guix first, then falls back to Nix. -# -# Usage: -# nix develop # Enter development shell -# nix build # Build the project -# nix flake check # Run checks -# nix flake show # Show flake outputs -# -# With direnv (.envrc already configured): -# direnv allow # Auto-enters shell on cd -# -# TODO: Replace {{PROJECT_NAME}} and {{PROJECT_DESCRIPTION}} with actual values. - -{ - description = "{{PROJECT_NAME}} — RSR-compliant project"; - - inputs = { - nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable"; - flake-utils.url = "github:numtide/flake-utils"; - }; - - outputs = { self, nixpkgs, flake-utils }: - flake-utils.lib.eachSystem [ "x86_64-linux" "aarch64-linux" ] (system: - let - pkgs = import nixpkgs { inherit system; }; - - # Common development tools present in every RSR project. - commonTools = with pkgs; [ - git - just - nickel - curl - bash - coreutils - ]; - - # --------------------------------------------------------------- - # Language-specific packages: uncomment the stacks you need. - # --------------------------------------------------------------- - # - # Rust: - # rustc cargo clippy rustfmt rust-analyzer - # - # Elixir: - # elixir erlang - # - # Gleam: - # gleam erlang - # - # Zig: - # zig zls - # - # Haskell: - # ghc cabal-install haskell-language-server - # - # Idris2: - # idris2 - # - # OCaml: - # ocaml dune_3 ocaml-lsp - # - # ReScript (via Deno): - # deno - # - # Julia: - # julia - # - # Ada/SPARK: - # gnat gprbuild - # - # --------------------------------------------------------------- - languageTools = with pkgs; [ - # TODO: Uncomment or add packages for your stack. - # Example for a Rust project: - # rustc - # cargo - # clippy - # rustfmt - # rust-analyzer - ]; - - in - { - # --------------------------------------------------------------- - # Development shell — `nix develop` - # --------------------------------------------------------------- - devShells.default = pkgs.mkShell { - name = "{{PROJECT_NAME}}-dev"; - - buildInputs = commonTools ++ languageTools; - - # Environment variables available inside the shell. - env = { - PROJECT_NAME = "{{PROJECT_NAME}}"; - RSR_TIER = "infrastructure"; - }; - - shellHook = '' - echo "" - echo " {{PROJECT_NAME}} — development shell" - echo " Nix: $(nix --version 2>/dev/null || echo 'unknown')" - echo " Just: $(just --version 2>/dev/null || echo 'not found')" - echo "" - echo " Run 'just' to see available recipes." - echo "" - - # Source .envrc manually when direnv is not managing the shell. - # This keeps project env vars (PROJECT_NAME, DATABASE_URL, etc.) - # consistent whether you enter via 'nix develop' or 'direnv allow'. - if [ -z "''${DIRENV_IN_ENVRC:-}" ] && [ -f .envrc ]; then - # Only source the non-nix parts to avoid recursion. - export PROJECT_NAME="{{PROJECT_NAME}}" - export RSR_TIER="infrastructure" - if [ -f .env ]; then - set -a - . .env - set +a - fi - fi - ''; - }; - - # --------------------------------------------------------------- - # Package — `nix build` - # --------------------------------------------------------------- - packages.default = pkgs.stdenv.mkDerivation { - pname = "{{PROJECT_NAME}}"; - version = "0.1.0"; - - src = self; - - # TODO: Replace with real build instructions. - # Examples: - # - # Rust (use rustPlatform.buildRustPackage instead of stdenv): - # packages.default = pkgs.rustPlatform.buildRustPackage { ... }; - # - # Elixir (use mixRelease): - # packages.default = pkgs.beamPackages.mixRelease { ... }; - # - # Zig: - # buildPhase = "zig build -Doptimize=ReleaseSafe"; - - buildPhase = '' - echo "TODO: Add build commands for {{PROJECT_NAME}}" - ''; - - installPhase = '' - mkdir -p $out/share/doc - cp README.adoc $out/share/doc/ 2>/dev/null || true - ''; - - meta = with pkgs.lib; { - description = "{{PROJECT_DESCRIPTION}}"; - homepage = "https://github.com/{{OWNER}}/{{PROJECT_NAME}}"; - license = licenses.mpl20; # PMPL-1.0-or-later extends MPL-2.0 - maintainers = []; - platforms = [ "x86_64-linux" "aarch64-linux" ]; - }; - }; - } - ); -} diff --git a/k9-svc/flake.lock b/k9-svc/flake.lock deleted file mode 100644 index 4cee253d..00000000 --- a/k9-svc/flake.lock +++ /dev/null @@ -1,61 +0,0 @@ -{ - "nodes": { - "flake-utils": { - "inputs": { - "systems": "systems" - }, - "locked": { - "lastModified": 1731533236, - "narHash": "sha256-l0KFg5HjrsfsO/JpG+r7fRrqm12kzFHyUHqHCVpMMbI=", - "owner": "numtide", - "repo": "flake-utils", - "rev": "11707dc2f618dd54ca8739b309ec4fc024de578b", - "type": "github" - }, - "original": { - "owner": "numtide", - "repo": "flake-utils", - "type": "github" - } - }, - "nixpkgs": { - "locked": { - "lastModified": 1776169885, - "narHash": "sha256-l/iNYDZ4bGOAFQY2q8y5OAfBBtrDAaPuRQqWaFHVRXM=", - "owner": "NixOS", - "repo": "nixpkgs", - "rev": "4bd9165a9165d7b5e33ae57f3eecbcb28fb231c9", - "type": "github" - }, - "original": { - "owner": "NixOS", - "ref": "nixos-unstable", - "repo": "nixpkgs", - "type": "github" - } - }, - "root": { - "inputs": { - "flake-utils": "flake-utils", - "nixpkgs": "nixpkgs" - } - }, - "systems": { - "locked": { - "lastModified": 1681028828, - "narHash": "sha256-Vy1rq5AaRuLzOxct8nz4T6wlgyUR7zLU309k9mBC768=", - "owner": "nix-systems", - "repo": "default", - "rev": "da67096a3b9bf56a91d16901293e51ba5b49a27e", - "type": "github" - }, - "original": { - "owner": "nix-systems", - "repo": "default", - "type": "github" - } - } - }, - "root": "root", - "version": 7 -} diff --git a/k9-svc/flake.nix b/k9-svc/flake.nix deleted file mode 100644 index 49d97670..00000000 --- a/k9-svc/flake.nix +++ /dev/null @@ -1,137 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# flake.nix - K9 SVC Nix Flake -# -# Usage: -# nix develop # Enter development shell -# nix build # Build the package -# nix run # Run k9 status -# nix flake check # Run tests -# -# To use in another flake: -# inputs.k9-svc.url = "github:hyperpolymath/k9-svc"; -# packages = [ inputs.k9-svc.packages.${system}.default ]; - -{ - description = "K9 SVC - Self-Validating Components"; - - inputs = { - nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable"; - flake-utils.url = "github:numtide/flake-utils"; - }; - - outputs = { self, nixpkgs, flake-utils }: - flake-utils.lib.eachDefaultSystem (system: - let - pkgs = nixpkgs.legacyPackages.${system}; - - k9-svc = pkgs.stdenv.mkDerivation { - pname = "k9-svc"; - version = "1.0.0"; - - src = ./.; - - nativeBuildInputs = [ pkgs.makeWrapper ]; - - buildInputs = [ - pkgs.nickel - pkgs.just - pkgs.openssl - ]; - - installPhase = '' - runHook preInstall - - # Create directories - mkdir -p $out/bin - mkdir -p $out/share/k9/{examples,assets} - mkdir -p $out/share/mime/packages - mkdir -p $out/share/doc/k9-svc - - # Install scripts - install -m755 must $out/bin/k9-must - install -m755 sign.sh $out/bin/k9-sign - - # Install schemas - install -m644 pedigree.ncl $out/share/k9/ - install -m644 register.ncl $out/share/k9/ - install -m644 leash.ncl $out/share/k9/ - install -m644 justfile $out/share/k9/ - - # Install examples - install -m644 examples/*.k9 $out/share/k9/examples/ 2>/dev/null || true - install -m644 examples/*.k9.ncl $out/share/k9/examples/ 2>/dev/null || true - - # Install assets - install -m644 assets/*.svg $out/share/k9/assets/ 2>/dev/null || true - - # Install MIME type - install -m644 mime/k9.xml $out/share/mime/packages/ - - # Install documentation - install -m644 README.adoc SPEC.adoc GUIDE.adoc LICENSE $out/share/doc/k9-svc/ - - # Create wrapper script - makeWrapper ${pkgs.just}/bin/just $out/bin/k9 \ - --add-flags "--justfile $out/share/k9/justfile" \ - --prefix PATH : ${pkgs.lib.makeBinPath [ pkgs.nickel pkgs.openssl ]} - - # Wrap sign.sh to ensure openssl is available - wrapProgram $out/bin/k9-sign \ - --prefix PATH : ${pkgs.lib.makeBinPath [ pkgs.openssl ]} - - runHook postInstall - ''; - - meta = with pkgs.lib; { - description = "Self-Validating Components - a file format that eats its own dog food"; - homepage = "https://github.com/hyperpolymath/standards/tree/main/k9-svc"; - license = licenses.agpl3Plus; - maintainers = []; - platforms = platforms.unix; - }; - }; - - in { - packages = { - default = k9-svc; - k9-svc = k9-svc; - }; - - apps.default = flake-utils.lib.mkApp { - drv = k9-svc; - exePath = "/bin/k9"; - }; - - devShells.default = pkgs.mkShell { - buildInputs = [ - pkgs.nickel - pkgs.just - pkgs.openssl - pkgs.podman - pkgs.asciidoctor - pkgs.xmllint - ]; - - shellHook = '' - echo "K9 SVC Development Shell" - echo "========================" - echo "Available commands:" - echo " ./must status - Check environment" - echo " just typecheck - Validate schemas" - echo " just test - Run test suite" - echo " just dogfood - Self-validation" - echo "" - ''; - }; - - checks.default = pkgs.runCommand "k9-svc-check" { - buildInputs = [ pkgs.nickel k9-svc ]; - } '' - # Typecheck schemas - nickel typecheck ${k9-svc}/share/k9/pedigree.ncl - nickel typecheck ${k9-svc}/share/k9/register.ncl - nickel typecheck ${k9-svc}/share/k9/leash.ncl - echo "All schema checks passed" > $out - ''; - }); -} diff --git a/k9-svc/guix.scm b/k9-svc/guix.scm new file mode 100644 index 00000000..8f58b472 --- /dev/null +++ b/k9-svc/guix.scm @@ -0,0 +1,32 @@ +;;; SPDX-License-Identifier: MPL-2.0 +;;; guix.scm — Guix environment for K9 SVC development +;;; +;;; Usage: +;;; guix shell -D -f guix.scm +;;; + +(use-modules (guix packages) + (guix build-system gnu) + (guix licenses) + (gnu packages base) + (gnu packages crypto) + (gnu packages shells) + (gnu packages rust-apps) ; for just + (gnu packages node)) ; for nickel if available or used + +(package + (name "k9-svc") + (version "1.0.0") + (source #f) ; Development environment only + (build-system gnu-build-system) + (native-inputs + (list just + openssl + nickel + ripgrep)) + (synopsis "Self-Validating Components - Data-first configuration") + (description + "Development environment for K9 SVC, including Nickel for schema +validation and OpenSSL for cryptographic signing.") + (home-page "https://github.com/hyperpolymath/standards/tree/main/k9-svc") + (license agpl3+)) diff --git a/k9-svc/manifest.scm b/k9-svc/manifest.scm new file mode 100644 index 00000000..dd942c7f --- /dev/null +++ b/k9-svc/manifest.scm @@ -0,0 +1,24 @@ +;;; SPDX-License-Identifier: MPL-2.0 +;;; manifest.scm — Generic Guix manifest for RSR-compliant projects +;;; +;;; Usage: +;;; guix shell -m manifest.scm +;;; + +(specifications->manifest + '(;; Core development tools + "git" + "just" + "nickel" + "curl" + "bash" + "coreutils" + + ;; Documentation + "asciidoctor" + "pandoc" + + ;; Common build dependencies + "openssl" + "zlib" + "pkg-config")) diff --git a/k9-svc/pandoc/.machine_readable/6a2/META.a2ml b/k9-svc/pandoc/.machine_readable/6a2/META.a2ml index 6e5dda1e..d9b09e68 100644 --- a/k9-svc/pandoc/.machine_readable/6a2/META.a2ml +++ b/k9-svc/pandoc/.machine_readable/6a2/META.a2ml @@ -11,7 +11,7 @@ last-updated = "2026-04-11" [project-info] type = "library" # TODO: update type (library|binary|service|website|monorepo) # library | binary | monorepo | service | website languages = [] # e.g. ["rust", "zig", "idris2"] -license = "PMPL-1.0-or-later" +license = "MPL-2.0" author = "Jonathan D.A. Jewell (hyperpolymath)" [architecture-decisions] diff --git a/k9-svc/pandoc/flake.nix b/k9-svc/pandoc/flake.nix deleted file mode 100644 index ded161e3..00000000 --- a/k9-svc/pandoc/flake.nix +++ /dev/null @@ -1,170 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}> -# -# Nix flake for {{PROJECT_NAME}} -# -# NOTE: guix.scm is the PRIMARY development environment. This flake is provided -# as a FALLBACK for contributors who use Nix instead of Guix. The .envrc checks -# for Guix first, then falls back to Nix. -# -# Usage: -# nix develop # Enter development shell -# nix build # Build the project -# nix flake check # Run checks -# nix flake show # Show flake outputs -# -# With direnv (.envrc already configured): -# direnv allow # Auto-enters shell on cd -# -# TODO: Replace {{PROJECT_NAME}} and {{PROJECT_DESCRIPTION}} with actual values. - -{ - description = "{{PROJECT_NAME}} — RSR-compliant project"; - - inputs = { - nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable"; - flake-utils.url = "github:numtide/flake-utils"; - }; - - outputs = { self, nixpkgs, flake-utils }: - flake-utils.lib.eachSystem [ "x86_64-linux" "aarch64-linux" ] (system: - let - pkgs = import nixpkgs { inherit system; }; - - # Common development tools present in every RSR project. - commonTools = with pkgs; [ - git - just - nickel - curl - bash - coreutils - ]; - - # --------------------------------------------------------------- - # Language-specific packages: uncomment the stacks you need. - # --------------------------------------------------------------- - # - # Rust: - # rustc cargo clippy rustfmt rust-analyzer - # - # Elixir: - # elixir erlang - # - # Gleam: - # gleam erlang - # - # Zig: - # zig zls - # - # Haskell: - # ghc cabal-install haskell-language-server - # - # Idris2: - # idris2 - # - # OCaml: - # ocaml dune_3 ocaml-lsp - # - # ReScript (via Deno): - # deno - # - # Julia: - # julia - # - # Ada/SPARK: - # gnat gprbuild - # - # --------------------------------------------------------------- - languageTools = with pkgs; [ - # TODO: Uncomment or add packages for your stack. - # Example for a Rust project: - # rustc - # cargo - # clippy - # rustfmt - # rust-analyzer - ]; - - in - { - # --------------------------------------------------------------- - # Development shell — `nix develop` - # --------------------------------------------------------------- - devShells.default = pkgs.mkShell { - name = "{{PROJECT_NAME}}-dev"; - - buildInputs = commonTools ++ languageTools; - - # Environment variables available inside the shell. - env = { - PROJECT_NAME = "{{PROJECT_NAME}}"; - RSR_TIER = "infrastructure"; - }; - - shellHook = '' - echo "" - echo " {{PROJECT_NAME}} — development shell" - echo " Nix: $(nix --version 2>/dev/null || echo 'unknown')" - echo " Just: $(just --version 2>/dev/null || echo 'not found')" - echo "" - echo " Run 'just' to see available recipes." - echo "" - - # Source .envrc manually when direnv is not managing the shell. - # This keeps project env vars (PROJECT_NAME, DATABASE_URL, etc.) - # consistent whether you enter via 'nix develop' or 'direnv allow'. - if [ -z "''${DIRENV_IN_ENVRC:-}" ] && [ -f .envrc ]; then - # Only source the non-nix parts to avoid recursion. - export PROJECT_NAME="{{PROJECT_NAME}}" - export RSR_TIER="infrastructure" - if [ -f .env ]; then - set -a - . .env - set +a - fi - fi - ''; - }; - - # --------------------------------------------------------------- - # Package — `nix build` - # --------------------------------------------------------------- - packages.default = pkgs.stdenv.mkDerivation { - pname = "{{PROJECT_NAME}}"; - version = "0.1.0"; - - src = self; - - # TODO: Replace with real build instructions. - # Examples: - # - # Rust (use rustPlatform.buildRustPackage instead of stdenv): - # packages.default = pkgs.rustPlatform.buildRustPackage { ... }; - # - # Elixir (use mixRelease): - # packages.default = pkgs.beamPackages.mixRelease { ... }; - # - # Zig: - # buildPhase = "zig build -Doptimize=ReleaseSafe"; - - buildPhase = '' - echo "TODO: Add build commands for {{PROJECT_NAME}}" - ''; - - installPhase = '' - mkdir -p $out/share/doc - cp README.adoc $out/share/doc/ 2>/dev/null || true - ''; - - meta = with pkgs.lib; { - description = "{{PROJECT_DESCRIPTION}}"; - homepage = "https://github.com/{{OWNER}}/{{PROJECT_NAME}}"; - license = licenses.mpl20; # PMPL-1.0-or-later extends MPL-2.0 - maintainers = []; - platforms = [ "x86_64-linux" "aarch64-linux" ]; - }; - }; - } - ); -} diff --git a/k9-svc/tools/manifest.scm b/k9-svc/tools/manifest.scm new file mode 100644 index 00000000..dd942c7f --- /dev/null +++ b/k9-svc/tools/manifest.scm @@ -0,0 +1,24 @@ +;;; SPDX-License-Identifier: MPL-2.0 +;;; manifest.scm — Generic Guix manifest for RSR-compliant projects +;;; +;;; Usage: +;;; guix shell -m manifest.scm +;;; + +(specifications->manifest + '(;; Core development tools + "git" + "just" + "nickel" + "curl" + "bash" + "coreutils" + + ;; Documentation + "asciidoctor" + "pandoc" + + ;; Common build dependencies + "openssl" + "zlib" + "pkg-config")) diff --git a/lol/.machine_readable/6a2/META.a2ml b/lol/.machine_readable/6a2/META.a2ml index 17e9d954..2e564acf 100644 --- a/lol/.machine_readable/6a2/META.a2ml +++ b/lol/.machine_readable/6a2/META.a2ml @@ -7,7 +7,7 @@ version = "0.1.0" last-updated = "2026-04-11" [project-info] -license = "PMPL-1.0-or-later" +license = "MPL-2.0" author = "Jonathan D.A. Jewell (hyperpolymath)" [architecture-decisions] diff --git a/lol/manifest.scm b/lol/manifest.scm new file mode 100644 index 00000000..dd942c7f --- /dev/null +++ b/lol/manifest.scm @@ -0,0 +1,24 @@ +;;; SPDX-License-Identifier: MPL-2.0 +;;; manifest.scm — Generic Guix manifest for RSR-compliant projects +;;; +;;; Usage: +;;; guix shell -m manifest.scm +;;; + +(specifications->manifest + '(;; Core development tools + "git" + "just" + "nickel" + "curl" + "bash" + "coreutils" + + ;; Documentation + "asciidoctor" + "pandoc" + + ;; Common build dependencies + "openssl" + "zlib" + "pkg-config")) diff --git a/neurosym-a2ml/.machine_readable/6a2/META.a2ml b/neurosym-a2ml/.machine_readable/6a2/META.a2ml index 76784db4..cc351418 100644 --- a/neurosym-a2ml/.machine_readable/6a2/META.a2ml +++ b/neurosym-a2ml/.machine_readable/6a2/META.a2ml @@ -7,7 +7,7 @@ version = "0.1.0" last-updated = "2026-04-11" [project-info] -license = "PMPL-1.0-or-later" +license = "MPL-2.0" author = "Jonathan D.A. Jewell (hyperpolymath)" [architecture-decisions] diff --git a/outreach/.machine_readable/6a2/META.a2ml b/outreach/.machine_readable/6a2/META.a2ml index ad8f2419..07229dba 100644 --- a/outreach/.machine_readable/6a2/META.a2ml +++ b/outreach/.machine_readable/6a2/META.a2ml @@ -7,7 +7,7 @@ version = "0.1.0" last-updated = "2026-02-08" [project-info] -license = "PMPL-1.0-or-later" +license = "MPL-2.0" author = "Jonathan D.A. Jewell (hyperpolymath)" [architecture-decisions] diff --git a/overlay-protocol/.machine_readable/6a2/META.a2ml b/overlay-protocol/.machine_readable/6a2/META.a2ml index ad3aba7f..abe0dfcb 100644 --- a/overlay-protocol/.machine_readable/6a2/META.a2ml +++ b/overlay-protocol/.machine_readable/6a2/META.a2ml @@ -7,7 +7,7 @@ version = "1.0.0-draft" last-updated = "2026-04-11" [project-info] -license = "PMPL-1.0-or-later" +license = "MPL-2.0" author = "Jonathan D.A. Jewell (hyperpolymath)" [architecture-decisions] diff --git a/playbook-a2ml/.machine_readable/6a2/META.a2ml b/playbook-a2ml/.machine_readable/6a2/META.a2ml index cad9747d..d0d598ba 100644 --- a/playbook-a2ml/.machine_readable/6a2/META.a2ml +++ b/playbook-a2ml/.machine_readable/6a2/META.a2ml @@ -7,7 +7,7 @@ version = "0.1.0" last-updated = "2026-04-11" [project-info] -license = "PMPL-1.0-or-later" +license = "MPL-2.0" author = "Jonathan D.A. Jewell (hyperpolymath)" [architecture-decisions] diff --git a/rhodium-standard-repositories/.machine_readable/6a2/META.a2ml b/rhodium-standard-repositories/.machine_readable/6a2/META.a2ml index 1daa5c45..ca56de5a 100644 --- a/rhodium-standard-repositories/.machine_readable/6a2/META.a2ml +++ b/rhodium-standard-repositories/.machine_readable/6a2/META.a2ml @@ -7,7 +7,7 @@ version = "0.1.0" last-updated = "2026-04-11" [project-info] -license = "PMPL-1.0-or-later" +license = "MPL-2.0" author = "Jonathan D.A. Jewell (hyperpolymath)" [architecture-decisions] diff --git a/rhodium-standard-repositories/examples/rhodium-minimal/flake.lock b/rhodium-standard-repositories/examples/rhodium-minimal/flake.lock deleted file mode 100644 index cb4629b3..00000000 --- a/rhodium-standard-repositories/examples/rhodium-minimal/flake.lock +++ /dev/null @@ -1,37 +0,0 @@ -{ - "nodes": { - "flake-utils": { - "locked": { - "narHash": "sha256-dummy", - "type": "github", - "owner": "numtide", - "repo": "flake-utils" - } - }, - "nixpkgs": { - "locked": { - "narHash": "sha256-dummy", - "type": "github", - "owner": "NixOS", - "repo": "nixpkgs" - } - }, - "rust-overlay": { - "locked": { - "narHash": "sha256-dummy", - "type": "github", - "owner": "oxalica", - "repo": "rust-overlay" - } - }, - "root": { - "inputs": { - "nixpkgs": "nixpkgs", - "flake-utils": "flake-utils", - "rust-overlay": "rust-overlay" - } - } - }, - "root": "root", - "version": 7 -} diff --git a/rhodium-standard-repositories/examples/rhodium-minimal/flake.nix b/rhodium-standard-repositories/examples/rhodium-minimal/flake.nix deleted file mode 100644 index 6a021dfa..00000000 --- a/rhodium-standard-repositories/examples/rhodium-minimal/flake.nix +++ /dev/null @@ -1,117 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 AND Palimpsest-0.8 -# SPDX-FileCopyrightText: 2025 The Rhodium Standard Contributors -{ - description = "rhodium-minimal - Minimal Rhodium Standard Repository example"; - - inputs = { - nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable"; - flake-utils.url = "github:numtide/flake-utils"; - rust-overlay.url = "github:oxalica/rust-overlay"; - }; - - outputs = { self, nixpkgs, flake-utils, rust-overlay }: - flake-utils.lib.eachDefaultSystem (system: - let - overlays = [ (import rust-overlay) ]; - pkgs = import nixpkgs { - inherit system overlays; - }; - - rustToolchain = pkgs.rust-bin.stable.latest.default.override { - extensions = [ "rust-src" "rust-analyzer" ]; - }; - - buildInputs = with pkgs; [ - rustToolchain - ]; - - nativeBuildInputs = with pkgs; [ - just - ripgrep - tokei # Code statistics - ]; - - in - { - # Development shell - devShells.default = pkgs.mkShell { - inherit buildInputs nativeBuildInputs; - - shellHook = '' - echo "🎖️ rhodium-minimal development environment" - echo "Language: Rust ${rustToolchain.version}" - echo "" - echo "Available commands:" - echo " just --list # Show all tasks" - echo " just build # Build project" - echo " just run # Run application" - echo " just test # Run tests" - echo " just validate # RSR compliance" - echo "" - echo "RSR Compliance: Bronze (75-89%)" - echo "TPCF Perimeter: 3 (Community Sandbox)" - echo "" - ''; - }; - - # Packages - packages.default = pkgs.rustPlatform.buildRustPackage { - pname = "rhodium-minimal"; - version = "0.1.0"; - src = ./.; - - cargoLock = { - lockFile = ./Cargo.lock; - }; - - nativeBuildInputs = nativeBuildInputs; - - meta = with pkgs.lib; { - description = "Minimal Rhodium Standard Repository (RSR) compliant example"; - homepage = "https://gitlab.com/hyperpolymath/rhodium-standard-repositories"; - license = with licenses; [ mit ]; # Dual: MIT + Palimpsest-0.8 - maintainers = [ "The Rhodium Standard Contributors" ]; - platforms = platforms.unix; - }; - }; - - # Apps - apps.default = { - type = "app"; - program = "${self.packages.${system}.default}/bin/rhodium-minimal"; - }; - - # Checks (CI/CD integration) - checks = { - build = self.packages.${system}.default; - - # Test check - test = pkgs.runCommand "test-rhodium-minimal" { - buildInputs = [ rustToolchain ]; - } '' - cd ${./.} - cargo test - touch $out - ''; - - # Format check - format = pkgs.runCommand "format-rhodium-minimal" { - buildInputs = [ rustToolchain ]; - } '' - cd ${./.} - cargo fmt -- --check - touch $out - ''; - - # Lint check - lint = pkgs.runCommand "lint-rhodium-minimal" { - buildInputs = [ rustToolchain ]; - } '' - cd ${./.} - cargo clippy -- -D warnings - touch $out - ''; - }; - } - ); -} diff --git a/rhodium-standard-repositories/examples/rhodium-minimal/manifest.scm b/rhodium-standard-repositories/examples/rhodium-minimal/manifest.scm new file mode 100644 index 00000000..dd942c7f --- /dev/null +++ b/rhodium-standard-repositories/examples/rhodium-minimal/manifest.scm @@ -0,0 +1,24 @@ +;;; SPDX-License-Identifier: MPL-2.0 +;;; manifest.scm — Generic Guix manifest for RSR-compliant projects +;;; +;;; Usage: +;;; guix shell -m manifest.scm +;;; + +(specifications->manifest + '(;; Core development tools + "git" + "just" + "nickel" + "curl" + "bash" + "coreutils" + + ;; Documentation + "asciidoctor" + "pandoc" + + ;; Common build dependencies + "openssl" + "zlib" + "pkg-config")) diff --git a/rhodium-standard-repositories/flake.lock b/rhodium-standard-repositories/flake.lock deleted file mode 100644 index 4a13e74c..00000000 --- a/rhodium-standard-repositories/flake.lock +++ /dev/null @@ -1,85 +0,0 @@ -{ - "nodes": { - "flake-utils": { - "inputs": { - "systems": "systems" - }, - "locked": { - "lastModified": 1701680307, - "narHash": "sha256-kAuep2h5ajznlPMD9rnQyffWG8EM/C73lejGofXvdM8=", - "owner": "numtide", - "repo": "flake-utils", - "rev": "4022d587cbbfd70fe950c1e2083a02621806a725", - "type": "github" - }, - "original": { - "owner": "numtide", - "repo": "flake-utils", - "type": "github" - } - }, - "nixpkgs": { - "locked": { - "lastModified": 1701336116, - "narHash": "sha256-kEmpezCR/FpITc6yMbAh4WrOCiT2zg5pSjnKrq51h5Y=", - "owner": "NixOS", - "repo": "nixpkgs", - "rev": "f5c27c6136db4d76c30e533c20517df6864c46ee", - "type": "github" - }, - "original": { - "owner": "NixOS", - "ref": "nixos-24.05", - "repo": "nixpkgs", - "type": "github" - } - }, - "root": { - "inputs": { - "flake-utils": "flake-utils", - "nixpkgs": "nixpkgs", - "rust-overlay": "rust-overlay" - } - }, - "rust-overlay": { - "inputs": { - "flake-utils": [ - "flake-utils" - ], - "nixpkgs": [ - "nixpkgs" - ] - }, - "locked": { - "lastModified": 1701389776, - "narHash": "sha256-5BzphZ/r92IQ2ybzU1N0KKW0xqYRThGYE9YckxlNuMQ=", - "owner": "oxalica", - "repo": "rust-overlay", - "rev": "9e0782d5e17d661fd27027e1a17c1e7c0b20b9b3", - "type": "github" - }, - "original": { - "owner": "oxalica", - "repo": "rust-overlay", - "type": "github" - } - }, - "systems": { - "locked": { - "lastModified": 1681028828, - "narHash": "sha256-Vy1rq5AaRuLzOxct8nz4T6wlgyUR7zLU309k9mBC768=", - "owner": "nix-systems", - "repo": "default", - "rev": "da67096a3b9bf56a91d16901293e51ba5b49a27e", - "type": "github" - }, - "original": { - "owner": "nix-systems", - "repo": "default", - "type": "github" - } - } - }, - "root": "root", - "version": 7 -} diff --git a/rhodium-standard-repositories/flake.nix b/rhodium-standard-repositories/flake.nix deleted file mode 100644 index 6fd7457d..00000000 --- a/rhodium-standard-repositories/flake.nix +++ /dev/null @@ -1,158 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 AND Palimpsest-0.8 -# SPDX-FileCopyrightText: 2025 The Rhodium Standard Contributors -{ - description = "Rhodium Standard Repositories - Framework for emotionally safe, technically excellent, politically autonomous software development"; - - inputs = { - nixpkgs.url = "github:NixOS/nixpkgs/nixos-24.05"; - flake-utils.url = "github:numtide/flake-utils"; - rust-overlay.url = "github:oxalica/rust-overlay"; - }; - - outputs = { self, nixpkgs, flake-utils, rust-overlay }: - flake-utils.lib.eachDefaultSystem (system: - let - overlays = [ (import rust-overlay) ]; - pkgs = import nixpkgs { - inherit system overlays; - }; - - rustToolchain = pkgs.rust-bin.stable.latest.default.override { - extensions = [ "rust-src" "rust-analyzer" "rustfmt" "clippy" ]; - }; - - in - { - devShells.default = pkgs.mkShell { - name = "rhodium-standard-dev"; - - buildInputs = with pkgs; [ - # Rust toolchain - rustToolchain - cargo-audit - cargo-watch - cargo-edit - - # Build tools - just - git - - # Documentation tools - asciidoctor - pandoc - - # Link checking - lychee - - # Shell linting - shellcheck - - # General utilities - jq - ripgrep - fd - tree - - # Nix tools - nil # Nix language server - nixfmt - ]; - - shellHook = '' - echo "🎖️ Rhodium Standard Development Environment" - echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" - echo "Available commands:" - echo " just --list # Show all tasks" - echo " just validate # Run full validation" - echo " just audit # RSR compliance audit" - echo " just test # Run tests" - echo "" - echo "Versions:" - echo " Rust: $(rustc --version | cut -d' ' -f2)" - echo " Cargo: $(cargo --version | cut -d' ' -f2)" - echo " Just: $(just --version 2>&1 | head -1 | cut -d' ' -f2)" - echo " Nix: $(nix --version | cut -d' ' -f3)" - echo "" - echo "Documentation: README.adoc" - echo "Contributing: CONTRIBUTING.adoc" - echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" - ''; - - # Environment variables - RUST_BACKTRACE = "1"; - RUST_LOG = "info"; - }; - - # Package for the RSR audit script - packages.rsr-audit = pkgs.writeShellApplication { - name = "rsr-audit"; - runtimeInputs = with pkgs; [ bash coreutils findutils ripgrep ]; - text = builtins.readFile ./rsr-audit.sh; - }; - - packages.default = self.packages.${system}.rsr-audit; - - # CI/CD checks - checks = { - audit-script-shellcheck = pkgs.runCommand "shellcheck-rsr-audit" { - buildInputs = [ pkgs.shellcheck ]; - } '' - shellcheck ${./rsr-audit.sh} - touch $out - ''; - - # Check that all required files exist - required-files-check = pkgs.runCommand "check-required-files" {} '' - cd ${./.} - - # Category 2: Documentation Standards - test -f README.adoc || (echo "Missing README.adoc" && exit 1) - test -f LICENSE.txt || (echo "Missing LICENSE.txt" && exit 1) - test -f SECURITY.md || (echo "Missing SECURITY.md" && exit 1) - test -f CODE_OF_CONDUCT.adoc || (echo "Missing CODE_OF_CONDUCT.adoc" && exit 1) - test -f CONTRIBUTING.adoc || (echo "Missing CONTRIBUTING.adoc" && exit 1) - test -f MAINTAINERS.md || (echo "Missing MAINTAINERS.md" && exit 1) - test -f CHANGELOG.md || (echo "Missing CHANGELOG.md" && exit 1) - test -f FUNDING.yml || (echo "Missing FUNDING.yml" && exit 1) - test -f GOVERNANCE.adoc || (echo "Missing GOVERNANCE.adoc" && exit 1) - - # .well-known directory - test -d .well-known || (echo "Missing .well-known directory" && exit 1) - test -f .well-known/security.txt || (echo "Missing .well-known/security.txt" && exit 1) - test -f .well-known/ai.txt || (echo "Missing .well-known/ai.txt" && exit 1) - test -f .well-known/humans.txt || (echo "Missing .well-known/humans.txt" && exit 1) - - # Infrastructure - test -f .gitignore || (echo "Missing .gitignore" && exit 1) - test -f .gitattributes || (echo "Missing .gitattributes" && exit 1) - test -f justfile || (echo "Missing justfile" && exit 1) - test -f flake.nix || (echo "Missing flake.nix" && exit 1) - - echo "✅ All required files present" - touch $out - ''; - }; - - # Apps for running tools - apps = { - audit = { - type = "app"; - program = "${self.packages.${system}.rsr-audit}/bin/rsr-audit"; - }; - }; - - # Formatter for Nix files - formatter = pkgs.nixfmt; - } - ); - - # Metadata - nixConfig = { - extra-substituters = [ - "https://cache.nixos.org" - ]; - extra-trusted-public-keys = [ - "cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY=" - ]; - }; -} diff --git a/rhodium-standard-repositories/manifest.scm b/rhodium-standard-repositories/manifest.scm new file mode 100644 index 00000000..dd942c7f --- /dev/null +++ b/rhodium-standard-repositories/manifest.scm @@ -0,0 +1,24 @@ +;;; SPDX-License-Identifier: MPL-2.0 +;;; manifest.scm — Generic Guix manifest for RSR-compliant projects +;;; +;;; Usage: +;;; guix shell -m manifest.scm +;;; + +(specifications->manifest + '(;; Core development tools + "git" + "just" + "nickel" + "curl" + "bash" + "coreutils" + + ;; Documentation + "asciidoctor" + "pandoc" + + ;; Common build dependencies + "openssl" + "zlib" + "pkg-config")) diff --git a/rhodium-standard-repositories/rhodium-pipeline/manifest.scm b/rhodium-standard-repositories/rhodium-pipeline/manifest.scm new file mode 100644 index 00000000..dd942c7f --- /dev/null +++ b/rhodium-standard-repositories/rhodium-pipeline/manifest.scm @@ -0,0 +1,24 @@ +;;; SPDX-License-Identifier: MPL-2.0 +;;; manifest.scm — Generic Guix manifest for RSR-compliant projects +;;; +;;; Usage: +;;; guix shell -m manifest.scm +;;; + +(specifications->manifest + '(;; Core development tools + "git" + "just" + "nickel" + "curl" + "bash" + "coreutils" + + ;; Documentation + "asciidoctor" + "pandoc" + + ;; Common build dependencies + "openssl" + "zlib" + "pkg-config")) diff --git a/rhodium-standard-repositories/satellites/cccp/satellites/nextgen-languages/7-tentacles/manifest.scm b/rhodium-standard-repositories/satellites/cccp/satellites/nextgen-languages/7-tentacles/manifest.scm new file mode 100644 index 00000000..dd942c7f --- /dev/null +++ b/rhodium-standard-repositories/satellites/cccp/satellites/nextgen-languages/7-tentacles/manifest.scm @@ -0,0 +1,24 @@ +;;; SPDX-License-Identifier: MPL-2.0 +;;; manifest.scm — Generic Guix manifest for RSR-compliant projects +;;; +;;; Usage: +;;; guix shell -m manifest.scm +;;; + +(specifications->manifest + '(;; Core development tools + "git" + "just" + "nickel" + "curl" + "bash" + "coreutils" + + ;; Documentation + "asciidoctor" + "pandoc" + + ;; Common build dependencies + "openssl" + "zlib" + "pkg-config")) diff --git a/rhodium-standard-repositories/satellites/rsr-certifier/manifest.scm b/rhodium-standard-repositories/satellites/rsr-certifier/manifest.scm new file mode 100644 index 00000000..dd942c7f --- /dev/null +++ b/rhodium-standard-repositories/satellites/rsr-certifier/manifest.scm @@ -0,0 +1,24 @@ +;;; SPDX-License-Identifier: MPL-2.0 +;;; manifest.scm — Generic Guix manifest for RSR-compliant projects +;;; +;;; Usage: +;;; guix shell -m manifest.scm +;;; + +(specifications->manifest + '(;; Core development tools + "git" + "just" + "nickel" + "curl" + "bash" + "coreutils" + + ;; Documentation + "asciidoctor" + "pandoc" + + ;; Common build dependencies + "openssl" + "zlib" + "pkg-config")) diff --git a/rhodium-standard-repositories/satellites/rsr-deployer/manifest.scm b/rhodium-standard-repositories/satellites/rsr-deployer/manifest.scm new file mode 100644 index 00000000..dd942c7f --- /dev/null +++ b/rhodium-standard-repositories/satellites/rsr-deployer/manifest.scm @@ -0,0 +1,24 @@ +;;; SPDX-License-Identifier: MPL-2.0 +;;; manifest.scm — Generic Guix manifest for RSR-compliant projects +;;; +;;; Usage: +;;; guix shell -m manifest.scm +;;; + +(specifications->manifest + '(;; Core development tools + "git" + "just" + "nickel" + "curl" + "bash" + "coreutils" + + ;; Documentation + "asciidoctor" + "pandoc" + + ;; Common build dependencies + "openssl" + "zlib" + "pkg-config")) diff --git a/standards-update/.machine_readable/6scm-archive/.machine_readable/6a2/META.a2ml b/standards-update/.machine_readable/6scm-archive/.machine_readable/6a2/META.a2ml index c201b113..967b35ec 100644 --- a/standards-update/.machine_readable/6scm-archive/.machine_readable/6a2/META.a2ml +++ b/standards-update/.machine_readable/6scm-archive/.machine_readable/6a2/META.a2ml @@ -7,7 +7,7 @@ version = "1.0.0" last-updated = "2026-04-11" [project-info] -license = "PMPL-1.0-or-later" +license = "MPL-2.0" author = "Jonathan D.A. Jewell (hyperpolymath)" [architecture-decisions] diff --git a/templates/CODEOWNERS b/templates/CODEOWNERS new file mode 100644 index 00000000..3a3b7f20 --- /dev/null +++ b/templates/CODEOWNERS @@ -0,0 +1,34 @@ +# SPDX-License-Identifier: MPL-2.0 +# CODEOWNERS - Define code review assignments for GitHub +# See: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners + +# Default: sole maintainer for all files +* @hyperpolymath + +# Security-sensitive files require explicit ownership +SECURITY.md @hyperpolymath +.github/workflows/ @hyperpolymath +.machine_readable/ @hyperpolymath +contractiles/ @hyperpolymath + +# License files +LICENSE @hyperpolymath +LICENSES/ @hyperpolymath + +# Configuration +.gitignore @hyperpolymath +.github/ @hyperpolymath + +# Documentation +README* @hyperpolymath +CONTRIBUTING* @hyperpolymath +CODE_OF_CONDUCT* @hyperpolymath +GOVERNANCE* @hyperpolymath +MAINTAINERS* @hyperpolymath +CHANGELOG* @hyperpolymath +ROADMAP* @hyperpolymath + +# Build and CI +Justfile @hyperpolymath +Makefile @hyperpolymath +*.sh @hyperpolymath diff --git a/templates/GOVERNANCE.adoc b/templates/GOVERNANCE.adoc new file mode 100644 index 00000000..8bbf167d --- /dev/null +++ b/templates/GOVERNANCE.adoc @@ -0,0 +1,162 @@ +// SPDX-License-Identifier: MPL-2.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 +|=== diff --git a/templates/MAINTAINERS.adoc b/templates/MAINTAINERS.adoc new file mode 100644 index 00000000..9910dd8f --- /dev/null +++ b/templates/MAINTAINERS.adoc @@ -0,0 +1,65 @@ +// SPDX-License-Identifier: MPL-2.0 +// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell += Maintainers +:toc: preamble + +== Current Maintainers + +[cols="2,3,2",options="header"] +|=== +| Name | Role | Contact + +| Jonathan D.A. Jewell | Sole Maintainer | https://github.com/hyperpolymath[@hyperpolymath] +|=== + +== Maintainer Responsibilities + +As the sole maintainer, all responsibilities apply to @hyperpolymath: + +* Reviewing and merging pull requests +* Triaging issues and feature requests +* Ensuring code quality and security standards +* Managing releases and versioning +* Upholding the project's Code of Conduct +* Maintaining documentation and examples +* Responding to security vulnerabilities + +== Contribution Process + +This is a sole-maintainer project. All contributions are welcome via: + +1. **Issues**: Report bugs, request features, ask questions +2. **Pull Requests**: Submit improvements for review +3. **Discussions**: Engage in community discussions + +All contributions will be reviewed by the maintainer. + +== Decision Making + +* Routine decisions (bug fixes, minor improvements): Made by maintainer +* Significant changes: Discussed in issues before implementation +* Breaking changes: Announced in advance with migration path + +== Becoming a Maintainer + +This project currently has a single maintainer. If you're interested in becoming a co-maintainer: + +1. Demonstrate consistent, high-quality contributions +2. Show understanding of project goals and standards +3. Participate constructively in discussions +4. Express interest to the current maintainer + +Co-maintainers may be added at the discretion of the current maintainer. + +== Contact + +For questions about project governance: + +* Open a GitHub issue in this repository +* Contact: https://github.com/hyperpolymath + +== See Also + +* link:GOVERNANCE.adoc[Governance Model] +* link:CODE_OF_CONDUCT.md[Code of Conduct] +* link:CONTRIBUTING.adoc[Contributing Guide]