diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000..3a3b7f2 --- /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/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index 987aab6..45a6c02 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -1,3 +1,7 @@ + --- name: Bug report about: Create a report to help us improve diff --git a/.github/ISSUE_TEMPLATE/custom.md b/.github/ISSUE_TEMPLATE/custom.md index 48d5f81..99ebf00 100644 --- a/.github/ISSUE_TEMPLATE/custom.md +++ b/.github/ISSUE_TEMPLATE/custom.md @@ -1,3 +1,7 @@ + --- name: Custom issue template about: Describe this issue template's purpose here. diff --git a/.github/ISSUE_TEMPLATE/documentation.md b/.github/ISSUE_TEMPLATE/documentation.md index 4fcb9f9..b1d16df 100644 --- a/.github/ISSUE_TEMPLATE/documentation.md +++ b/.github/ISSUE_TEMPLATE/documentation.md @@ -1,3 +1,7 @@ + --- name: Documentation about: Report unclear, missing, or incorrect documentation diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md index 3e8fa7e..a5a5693 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -1,3 +1,7 @@ + --- name: Feature request about: Suggest an idea for this project diff --git a/.github/ISSUE_TEMPLATE/question.md b/.github/ISSUE_TEMPLATE/question.md index fd0e2a5..c2d1f57 100644 --- a/.github/ISSUE_TEMPLATE/question.md +++ b/.github/ISSUE_TEMPLATE/question.md @@ -1,3 +1,7 @@ + --- name: Question about: Ask a question about usage or behaviour diff --git a/.github/copilot/coding-agent.yml b/.github/copilot/coding-agent.yml new file mode 100644 index 0000000..a719a77 --- /dev/null +++ b/.github/copilot/coding-agent.yml @@ -0,0 +1,6 @@ +mcp_servers: + boj-server: + command: npx + args: ["-y", "@hyperpolymath/boj-server@latest"] + env: + BOJ_URL: http://localhost:7700 diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml new file mode 100644 index 0000000..26846e6 --- /dev/null +++ b/.github/workflows/codeql.yml @@ -0,0 +1,43 @@ +# SPDX-License-Identifier: MPL-2.0 +name: CodeQL Security Analysis +on: + push: + branches: [main, master] + pull_request: + branches: [main, master] + schedule: + - cron: '0 6 * * 1' +# Estate guardrail: cancel superseded runs so re-pushes / rebased PR +# updates do not pile up queued runs against the shared account-wide +# Actions concurrency pool. Applied only to read-only check workflows +# (no publish/mutation), so cancelling a superseded run is always safe. +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true +permissions: + contents: read +jobs: + analyze: + runs-on: ubuntu-latest + timeout-minutes: 15 + permissions: + contents: read + security-events: write + strategy: + fail-fast: false + matrix: + include: + - language: javascript-typescript + build-mode: none + steps: + - name: Checkout + uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + - name: Initialize CodeQL + uses: github/codeql-action/init@7211b7c8077ea37d8641b6271f6a365a22a5fbfa # v3 + with: + languages: ${{ matrix.language }} + build-mode: ${{ matrix.build-mode }} + - name: Perform CodeQL Analysis + uses: github/codeql-action/analyze@7211b7c8077ea37d8641b6271f6a365a22a5fbfa # v3 + with: + category: "/language:${{ matrix.language }}" diff --git a/.github/workflows/dependabot-automerge.yml b/.github/workflows/dependabot-automerge.yml index ca86baa..cff4451 100644 --- a/.github/workflows/dependabot-automerge.yml +++ b/.github/workflows/dependabot-automerge.yml @@ -35,29 +35,25 @@ # bumps for dependabot/fetch-metadata flow through the same path. name: Dependabot Auto-Merge - on: pull_request: types: [opened, reopened, synchronize] - permissions: - contents: write # needed to enable auto-merge - pull-requests: write # needed to approve + contents: write # needed to enable auto-merge + pull-requests: write # needed to approve # NB: keep narrow — do NOT add secrets: read or id-token: write here. - jobs: automerge: # Only run for PRs actually authored by Dependabot. if: github.actor == 'dependabot[bot]' && github.event.pull_request.user.login == 'dependabot[bot]' runs-on: ubuntu-latest - + timeout-minutes: 15 steps: - name: Fetch Dependabot metadata id: meta uses: dependabot/fetch-metadata@25dd0e34f4fe68f24cc83900b1fe3fe149efef98 # v3.1.0 with: github-token: ${{ secrets.GITHUB_TOKEN }} - # --- Policy gate ------------------------------------------------------- # Outputs from fetch-metadata we care about: # update-type → version-update:semver-{patch,minor,major} @@ -106,7 +102,6 @@ jobs: echo "security=$is_security" >> "$GITHUB_OUTPUT" echo "update_type=$UPDATE_TYPE" >> "$GITHUB_OUTPUT" echo "ghsa=$GHSA_ID" >> "$GITHUB_OUTPUT" - - name: Approve PR (if policy allows) if: steps.policy.outputs.action == 'automerge' env: @@ -115,7 +110,6 @@ jobs: run: | gh pr review --approve "$PR_URL" \ --body "Auto-approving Dependabot security update (${{ steps.policy.outputs.ghsa }}, ${{ steps.policy.outputs.update_type }}). Policy: low/moderate security patches/minors only." - - name: Enable auto-merge (if policy allows) if: steps.policy.outputs.action == 'automerge' env: @@ -123,7 +117,6 @@ jobs: PR_URL: ${{ github.event.pull_request.html_url }} run: | gh pr merge --auto --squash "$PR_URL" - - name: Write decision to step summary env: ACTION: ${{ steps.policy.outputs.action }} diff --git a/.github/workflows/dogfood-gate.yml b/.github/workflows/dogfood-gate.yml index 155980a..75de35a 100644 --- a/.github/workflows/dogfood-gate.yml +++ b/.github/workflows/dogfood-gate.yml @@ -5,16 +5,13 @@ # Validates that the repo uses hyperpolymath's own formats and tools. # Companion to static-analysis-gate.yml (security) — this is for format compliance. name: Dogfood Gate - on: pull_request: branches: ['**'] push: branches: [main, master] - permissions: contents: read - jobs: # --------------------------------------------------------------------------- # Job 1: A2ML manifest validation @@ -22,7 +19,7 @@ jobs: a2ml-validate: name: Validate A2ML manifests runs-on: ubuntu-latest - + timeout-minutes: 15 steps: - name: Checkout repository uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3 @@ -35,14 +32,12 @@ jobs: if [ "$COUNT" -eq 0 ]; then echo "::warning::No .a2ml manifest files found. Every RSR repo should have 0-AI-MANIFEST.a2ml" fi - - name: Validate A2ML manifests if: steps.detect.outputs.count > 0 uses: hyperpolymath/a2ml-validate-action@59145c7d1039fa3059b3ecacdb50ee23d7505898 # main with: path: '.' strict: 'false' - - name: Write summary run: | A2ML_COUNT="${{ steps.detect.outputs.count }}" @@ -59,14 +54,13 @@ jobs: echo "" >> "$GITHUB_STEP_SUMMARY" echo "Scanned **${A2ML_COUNT}** .a2ml file(s). See step output for details." >> "$GITHUB_STEP_SUMMARY" fi - # --------------------------------------------------------------------------- # Job 2: K9 contract validation # --------------------------------------------------------------------------- k9-validate: name: Validate K9 contracts runs-on: ubuntu-latest - + timeout-minutes: 15 steps: - name: Checkout repository uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3 @@ -83,14 +77,12 @@ jobs: if [ "$COUNT" -eq 0 ] && [ "$CONFIG_COUNT" -gt 0 ]; then echo "::warning::Found $CONFIG_COUNT config files but no K9 contracts. Run k9iser to generate contracts." fi - - name: Validate K9 contracts if: steps.detect.outputs.k9_count > 0 uses: hyperpolymath/k9-validate-action@2d96f43c538964b097d159ed3a56ba5b5ceca227 # main with: path: '.' strict: 'false' - - name: Write summary run: | K9_COUNT="${{ steps.detect.outputs.k9_count }}" @@ -108,14 +100,13 @@ jobs: echo "" >> "$GITHUB_STEP_SUMMARY" echo "Validated **${K9_COUNT}** K9 contract(s) against **${CFG_COUNT}** config file(s)." >> "$GITHUB_STEP_SUMMARY" fi - # --------------------------------------------------------------------------- # Job 3: Empty-linter — invisible character detection # --------------------------------------------------------------------------- empty-lint: name: Empty-linter (invisible characters) runs-on: ubuntu-latest - + timeout-minutes: 15 steps: - name: Checkout repository uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3 @@ -153,7 +144,6 @@ jobs: REL_PATH="${filepath#$GITHUB_WORKSPACE/}" echo "::warning file=${REL_PATH}::Invisible Unicode characters detected (zero-width space, BOM, NBSP, etc.)" done < /tmp/empty-lint-results.txt - - name: Write summary run: | if [ "${{ steps.lint.outputs.ready }}" = "true" ]; then @@ -172,14 +162,13 @@ jobs: echo "" >> "$GITHUB_STEP_SUMMARY" echo "Skipped: empty-linter not available." >> "$GITHUB_STEP_SUMMARY" fi - # --------------------------------------------------------------------------- # Job 4: Groove manifest check (for repos that should expose services) # --------------------------------------------------------------------------- groove-check: name: Groove manifest check runs-on: ubuntu-latest - + timeout-minutes: 15 steps: - name: Checkout repository uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3 @@ -220,7 +209,6 @@ jobs: if [ "$HAS_SERVER" = "true" ] && [ "$HAS_MANIFEST" = "false" ] && [ "$HAS_GROOVE_CODE" = "false" ]; then echo "::warning::This repo has server code but no Groove endpoint. Add .well-known/groove/manifest.json for service discovery." fi - - name: Write summary run: | echo "## Groove Protocol Check" >> "$GITHUB_STEP_SUMMARY" @@ -230,16 +218,15 @@ jobs: echo "| Static manifest (.well-known/groove/manifest.json) | ${{ steps.groove.outputs.has_manifest }} |" >> "$GITHUB_STEP_SUMMARY" echo "| Groove endpoint in code | ${{ steps.groove.outputs.has_groove_code }} |" >> "$GITHUB_STEP_SUMMARY" echo "| Has HTTP server code | ${{ steps.groove.outputs.has_server }} |" >> "$GITHUB_STEP_SUMMARY" - # --------------------------------------------------------------------------- # Job 5: Dogfooding summary # --------------------------------------------------------------------------- dogfood-summary: name: Dogfooding compliance summary runs-on: ubuntu-latest + timeout-minutes: 15 needs: [a2ml-validate, k9-validate, empty-lint, groove-check] if: always() - steps: - name: Checkout repository uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3 @@ -306,4 +293,3 @@ jobs: *Generated by the [Dogfood Gate](https://github.com/hyperpolymath/rsr-template-repo) workflow.* *Dogfooding is guinea pig fooding — we test our tools on ourselves.* EOF - diff --git a/.github/workflows/governance.yml b/.github/workflows/governance.yml index 653ef98..e0c379b 100644 --- a/.github/workflows/governance.yml +++ b/.github/workflows/governance.yml @@ -11,13 +11,11 @@ # (rust-ci, codeql, dependabot, release, scan/mirror/pages plumbing). name: Governance - on: push: branches: [main, master] pull_request: workflow_dispatch: - # Estate guardrail: cancel superseded runs so re-pushes / rebased PR # updates do not pile up queued runs against the shared account-wide # Actions concurrency pool. Applied only to read-only check workflows @@ -25,10 +23,9 @@ on: concurrency: group: ${{ github.workflow }}-${{ github.ref }} cancel-in-progress: true - permissions: contents: read - jobs: governance: - uses: hyperpolymath/standards/.github/workflows/governance-reusable.yml@main + uses: hyperpolymath/standards/.github/workflows/governance-reusable.yml@861b5e911d9e5dcfb3c0ab3dd2a9a3c8fd0a1613 + timeout-minutes: 10 diff --git a/.github/workflows/hypatia-scan.yml b/.github/workflows/hypatia-scan.yml index 1d6417e..a686797 100644 --- a/.github/workflows/hypatia-scan.yml +++ b/.github/workflows/hypatia-scan.yml @@ -3,7 +3,6 @@ # See standards#191 for the reusable's purpose and design. name: Hypatia Security Scan - on: push: branches: [main, master, develop] @@ -17,12 +16,10 @@ on: concurrency: group: ${{ github.workflow }}-${{ github.ref }} cancel-in-progress: true - permissions: contents: read security-events: write pull-requests: write - jobs: hypatia: uses: hyperpolymath/standards/.github/workflows/hypatia-scan-reusable.yml@97df762107501909f50bb770e9bc200b6c415600 diff --git a/.github/workflows/instant-sync.yml b/.github/workflows/instant-sync.yml index d022c3e..0994325 100644 --- a/.github/workflows/instant-sync.yml +++ b/.github/workflows/instant-sync.yml @@ -1,19 +1,17 @@ # SPDX-License-Identifier: MPL-2.0 # Instant Forge Sync - Triggers propagation to all forges on push/release name: Instant Sync - on: push: branches: [main, master] release: types: [published] - permissions: contents: read - jobs: dispatch: runs-on: ubuntu-latest + timeout-minutes: 15 steps: - name: Trigger Propagation uses: peter-evans/repository-dispatch@28959ce8df70de7be546dd1250a005dd32156697 # v3 @@ -28,7 +26,6 @@ jobs: "sha": "${{ github.sha }}", "forges": "" } - - name: Confirm env: REPO_NAME: ${{ github.event.repository.name }} diff --git a/.github/workflows/jekyll-gh-pages.yml b/.github/workflows/jekyll-gh-pages.yml new file mode 100644 index 0000000..5178f85 --- /dev/null +++ b/.github/workflows/jekyll-gh-pages.yml @@ -0,0 +1,48 @@ +# SPDX-License-Identifier: MPL-2.0 +# Sample workflow for building and deploying a Jekyll site to GitHub Pages +name: Deploy Jekyll with GitHub Pages dependencies preinstalled +on: + # Runs on pushes targeting the default branch + push: + branches: ["main"] + # Allows you to run this workflow manually from the Actions tab + workflow_dispatch: +# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages +permissions: + contents: read + pages: write + id-token: write +# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. +# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. +concurrency: + group: "pages" + cancel-in-progress: false +jobs: + # Build job + build: + runs-on: ubuntu-latest + timeout-minutes: 15 + steps: + - name: Checkout + uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6 + - name: Setup Pages + uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0 + - name: Build with Jekyll + uses: actions/jekyll-build-pages@44a6e6beabd48582f863aeeb6cb2151cc1716697 # v1 + with: + source: ./ + destination: ./_site + - name: Upload artifact + uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v4 + # Deployment job + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + timeout-minutes: 15 + needs: build + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0 diff --git a/.github/workflows/jekyll.yml b/.github/workflows/jekyll.yml new file mode 100644 index 0000000..9485bce --- /dev/null +++ b/.github/workflows/jekyll.yml @@ -0,0 +1,62 @@ +# SPDX-License-Identifier: MPL-2.0 +# This workflow uses actions that are not certified by GitHub. +# They are provided by a third-party and are governed by +# separate terms of service, privacy policy, and support +# documentation. + +# Sample workflow for building and deploying a Jekyll site to GitHub Pages +name: Deploy Jekyll site to Pages +on: + # Runs on pushes targeting the default branch + push: + branches: ["main"] + # Allows you to run this workflow manually from the Actions tab + workflow_dispatch: +# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages +permissions: + contents: read + pages: write + id-token: write +# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. +# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. +concurrency: + group: "pages" + cancel-in-progress: false +jobs: + # Build job + build: + runs-on: ubuntu-latest + timeout-minutes: 15 + steps: + - name: Checkout + uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6 + - name: Setup Ruby + # https://github.com/ruby/setup-ruby/releases/tag/v1.207.0 + uses: ruby/setup-ruby@afeafc3d1ab54a631816aba4c914a0081c12ff2f + with: + ruby-version: '3.1' # Not needed with a .ruby-version file + bundler-cache: true # runs 'bundle install' and caches installed gems automatically + cache-version: 0 # Increment this number if you need to re-download cached gems + - name: Setup Pages + id: pages + uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0 + - name: Build with Jekyll + # Outputs to the './_site' directory by default + run: bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}" + env: + JEKYLL_ENV: production + - name: Upload artifact + # Automatically uploads an artifact from the './_site' directory by default + uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v4 + # Deployment job + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + timeout-minutes: 15 + needs: build + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0 diff --git a/.github/workflows/mirror.yml b/.github/workflows/mirror.yml index 2083ca6..c85df64 100644 --- a/.github/workflows/mirror.yml +++ b/.github/workflows/mirror.yml @@ -1,6 +1,5 @@ # SPDX-License-Identifier: MPL-2.0 name: Mirror to Git Forges - on: push: branches: [main] diff --git a/.github/workflows/scorecard-enforcer.yml b/.github/workflows/scorecard-enforcer.yml index 4919e50..64071da 100644 --- a/.github/workflows/scorecard-enforcer.yml +++ b/.github/workflows/scorecard-enforcer.yml @@ -1,14 +1,12 @@ # SPDX-License-Identifier: MPL-2.0 # Prevention workflow - runs OpenSSF Scorecard and fails on low scores name: OpenSSF Scorecard Enforcer - on: push: branches: [main] schedule: - - cron: '0 6 * * 1' # Weekly on Monday + - cron: '0 6 * * 1' # Weekly on Monday workflow_dispatch: - # Estate guardrail: cancel superseded runs so re-pushes / rebased PR # updates do not pile up queued runs against the shared account-wide # Actions concurrency pool. Applied only to read-only check workflows @@ -16,33 +14,29 @@ on: concurrency: group: ${{ github.workflow }}-${{ github.ref }} cancel-in-progress: true - permissions: contents: read - jobs: scorecard: runs-on: ubuntu-latest + timeout-minutes: 15 permissions: security-events: write - id-token: write # For OIDC + id-token: write # For OIDC steps: - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3 with: persist-credentials: false - - name: Run Scorecard uses: ossf/scorecard-action@4eaacf0543bb3f2c246792bd56e8cdeffafb205a # v2.4.3 with: results_file: results.sarif results_format: sarif publish_results: true - - name: Upload SARIF uses: github/codeql-action/upload-sarif@87557b9c84dde89fdd9b10e88954ac2f4248e463 # v4 with: sarif_file: results.sarif - - name: Check minimum score run: | # Parse score from results @@ -57,10 +51,10 @@ jobs: echo "::error::Scorecard score $SCORE is below minimum $MIN_SCORE" exit 1 fi - # Check specific high-priority items check-critical: runs-on: ubuntu-latest + timeout-minutes: 15 steps: - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3 @@ -70,7 +64,6 @@ jobs: echo "::error::SECURITY.md is required" exit 1 fi - - name: Check for pinned dependencies run: | # Check workflows for unpinned actions diff --git a/.github/workflows/secret-scanner.yml b/.github/workflows/secret-scanner.yml index 586cdc0..c326dc4 100644 --- a/.github/workflows/secret-scanner.yml +++ b/.github/workflows/secret-scanner.yml @@ -1,6 +1,5 @@ # SPDX-License-Identifier: PMPL-1.0 name: Secret Scanner - on: pull_request: push: @@ -9,10 +8,8 @@ on: concurrency: group: ${{ github.workflow }}-${{ github.ref }} cancel-in-progress: true - permissions: contents: read - jobs: scan: uses: hyperpolymath/standards/.github/workflows/secret-scanner-reusable.yml@3e4bd4c93911750727e2e4c66dff859e00079da0 diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 7309fa9..286c865 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -1,4 +1,5 @@ # SPDX-License-Identifier: MPL-2.0 +// Owner: Jonathan D.A. Jewell # Primary CI/CD - GitLab is the source of truth stages: @@ -6,20 +7,16 @@ stages: - lint - test - build - variables: CARGO_HOME: ${CI_PROJECT_DIR}/.cargo - cache: key: ${CI_COMMIT_REF_SLUG} paths: - .cargo/ - target/ - # ================== # Security Scanning # ================== - trivy: stage: security image: aquasec/trivy:latest @@ -27,21 +24,12 @@ trivy: - trivy fs --exit-code 0 --severity HIGH,CRITICAL --format table . - trivy fs --exit-code 1 --severity CRITICAL . allow_failure: false - -gitleaks: - stage: security - image: zricethezav/gitleaks:latest - script: - - gitleaks detect --source . --verbose --redact - allow_failure: false - semgrep: stage: security image: returntocorp/semgrep script: - semgrep --config auto --error . allow_failure: true - cargo-audit: stage: security image: rust:latest @@ -51,7 +39,6 @@ cargo-audit: rules: - exists: - Cargo.toml - cargo-deny: stage: security image: rust:latest @@ -62,7 +49,6 @@ cargo-deny: - exists: - Cargo.toml allow_failure: true - mix-audit: stage: security image: elixir:latest @@ -75,11 +61,9 @@ mix-audit: - exists: - mix.exs allow_failure: true - # ================== # Linting # ================== - rustfmt: stage: lint image: rust:latest @@ -89,7 +73,6 @@ rustfmt: rules: - exists: - Cargo.toml - clippy: stage: lint image: rust:latest @@ -100,7 +83,6 @@ clippy: - exists: - Cargo.toml allow_failure: true - mix-format: stage: lint image: elixir:latest @@ -109,7 +91,6 @@ mix-format: rules: - exists: - mix.exs - credo: stage: lint image: elixir:latest @@ -121,11 +102,9 @@ credo: - exists: - mix.exs allow_failure: true - # ================== # Testing # ================== - cargo-test: stage: test image: rust:latest @@ -134,7 +113,6 @@ cargo-test: rules: - exists: - Cargo.toml - mix-test: stage: test image: elixir:latest @@ -145,11 +123,9 @@ mix-test: rules: - exists: - mix.exs - # ================== # Build # ================== - cargo-build: stage: build image: rust:latest @@ -162,7 +138,6 @@ cargo-build: rules: - exists: - Cargo.toml - mix-build: stage: build image: elixir:latest @@ -173,3 +148,8 @@ mix-build: rules: - exists: - mix.exs +trufflehog: + stage: security + image: trufflesecurity/trufflehog:latest + script: + - trufflehog git file://. --only-verified --fail diff --git a/.machine_readable/6a2/0-AI-MANIFEST.a2ml b/.machine_readable/6a2/0-AI-MANIFEST.a2ml new file mode 100644 index 0000000..cede8a9 --- /dev/null +++ b/.machine_readable/6a2/0-AI-MANIFEST.a2ml @@ -0,0 +1,22 @@ +# AI Manifest for 6a2 Directory + +## Purpose + +This manifest declares the AI-assistant context for the 6a2 machine-readable metadata directory. + +## Canonical Locations + +The 6 core A2ML files MUST exist in this directory: +1. AGENTIC.a2ml +2. ECOSYSTEM.a2ml +3. META.a2ml +4. NEUROSYM.a2ml +5. PLAYBOOK.a2ml +6. STATE.a2ml + +## Invariants + +- No duplicate files in root directory +- Single source of truth: this directory is authoritative +- No stale metadata + diff --git a/.machine_readable/6a2/README.adoc b/.machine_readable/6a2/README.adoc new file mode 100644 index 0000000..ac38c25 --- /dev/null +++ b/.machine_readable/6a2/README.adoc @@ -0,0 +1,20 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell +# A2ML 6a2 Directory + +This directory contains the 6 core A2ML machine-readable metadata files for this repository. + +## Files + +- `AGENTIC.a2ml` - AI agent operational gating, safety controls +- `ECOSYSTEM.a2ml` - Project ecosystem position, relationships, explicit boundaries +- `META.a2ml` - Architecture decisions (ADRs), development practices, design rationale +- `NEUROSYM.a2ml` - Symbolic semantics, composition algebra +- `PLAYBOOK.a2ml` - Executable plans, operational runbooks +- `STATE.a2ml` - Project state, phase, milestones, session history + +## Standards Compliance + +These files follow the A2ML Format Family specification from: +https://github.com/hyperpolymath/standards/tree/main/a2ml + diff --git a/.machine_readable/ADJUST.contractile b/.machine_readable/ADJUST.contractile deleted file mode 100644 index 13f934c..0000000 --- a/.machine_readable/ADJUST.contractile +++ /dev/null @@ -1,126 +0,0 @@ -; SPDX-License-Identifier: MPL-2.0 -; ADJUST.contractile — Accessibility invariants for tangle -; "ADJUST" = Accessibility & Digital Justice for Universal Software & Technology -; -; Part of the contractile family: MUST, TRUST, DUST, INTENT, ADJUST -; This file is machine-readable. LLM/SLM agents MUST NOT violate these invariants. - -; ── Definitions ────────────────────────────────────────────────── -; -; ADJUST (noun/verb) -; The accessibility contractile. Defines how software must adapt to serve -; all users regardless of ability, device, or context. Named for the verb -; "adjust" — to make suitable, to adapt, to accommodate — which is the -; core action of accessible design. -; -; Scope: -; ADJUST governs all user-facing interfaces: GUI, TUI, CLI, web, mobile, -; documentation, error messages, and installation flows. It applies to -; both human users and assistive technologies (screen readers, switch -; devices, braille displays, voice control). -; -; Relationship to other contractiles: -; - MUST: ADJUST invariants are a subset of MUST — violating ADJUST -; is a MUST violation. ADJUST exists separately because accessibility -; rules are numerous enough to warrant their own file, and because -; LLMs frequently forget accessibility unless explicitly reminded. -; - TRUST: ADJUST does not affect trust levels. All trust tiers must -; respect ADJUST invariants equally. -; - DUST: Deprecating a feature does not exempt it from ADJUST until -; it is fully removed. Deprecated UI must remain accessible. -; - INTENT: ADJUST supports the anti-purpose "this software is NOT -; only for able-bodied users with modern hardware." -; -; Standard: WCAG 2.2 Level AA (minimum) -; https://www.w3.org/WAI/WCAG22/quickref/?levels=aaa -; -; Why a separate file: -; Experience shows LLMs and developers alike treat accessibility as an -; afterthought. By placing invariants in a contractile that is loaded -; at session start, we make it structurally impossible to forget. -; -; ── End Definitions ────────────────────────────────────────────── - -(adjust-contractile - (version "1.0.0") - (full-name "Accessibility & Digital Justice for Universal Software & Technology") - (standard "WCAG-2.2-AA") - (repo "tangle") - - (invariants - ; ── Visual ── - (adjust "colour-contrast-ratio >= 4.5:1 for normal text") - (adjust "colour-contrast-ratio >= 3:1 for large text (18pt+ or 14pt+ bold)") - (adjust "no information conveyed by colour alone") - (adjust "no flashing or strobing content (3 flashes/second max)") - (adjust "text resizable to 200% without loss of content or function") - (adjust "focus indicators visible on all interactive elements") - - ; ── Keyboard ── - (adjust "all interactive elements reachable via keyboard (Tab/Shift+Tab)") - (adjust "no keyboard traps — user can always Tab away") - (adjust "skip navigation link present on pages with repeated blocks") - (adjust "logical focus order follows visual reading order") - - ; ── Screen reader ── - (adjust "all images have meaningful alt text (or alt='' if decorative)") - (adjust "all form inputs have associated labels") - (adjust "ARIA landmarks used for page regions (main, nav, banner, etc.)") - (adjust "dynamic content updates announced via aria-live regions") - (adjust "semantic HTML used (headings, lists, tables) — not div soup") - - ; ── Interactive ── - (adjust "touch targets minimum 44x44px on mobile/touch interfaces") - (adjust "error messages identify the field and describe the error") - (adjust "error messages not conveyed by colour or position alone") - (adjust "form validation provides suggestions for correction") - - ; ── Media ── - (adjust "video has captions (closed or open)") - (adjust "audio-only content has text transcript") - (adjust "no autoplay of media with sound") - - ; ── Motion ── - (adjust "animations respect prefers-reduced-motion media query") - (adjust "no content depends on motion to convey meaning") - - ; ── CLI/TUI ── - (adjust "CLI output must not rely solely on colour (use symbols: [OK] [FAIL])") - (adjust "TUI must support high-contrast mode") - (adjust "all CLI commands support --help with plain-text output") - (adjust "error messages written in plain language, not jargon or codes alone") - - ; ── Documentation ── - (adjust "docs use clear language, short sentences, logical structure") - (adjust "code examples include comments explaining non-obvious steps") - (adjust "diagrams have text descriptions or alt text") - - ; ── Internationalisation (i18n) ── - (adjust "all user-facing strings externalisable for translation") - (adjust "no hardcoded English in error messages — use message keys") - (adjust "date/time/number formats locale-aware") - (adjust "RTL (right-to-left) layout support where applicable") - (adjust "Unicode handled correctly throughout (UTF-8 everywhere)") - ) - - (related-resources - ; LOL — super-parallel corpus crawler for 1500+ languages - ; Use for linguistic data, translation coverage, and i18n validation - (lol "standards/lol — multilingual NLP corpus, see README.adoc") - (polyglot-i18n "polyglot-i18n — i18n framework and WASM translation engine") - ) - - (enforcement - (ci "accessibility linting in quality.yml workflow") - (pr-block "PR blocked if accessibility regression detected") - (tool "axe-core or pa11y for automated checks on web UI") - (tool "CLI output inspected for colour-only signalling") - (manual "manual screen reader test before major releases") - ) - - (notes - "These are MINIMUM requirements. Exceeding them (AAA) is encouraged." - "When in doubt about an accessibility decision, ask — don't guess." - "Accessibility is not optional polish — it is a structural requirement." - ) -) diff --git a/.machine_readable/INTENT.contractile b/.machine_readable/INTENT.contractile deleted file mode 100644 index 93af5ab..0000000 --- a/.machine_readable/INTENT.contractile +++ /dev/null @@ -1,72 +0,0 @@ -; SPDX-License-Identifier: MPL-2.0 -; INTENT.contractile — Purpose and scope for tangle -; Helps LLM/SLM agents understand what this repo IS and IS NOT. -; -; Part of the contractile family: MUST, TRUST, DUST, INTENT, ADJUST - -; ── Definitions ────────────────────────────────────────────────── -; -; INTENT (noun) -; The purpose contractile. Defines what this repository IS, what it is -; NOT (anti-purpose), and which architectural decisions are load-bearing. -; Without INTENT, LLMs drift into scope creep, reverse key decisions, -; or add features that belong in a different repo. -; -; Scope: -; INTENT governs the conceptual boundaries of the project — its reason -; for existing, its domain, and its relationship to the ecosystem. -; It does NOT specify implementation details (that's MUST and code). -; -; Relationship to other contractiles: -; - MUST: INTENT explains WHY certain MUSTs exist. If you don't -; understand a MUST, read INTENT first. -; - TRUST: The "ask-before-touching" section in INTENT maps directly -; to TRUST.trust-deny for the most sensitive areas. -; - ADJUST: INTENT's anti-purpose should include "this software is -; NOT only for users with perfect vision/hearing/mobility." -; - DUST: When INTENT changes (repo pivots), related DUST entries -; should be created for the abandoned direction. -; -; ── End Definitions ────────────────────────────────────────────── - -(intent-contractile - (version "1.0.0") - (repo "tangle") - - ; === Purpose (what this repo IS) === - (purpose - "{{ONE_PARAGRAPH_PURPOSE}}" - ) - - ; === Anti-Purpose (what this repo is NOT — prevents scope creep) === - (anti-purpose - "{{ONE_PARAGRAPH_ANTI_PURPOSE}}" - ; Examples: - ; "This is NOT a general-purpose database — it solves one specific problem." - ; "This is NOT a framework — it is a library with a focused API." - ; "This does NOT handle authentication — that is delegated to [other repo]." - ) - - ; === Key Architectural Decisions That Must Not Be Reversed === - (architectural-invariants - ; *REMINDER: List the foundational decisions* - ; ("Idris2 for ABI definitions — dependent types prove interface correctness") - ; ("Zig for FFI — zero-cost C ABI compatibility") - ; ("Elixir for supervision — OTP fault tolerance") - ) - - ; === Sensitive Areas (if in doubt, ask) === - (ask-before-touching - ; *REMINDER: List areas where LLMs should check before modifying* - ; "src/abi/ — formal proofs, changes require re-verification" - ; "ffi/zig/ — C ABI boundary, changes affect all language bindings" - ; ".machine_readable/ — checkpoint files, format is specified" - ) - - ; === Ecosystem Position === - (ecosystem - (belongs-to "{{MONOREPO_OR_STANDALONE}}") - (depends-on ("{{DEP1}}" "{{DEP2}}")) - (depended-on-by ("{{CONSUMER1}}" "{{CONSUMER2}}")) - ) -) diff --git a/.machine_readable/MUST.contractile b/.machine_readable/MUST.contractile deleted file mode 100644 index 8d4748d..0000000 --- a/.machine_readable/MUST.contractile +++ /dev/null @@ -1,91 +0,0 @@ -; SPDX-License-Identifier: MPL-2.0 -; MUST.contractile — Baseline invariants for tangle -; These constraints MUST NOT be violated. K9 validators enforce them. -; -; Part of the contractile family: MUST, TRUST, DUST, INTENT, ADJUST - -; ── Definitions ────────────────────────────────────────────────── -; -; MUST (noun/verb) -; The hard-constraint contractile. Defines invariants that are structurally -; required for the repository to function correctly and safely. Violating -; a MUST is always a bug — there are no "soft" MUSTs. -; -; Scope: -; MUST governs code, configuration, CI, and structure. It does NOT govern -; style, preference, or approach — those belong in CLAUDE.md or coding -; standards. MUST is for things that break the project if violated. -; -; Relationship to other contractiles: -; - TRUST: MUST is enforced regardless of trust level. Even maximal-trust -; agents cannot violate MUST constraints. -; - ADJUST: All ADJUST invariants are implicitly MUST invariants too. -; ADJUST exists separately for visibility. -; - INTENT: MUST protects the architectural decisions described in INTENT. -; - DUST: When a feature enters DUST (deprecation), its MUST constraints -; remain active until the feature is fully removed. -; -; Enforcement: -; K9 validators in contractiles/k9/ machine-check MUST constraints. -; CI runs these on every PR. Violations block merge. -; -; ── End Definitions ────────────────────────────────────────────── - -(must-contractile - (version "1.0.0") - (repo "tangle") - - ; === Universal Invariants (apply to ALL repos) === - - (invariants - ; Paths - (must "no hardcoded absolute paths (/home/*, /mnt/*, /var/mnt/*)") - (must "all paths use env vars, XDG dirs, or relative references") - - ; Language policy - (must "no new TypeScript files") - (must "no new Python files") - (must "no new Go files") - (must "no npm/bun/yarn/pnpm dependencies — Deno only") - - ; Dangerous patterns - (must "no believe_me (Idris2)") - (must "no assert_total (Idris2)") - (must "no Admitted (Coq)") - (must "no sorry (Lean)") - (must "no unsafeCoerce (Haskell)") - (must "no Obj.magic (OCaml)") - (must "no unsafe {} blocks without safety comment (Rust)") - - ; License - (must "SPDX-License-Identifier header on every source file") - (must "no removal or modification of LICENSE file") - - ; Structure - (must ".machine_readable/ directory preserved") - (must "0-AI-MANIFEST.a2ml preserved") - (must "no SCM files in repo root — only in .machine_readable/") - - ; CI - (must "no removal of CI workflows without explicit approval") - (must "all GitHub Actions SHA-pinned") - - ; Code quality - (must "tests must not be deleted or weakened") - (must "generated code in generated/ directory only") - (must "no introduction of OWASP top 10 vulnerabilities") - - ; ABI/FFI (if applicable) - (must "no modification of ABI contracts without proof update") - (must "no removal of formal verification proofs") - ) - - ; === Project-Specific Invariants === - ; *REMINDER: Add invariants specific to this repo* - ; (must "# Add project-specific invariants here") - - (enforcement - (k9-validator "contractiles/k9/must-check.k9.ncl") - (ci "quality.yml runs must-check on every PR") - ) -) diff --git a/.machine_readable/TRUST.contractile b/.machine_readable/TRUST.contractile deleted file mode 100644 index 2504e79..0000000 --- a/.machine_readable/TRUST.contractile +++ /dev/null @@ -1,80 +0,0 @@ -; SPDX-License-Identifier: MPL-2.0 -; TRUST.contractile — Trust boundaries for tangle -; Defines what LLM/SLM agents are trusted to do without asking. -; -; Part of the contractile family: MUST, TRUST, DUST, INTENT, ADJUST - -; ── Definitions ────────────────────────────────────────────────── -; -; TRUST (noun/verb) -; The permission contractile. Defines the boundary between what an AI -; agent may do autonomously and what requires human approval. Trust is -; graduated — not binary — with four levels from minimal to maximal. -; -; Trust levels: -; - maximal: Agent may read, build, test, lint, format, heal freely. -; Only destructive/external actions require approval. -; - standard: Agent may read and build. Test/lint need approval. -; - restricted: Agent may read only. All modifications need approval. -; - minimal: Agent may read specific files only. Everything else blocked. -; -; Scope: -; TRUST governs AI agent behaviour only. It does not affect human -; contributors — humans follow CONTRIBUTING.md and GOVERNANCE.adoc. -; -; Relationship to other contractiles: -; - MUST: Trust never overrides MUST. Even at maximal trust, MUST -; violations are blocked. -; - ADJUST: Trust does not exempt from ADJUST. All trust tiers must -; produce accessible output. -; - INTENT: TRUST.trust-deny protects the sensitive areas listed in -; INTENT.ask-before-touching. -; - DUST: Deprecated features have the same trust rules as active ones. -; -; ── End Definitions ────────────────────────────────────────────── - -(trust-contractile - (version "1.0.0") - (repo "tangle") - - (trust-level "maximal") ; maximal | standard | restricted | minimal - - ; === Maximal Trust (default) === - ; LLM may freely do these without asking: - (trust-actions - "read" ; Read any file in the repo - "build" ; Run build commands - "test" ; Run test suites - "lint" ; Run linters and formatters - "format" ; Auto-format code - "doctor" ; Run self-diagnostics - "heal" ; Attempt automatic repair - "git-status" ; Check git status - "git-diff" ; View diffs - "git-log" ; View history - ) - - ; === Denied Actions (always require human approval) === - (trust-deny - "delete-branch" ; Could lose work - "force-push" ; Overwrites history - "modify-ci-secrets" ; Security sensitive - "publish" ; External visibility - "push-to-main" ; Protected branch - "delete-files-bulk" ; More than 5 files at once - "modify-license" ; Legal implications - "modify-security-policy" ; Security implications - "remove-proofs" ; Formal verification regression - "disable-ci-checks" ; Safety regression - ) - - ; === Trust Boundary === - (trust-boundary "repo") ; LLM confined to this repo unless explicitly told otherwise - - ; === Override === - ; Repos requiring tighter trust override these settings with justification: - ; (override - ; (trust-level "restricted") - ; (reason "Contains production secrets / handles PII / etc.") - ; ) -) diff --git a/.machine_readable/agent_instructions/README.adoc b/.machine_readable/agent_instructions/README.adoc deleted file mode 100644 index 9bc2e24..0000000 --- a/.machine_readable/agent_instructions/README.adoc +++ /dev/null @@ -1,41 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -= Agent Instructions -:toc: preamble - -Methodology-aware configuration for AI agents. Read by any AI agent -(Claude, Gemini, Copilot, etc.) at session start. - -== Files - -[cols="1,3"] -|=== -| File | Purpose - -| `methodology.a2ml` -| Default mode, invariants, ring ceiling, priority weights, convergent budget - -| `coverage.a2ml` -| Session coverage tracking — what was visited, what was skipped, what has MUSTs - -| `debt.a2ml` -| Meander debt — things found but not fixed, carried between sessions -|=== - -== How Agents Use These - -1. Read `methodology.a2ml` at session start — know mode, invariants, ceiling -2. Read `coverage.a2ml` — know what was visited last time, what was skipped -3. Read `debt.a2ml` — know what's outstanding from previous sessions -4. At session end, update `coverage.a2ml` and `debt.a2ml` - -== Relationship to Other Files - -* `AGENTIC.a2ml` says WHAT agents can do (permissions, gating) -* `agent_instructions/` says HOW agents should work (methodology) -* `bot_directives/` says what the gitbot-fleet does (fleet-specific) -* `CLAUDE.md` says how Claude specifically should work (Claude-specific) - -== Reference - -ADR-002 in `standards/agentic-a2ml/docs/ADR-002-methodology-layer.adoc` diff --git a/.machine_readable/agent_instructions/coverage.a2ml b/.machine_readable/bot_directives/coverage.a2ml similarity index 100% rename from .machine_readable/agent_instructions/coverage.a2ml rename to .machine_readable/bot_directives/coverage.a2ml diff --git a/.machine_readable/agent_instructions/debt.a2ml b/.machine_readable/bot_directives/debt.a2ml similarity index 100% rename from .machine_readable/agent_instructions/debt.a2ml rename to .machine_readable/bot_directives/debt.a2ml diff --git a/.machine_readable/agent_instructions/methodology.a2ml b/.machine_readable/bot_directives/methodology.a2ml similarity index 100% rename from .machine_readable/agent_instructions/methodology.a2ml rename to .machine_readable/bot_directives/methodology.a2ml diff --git a/.machine_readable/contractiles/Adjustfile.a2ml b/.machine_readable/contractiles/Adjustfile.a2ml new file mode 100644 index 0000000..6f01e89 --- /dev/null +++ b/.machine_readable/contractiles/Adjustfile.a2ml @@ -0,0 +1,72 @@ +# SPDX-License-Identifier: MPL-2.0 +# Adjustfile — Drift-tolerance contract for rsr-template-repo +# Author: Jonathan D.A. Jewell +# +# Cumulative-drift catchment: tolerance bands + corrective actions. +# Authority: advisory (Yard) — continue-with-warnings; auto_fix where deterministic. +# Run with: adjust check +# Fix with: adjust fix (applies deterministic patches; advisory otherwise) + +@abstract: +Drift tolerances and corrective actions for rsr-template-repo. Unlike +MUST (hard gate), ADJUST tracks cumulative drift against tolerance bands +and proposes corrective actions. Advisory — it warns and trends, it does +not block. +@end + +## Template Drift + +### placeholder-drift +- description: Template placeholders should be replaced when copied +- tolerance: 0 placeholder markers in copied repos +- corrective: Search and replace all {{PLACEHOLDER}} markers +- severity: advisory +- notes: This check only applies to repos that copied from this template + +### template-version-drift +- description: Template version should match RSR spec version +- tolerance: Template version matches current RSR spec +- corrective: Update template to match latest RSR spec +- severity: advisory + +## Documentation Drift + +### readme-completeness +- description: README should document all template features +- tolerance: README covers all contractiles and directory structure +- corrective: Update README.adoc with missing sections +- severity: advisory + +### example-accuracy +- description: Examples in documentation should match actual template content +- tolerance: All code examples in docs are accurate +- corrective: Audit and fix examples in documentation +- severity: advisory + +## Structural Drift + +### contractile-sync +- description: All contractiles should have matching a2ml and ncl implementations +- tolerance: Every .a2ml has a corresponding .ncl +- corrective: Generate missing .ncl files from .a2ml +- severity: advisory + +### no-broken-symlinks +- description: No broken symbolic links in template structure +- tolerance: 0 broken symlinks +- corrective: Run symlink-check script +- severity: advisory + +## Accessibility Drift + +### adoc-not-md +- description: Template docs should prefer AsciiDoc +- tolerance: New prose docs are *.adoc +- corrective: Convert any new *.md to *.adoc +- severity: advisory + +### spdx-header-consistency +- description: All template files have correct SPDX headers +- tolerance: 0 files missing SPDX-License-Identifier +- corrective: Add SPDX headers to files that need them +- severity: advisory diff --git a/.machine_readable/contractiles/Intentfile.a2ml b/.machine_readable/contractiles/Intentfile.a2ml new file mode 100644 index 0000000..ef74f45 --- /dev/null +++ b/.machine_readable/contractiles/Intentfile.a2ml @@ -0,0 +1,99 @@ +# SPDX-License-Identifier: MPL-2.0 +# Intentfile (A2ML Canonical) — north-star contractile for rsr-template-repo +# Author: Jonathan D.A. Jewell +# +# Paired runner: intend.ncl +# Verb: intend +# +# Semantics: North-star contractile. Declares BOTH concrete committed +# next-actions AND horizon aspirations the project wishes to +# become. Two sections share one file because they answer +# the same question at different ranges: +# [[intents]] — "we WILL do this; track progress" +# status: declared → in_progress → done | +# deferred | retired +# [[wishes]] — "we WISH this were true; revisit later" +# status: declared → in_progress → achieved | +# abandoned +# grouped by horizon: near / mid / far. +# Non-gating — this is a report, not a gate. See the `must` +# contractile for hard gates. + +@abstract: +North-star contractile for rsr-template-repo. This repository is the +canonical template for Rhodium Standard Repository compliance. It provides +the scaffold that all hyperpolymath repos should copy and customize. +@end + +## Purpose + +The rsr-template-repo serves as the master template for all hyperpolymath +repositories. It contains the complete set of contractile files, machine-readable +specifications, and governance documentation that define the Rhodium Standard. + +Every new repository in the hyperpolymath estate should be initialized by +copying this template and substituting the placeholder values with +repo-specific content. + +## Anti-Purpose + +This repository is NOT: +- A general-purpose project scaffold for external use (hyperpolymath-only) +- A replacement for per-repo customization (all files must be bespoke) +- A static template that never changes (evolves with RSR spec) +- A runtime library or framework (build-time only) + +## If In Doubt + +If you are unsure whether a change is in scope, ask. Sensitive areas: +- .machine_readable/ contractile definitions +- RSR specification files +- Governance templates +- License policy documents + +## Committed Next-Actions + +### repo-initialization +- description: Provide just copy-and-substitute template for new repos +- probe: test -f scripts/init-repo.sh +- status: done +- notes: Run with source scripts/init-repo.sh + +### contractile-completeness +- description: Every RSR contractile has an a2ml and ncl implementation +- probe: ls .machine_readable/contractiles/*.a2ml | wc -l | grep -q "^6$" +- status: in_progress +- notes: Currently 6 contractile verbs: intend, must, trust, adjust, bust, dust + +### automation-scripts +- description: All repetitive tasks have just recipes +- probe: grep -c "^# " Justfile | grep -q "^[6-9][0-9]*$" +- status: in_progress + +## Wishes + +### Near Horizon + +#### cross-repo-validation +- description: Tooling to validate all repos against RSR spec +- horizon: near +- status: declared + +#### automated-substitution +- description: Script to automate repo-specific substitution in template +- horizon: near +- status: declared + +### Mid Horizon + +#### formal-verification +- description: Idris2 proofs for all critical contractile invariants +- horizon: mid +- status: declared + +### Far Horizon + +#### ecosystem-visualization +- description: Interactive graph of all hyperpolymath repos and dependencies +- horizon: far +- status: declared diff --git a/.machine_readable/contractiles/Justfile b/.machine_readable/contractiles/Justfile new file mode 100644 index 0000000..750351b --- /dev/null +++ b/.machine_readable/contractiles/Justfile @@ -0,0 +1,75 @@ +# SPDX-License-Identifier: MPL-2.0 +# Justfile for tangle + +# Default recipe — list available commands +import? "contractile.just" + +default: + @just --list + +# Self-diagnostic — checks dependencies, permissions, paths +doctor: + @echo "Running diagnostics for tangle..." + @echo "Checking required tools..." + @command -v just >/dev/null 2>&1 && echo " [OK] just" || echo " [FAIL] just not found" + @command -v git >/dev/null 2>&1 && echo " [OK] git" || echo " [FAIL] git not found" + @echo "Checking for hardcoded paths..." + @grep -rn '/var/mnt/eclipse' --include='*.rs' --include='*.ex' --include='*.res' --include='*.gleam' --include='*.sh' --include='*.toml' . 2>/dev/null | grep -v 'Justfile' | head -5 || echo " [OK] No hardcoded paths in source" + @echo "Diagnostics complete." + +# Guided tour of key features +tour: + @echo "=== tangle Tour ===" + @echo "" + @echo "1. Project structure:" + @ls -la + @echo "" + @echo "2. Available commands: just --list" + @echo "" + @echo "3. Read README.adoc or README.md for full overview" + @echo "4. Read EXPLAINME.adoc for architecture decisions" + @echo "5. Run 'just doctor' to check your setup" + @echo "" + @echo "Tour complete! Try 'just --list' to see all available commands." + +# Open feedback channel with diagnostic context +help-me: + @echo "=== tangle Help ===" + @echo "Platform: $(uname -s) $(uname -m)" + @echo "Shell: $SHELL" + @echo "" + @echo "To report an issue:" + @echo " https://github.com/hyperpolymath/tangle/issues/new" + @echo "" + @echo "Include the output of 'just doctor' in your report." + +# Run panic-attacker pre-commit scan +assail: + @command -v panic-attack >/dev/null 2>&1 && panic-attack assail . || echo "WARN: panic-attack not found — install from https://github.com/hyperpolymath/panic-attacker" + +# LLM context dump +llm-context: + @echo "Project: tangle" + @echo "License: MPL-2.0" + @test -f README.adoc && head -30 README.adoc || test -f README.md && head -30 README.md || echo "No README found" + + +# Print the current CRG grade (reads from READINESS.md '**Current Grade:** X' line) +crg-grade: + @grade=$$(grep -oP '(?<=\*\*Current Grade:\*\* )[A-FX]' READINESS.md 2>/dev/null | head -1); \ + [ -z "$$grade" ] && grade="X"; \ + echo "$$grade" + +# Generate a shields.io badge markdown for the current CRG grade +# Looks for '**Current Grade:** X' in READINESS.md; falls back to X +crg-badge: + @grade=$$(grep -oP '(?<=\*\*Current Grade:\*\* )[A-FX]' READINESS.md 2>/dev/null | head -1); \ + [ -z "$$grade" ] && grade="X"; \ + case "$$grade" in \ + A) color="brightgreen" ;; B) color="green" ;; C) color="yellow" ;; \ + D) color="orange" ;; E) color="red" ;; F) color="critical" ;; \ + *) color="lightgrey" ;; esac; \ + echo "[![CRG $$grade](https://img.shields.io/badge/CRG-$$grade-$$color?style=flat-square)](https://github.com/hyperpolymath/standards/tree/main/component-readiness-grades)" + +secret-scan-trufflehog: + @command -v trufflehog >/dev/null && trufflehog filesystem . --only-verified || true diff --git a/.machine_readable/contractiles/Mustfile.a2ml b/.machine_readable/contractiles/Mustfile.a2ml new file mode 100644 index 0000000..55f8ab4 --- /dev/null +++ b/.machine_readable/contractiles/Mustfile.a2ml @@ -0,0 +1,102 @@ +# SPDX-License-Identifier: MPL-2.0 +# Mustfile — Physical state contract for rsr-template-repo +# Author: Jonathan D.A. Jewell +# +# What MUST be true about this repository. Hard requirements. +# Run with: must check +# Fix with: must fix (where a deterministic fix exists) + +@abstract: +Physical-state invariants for rsr-template-repo. This is the canonical +RSR template repository. These are hard requirements — CI and pre-commit +hooks fail if any check fails. +@end + +## File Presence + +### license-present +- description: LICENSE file must exist +- run: test -f LICENSE +- severity: critical + +### readme-present +- description: README.adoc must exist +- run: test -f README.adoc +- severity: critical + +### security-policy +- description: SECURITY.md must exist +- run: test -f SECURITY.md +- severity: critical + +### ai-manifest +- description: 0-AI-MANIFEST.a2ml must exist +- run: test -f 0-AI-MANIFEST.a2ml +- severity: critical + +### governance-docs +- description: GOVERNANCE.adoc, MAINTAINERS.adoc, CODEOWNERS must exist +- run: test -f GOVERNANCE.adoc && test -f MAINTAINERS.adoc && test -f .github/CODEOWNERS +- severity: critical + +### machine-readable-dir +- description: .machine_readable/ directory must exist +- run: test -d .machine_readable +- severity: critical + +## Directory Structure + +### contractiles-complete +- description: All required contractile directories exist +- run: test -d .machine_readable/contractiles && test -d .machine_readable/contractiles/bust && test -d .machine_readable/contractiles/dust +- severity: critical + +### contractiles-files-present +- description: All four primary contractile files exist +- run: test -f .machine_readable/contractiles/Intentfile.a2ml && test -f .machine_readable/contractiles/Mustfile.a2ml && test -f .machine_readable/contractiles/Trustfile.a2ml && test -f .machine_readable/contractiles/Adjustfile.a2ml +- severity: critical + +### bust-dust-files-present +- description: Bustfile and Dustfile exist in their directories +- run: test -f .machine_readable/contractiles/bust/Bustfile.a2ml && test -f .machine_readable/contractiles/dust/Dustfile.a2ml +- severity: critical + +### six-directory-present +- description: 6a2 directory exists with required files +- run: test -d .machine_readable/6a2 && test -f .machine_readable/6a2/META.a2ml && test -f .machine_readable/6a2/ECOSYSTEM.a2ml && test -f .machine_readable/6a2/STATE.a2ml && test -f .machine_readable/6a2/PLAYBOOK.a2ml && test -f .machine_readable/6a2/AGENTIC.a2ml && test -f .machine_readable/6a2/NEUROSYM.a2ml +- severity: critical + +### anchors-directory +- description: anchors directory exists in 6a2 +- run: test -d .machine_readable/6a2/anchors +- severity: warning + +### self-validating-structure +- description: self-validating directory has k9-svc and examples +- run: test -d .machine_readable/self-validating && test -d .machine_readable/self-validating/k9-svc && test -d .machine_readable/self-validating/examples +- severity: warning + +## Template Integrity + +### no-placeholder-values +- description: No placeholder values remain in template files +- run: test -z "$(grep -r '{{' .machine_readable/contractiles/ 2>/dev/null)" +- severity: critical +- notes: All placeholders must be substituted when copying this template + +### template-readonly +- description: Template marker files are not modified +- run: grep -q 'RSR_TEMPLATE_DO_NOT_EDIT' .machine_readable/0.1-AI-MANIFEST.a2ml +- severity: warning + +## Git State + +### no-untracked-contractiles +- description: All contractile files are tracked in git +- run: test -z "$(git ls-files -o --exclude-standard .machine_readable/contractiles/ 2>/dev/null)" +- severity: critical + +### signed-commits +- description: All commits must be signed +- run: git verify-commit HEAD +- severity: critical diff --git a/.machine_readable/contractiles/Trustfile.a2ml b/.machine_readable/contractiles/Trustfile.a2ml new file mode 100644 index 0000000..e2028b5 --- /dev/null +++ b/.machine_readable/contractiles/Trustfile.a2ml @@ -0,0 +1,88 @@ +# SPDX-License-Identifier: MPL-2.0 +# Trustfile — Trust boundaries and integrity invariants for rsr-template-repo +# Author: Jonathan D.A. Jewell +# +# Defines what LLM/SLM agents are trusted to do without asking, and +# integrity invariants that verify the repo has not been tampered with. + +@abstract: +Trust boundaries and integrity checks for rsr-template-repo. This file +combines the trust-level definitions from the original TRUST.contractile +with the integrity invariants from the old Trustfile.a2ml. It defines +what AI agents may do autonomously and what requires human approval, +plus checks that verify repository integrity. +@end + +## Trust Levels + +The rsr-template-repo operates at trust level: maximal + +Trust levels: +- maximal: Agent may read, build, test, lint, format, heal freely. + Only destructive/external actions require approval. +- standard: Agent may read and build. Test/lint need approval. +- restricted: Agent may read only. All modifications need approval. +- minimal: Agent may read specific files only. Everything else blocked. + +Current trust level: maximal + +## Integrity Invariants + +### Secrets + +#### no-secrets-committed +- description: No credential files in repo +- run: test ! -f .env && test ! -f credentials.json && test ! -f .env.local && test ! -f .env.production +- severity: critical + +#### no-private-keys +- description: No private key files committed +- run: "! find . -name '*.pem' -o -name '*.key' -o -name 'id_rsa' -o -name 'id_ed25519' 2>/dev/null | grep -v node_modules | head -1 | grep -q ." +- severity: critical + +#### no-tokens-in-source +- description: No hardcoded API tokens in source +- run: "! grep -rE '(api[_-]?key|secret|token|password)\s*[:=]\s*[\"'\\''][A-Za-z0-9]{16,}' --include='*.js' --include='*.ts' --include='*.res' --include='*.py' . 2>/dev/null | grep -v node_modules | head -1 | grep -q ." +- severity: critical + +## Provenance + +#### author-correct +- description: Git author matches expected identity +- run: "git log -1 --format='%ae' | grep -qE '(hyperpolymath|j\\.d\\.a\\.jewell)'" +- severity: warning + +#### license-content +- description: LICENSE contains expected identifier +- run: grep -q 'PMPL\|MPL\|MIT\|Apache\|LGPL' LICENSE +- severity: warning + +## Template-Specific Trust + +### template-files-readonly +- description: Template scaffold files should not be modified except by maintainer +- run: test -z "$(git status --short .machine_readable/ 2>/dev/null | grep -v '^??' || true)" +- severity: advisory +- notes: Changes to template files require careful review + +### trust-deny-areas +- description: Sensitive areas from INTENT.contractile require explicit approval +- run: echo "Check .machine_readable/ contractiles and governance docs" +- severity: advisory +- areas: + - .machine_readable/ + - GOVERNANCE.adoc + - MAINTAINERS.adoc + - .github/CODEOWNERS + +## Container Security + +#### container-images-pinned +- description: Containerfile uses pinned base images +- run: test ! -f Containerfile || grep -q 'cgr.dev\|@sha256:' Containerfile +- severity: warning + +#### no-dockerfile +- description: No Dockerfile (use Containerfile) +- run: test ! -f Dockerfile +- severity: warning diff --git a/.machine_readable/contractiles/bust/Bustfile.a2ml b/.machine_readable/contractiles/bust/Bustfile.a2ml new file mode 100644 index 0000000..97d62cd --- /dev/null +++ b/.machine_readable/contractiles/bust/Bustfile.a2ml @@ -0,0 +1,52 @@ +# SPDX-License-Identifier: MPL-2.0 +# Bustfile — failure mode contractile for tangle +# Author: Jonathan D.A. Jewell +# +# Paired runner: bust.ncl +# Verb: bust +# Semantics: Every declared failure mode must have a working recovery path +# that has been exercised. Status moves: +# declared → drilled (probe run) → verified (recovery confirmed) +# or → failing (recovery broken) +# +# CLI: +# contractile bust check → list failure modes + recovery status +# contractile bust drill → inject failures, verify recovery paths +# +# This repository: tangle is the canonical template for RSR compliance. +# Failure modes here relate to template distribution and substitution. + +@abstract: +Bustfile for tangle. Lists failure modes specific to the template +repository itself, particularly around template distribution, substitution, +and synchronization across the hyperpolymath estate. +@end + +## Failure Modes + +### template-substitution-failure +- class: template_processing +- description: Template substitution fails when initializing a new repo from this template +- injection_probe: "cp -r tangle test-repo && cd test-repo && sed -i 's/tangle/TEST/g' .machine_readable/contractiles/Intentfile.a2ml && grep -q 'TEST' .machine_readable/contractiles/Intentfile.a2ml" +- recovery_probe: "git -C test-repo diff --quiet .machine_readable/contractiles/Intentfile.a2ml" +- expected_recovery_time_seconds: 10 +- status: declared +- notes: Verify that substitution scripts handle all placeholder replacements correctly + +### sync-drift-between-repos +- class: synchronization +- description: Drift occurs between tangle and other repos after template updates +- injection_probe: "echo 'template_updated' > /tmp/test_drift_marker" +- recovery_probe: "test -f /tmp/test_drift_marker && rm /tmp/test_drift_marker" +- expected_recovery_time_seconds: 60 +- status: declared +- notes: The estate-wide sync scripts (see scripts/) should prevent this; verify with scripts/verify-sync.sh + +### contractile-parse-error +- class: contractile_format +- description: A contractile file fails to parse due to syntax errors +- injection_probe: "echo 'invalid syntax' >> tangle/.machine_readable/contractiles/Intentfile.a2ml" +- recovery_probe: "git checkout tangle/.machine_readable/contractiles/Intentfile.a2ml" +- expected_recovery_time_seconds: 5 +- status: declared +- notes: All .a2ml files should be valid A2ML; use a2ml-validate runner diff --git a/.machine_readable/contractiles/dust/Dustfile.a2ml b/.machine_readable/contractiles/dust/Dustfile.a2ml new file mode 100644 index 0000000..2dad215 --- /dev/null +++ b/.machine_readable/contractiles/dust/Dustfile.a2ml @@ -0,0 +1,62 @@ +# SPDX-License-Identifier: MPL-2.0 +# Dustfile — Cleanup and hygiene contract for tangle +# Author: Jonathan D.A. Jewell +# +# Paired runner: dust.ncl +# Verb: dust +# Semantics: What should be cleaned up. Housekeeping, not blockers. +# +# This repository: tangle is the canonical template. +# Cleanup items here ensure the template itself remains pristine. + +@abstract: +Cleanup and hygiene items for tangle. These are maintenance tasks +that ensure the template repository remains clean and ready for distribution +to new repositories. +@end + +## Stale Files + +### no-template-artifacts +- description: No generated files from template testing in root +- run: test -z "$(ls template-test-* 2>/dev/null)" +- severity: info +- notes: Template testing should use /tmp or dedicated test directories + +### no-example-placeholders +- description: No example placeholder files (EXAMPLE-, SAMPLE-) in contractiles/ +- run: test -z "$(find .machine_readable/contractiles/ -name 'EXAMPLE-*' -o -name 'SAMPLE-*' 2>/dev/null)" +- severity: warning +- notes: All placeholders should be replaced with actual content or removed + +### no-old-contractile-formats +- description: No old .contractile or .hs files remaining +- run: test -z "$(find .machine_readable/contractiles/ \( -name '*.contractile' -o -name '*.hs' \) 2>/dev/null)" +- severity: warning +- notes: All contractiles should be .a2ml format + +## Format Duplicates + +### no-duplicate-justfile +- description: Only one Justfile (hardlinked from root to .machine_readable/contractiles/) +- run: test $(stat -c '%i' Justfile) = $(stat -c '%i' .machine_readable/contractiles/Justfile 2>/dev/null) +- severity: warning +- notes: Justfile should be hardlinked, not copied + +### no-duplicate-readme-format +- description: Only one README format in contractiles/ (.adoc canonical) +- run: test ! -f .machine_readable/contractiles/README.md +- severity: info + +## Template Hygiene + +### no-stale-template-references +- description: No references to tangle in generic template files +- run: test -z "$(grep -r 'tangle' machine-readable-design/ 2>/dev/null)" +- severity: warning +- notes: Generic templates should use {{PROJECT_NAME}} or similar placeholders + +### version-sync-checked +- description: Version in canonical-directory-structure matches .machine_readable/contractiles +- verification: compare version identifiers in both locations +- severity: info diff --git a/.machine_readable/svc/k9/README.adoc b/.machine_readable/self-validating/README.adoc similarity index 98% rename from .machine_readable/svc/k9/README.adoc rename to .machine_readable/self-validating/README.adoc index 9c3099f..ce1825f 100644 --- a/.machine_readable/svc/k9/README.adoc +++ b/.machine_readable/self-validating/README.adoc @@ -1,4 +1,5 @@ // SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = K9 Contractiles :toc: left :icons: font diff --git a/.machine_readable/svc/k9/examples/ci-config.k9.ncl b/.machine_readable/self-validating/examples/ci-config.k9.ncl similarity index 100% rename from .machine_readable/svc/k9/examples/ci-config.k9.ncl rename to .machine_readable/self-validating/examples/ci-config.k9.ncl diff --git a/.machine_readable/svc/k9/examples/project-metadata.k9.ncl b/.machine_readable/self-validating/examples/project-metadata.k9.ncl similarity index 100% rename from .machine_readable/svc/k9/examples/project-metadata.k9.ncl rename to .machine_readable/self-validating/examples/project-metadata.k9.ncl diff --git a/.machine_readable/svc/k9/examples/setup-repo.k9.ncl b/.machine_readable/self-validating/examples/setup-repo.k9.ncl similarity index 100% rename from .machine_readable/svc/k9/examples/setup-repo.k9.ncl rename to .machine_readable/self-validating/examples/setup-repo.k9.ncl diff --git a/.machine_readable/svc/k9/template-hunt.k9.ncl b/.machine_readable/self-validating/template-hunt.k9.ncl similarity index 100% rename from .machine_readable/svc/k9/template-hunt.k9.ncl rename to .machine_readable/self-validating/template-hunt.k9.ncl diff --git a/.machine_readable/svc/k9/template-kennel.k9.ncl b/.machine_readable/self-validating/template-kennel.k9.ncl similarity index 100% rename from .machine_readable/svc/k9/template-kennel.k9.ncl rename to .machine_readable/self-validating/template-kennel.k9.ncl diff --git a/.machine_readable/svc/k9/template-yard.k9.ncl b/.machine_readable/self-validating/template-yard.k9.ncl similarity index 100% rename from .machine_readable/svc/k9/template-yard.k9.ncl rename to .machine_readable/self-validating/template-yard.k9.ncl diff --git a/.machine_readable/svc/README.adoc b/.machine_readable/svc/README.adoc index 99a044e..de136d7 100644 --- a/.machine_readable/svc/README.adoc +++ b/.machine_readable/svc/README.adoc @@ -1,3 +1,5 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = `.machine_readable/svc/` — Service components for tangle :toc: diff --git a/ABI-FFI-README.md b/ABI-FFI-README.md index ff85af1..0176d34 100644 --- a/ABI-FFI-README.md +++ b/ABI-FFI-README.md @@ -1,3 +1,7 @@ + # TANGLE ABI/FFI Documentation ## Overview diff --git a/CHANGELOG.md b/CHANGELOG.md index 786e939..2627d0a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,4 +1,7 @@ - + # Changelog — Tangle diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 31604d2..5c80c98 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -1,3 +1,7 @@ + # Code of Conduct # Clone the repository git clone https://github.com/hyperpolymath/nextgen-languages.git cd nextgen-languages diff --git a/EXPLAINME.adoc b/EXPLAINME.adoc index b2cc7a2..70bec22 100644 --- a/EXPLAINME.adoc +++ b/EXPLAINME.adoc @@ -1,7 +1,8 @@ // SPDX-License-Identifier: MPL-2.0 -// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) - +// Copyright (c) Jonathan D.A. Jewell = EXPLAINME: Tangle +image:https://img.shields.io/badge/License-MPL_2.0-blue.svg[License: MPL-2.0,link="https://opensource.org/licenses/MPL-2.0"] + :toc: preamble :icons: font @@ -69,3 +70,10 @@ not via a traditional proof. | `docs/spec/FORMAL-SEMANTICS.md` -- denotational model for tangle programs; isotopy-class equivalence; Reidemeister-move reduction rules | KnotTheory.jl (Julia knot invariant library), KRLAdapter.jl (KRL bridging), typed-wasm (structured braid-type analogues), standards (spec-first documentation pattern) |=== + + +== License + +This project is licensed under the Mozilla Public License, v. 2.0. See the `LICENSE` file for details. + +SPDX-License-Identifier: MPL-2.0 diff --git a/GOVERNANCE.adoc b/GOVERNANCE.adoc new file mode 100644 index 0000000..8bbf167 --- /dev/null +++ b/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/Justfile b/Justfile index 4c8c849..fbaad1a 100644 --- a/Justfile +++ b/Justfile @@ -1,4 +1,5 @@ # SPDX-License-Identifier: MPL-2.0 +// Owner: Jonathan D.A. Jewell # Justfile for tangle # Default recipe — list available commands @@ -70,3 +71,6 @@ crg-badge: D) color="orange" ;; E) color="red" ;; F) color="critical" ;; \ *) color="lightgrey" ;; esac; \ echo "[![CRG $$grade](https://img.shields.io/badge/CRG-$$grade-$$color?style=flat-square)](https://github.com/hyperpolymath/standards/tree/main/component-readiness-grades)" + +secret-scan-trufflehog: + @command -v trufflehog >/dev/null && trufflehog filesystem . --only-verified || true diff --git a/LICENSE b/LICENSE index 4a7f1aa..d0a1fa1 100644 --- a/LICENSE +++ b/LICENSE @@ -1,38 +1,3 @@ -SPDX-License-Identifier: MPL-2.0 -SPDX-FileCopyrightText: 2024-2026 Jonathan D.A. Jewell (hyperpolymath) - ------------------------------------------------------------------------- -PREFERRED LICENCE: Palimpsest License (MPL-2.0) ------------------------------------------------------------------------- - -This work is governed by the Palimpsest License (MPL-2.0) as -its primary intended licence. MPL-2.0 extends the Mozilla -Public License 2.0 (MPL-2.0) with additional provisions for ethical use, -post-quantum cryptographic provenance, and emotional lineage protection. -The canonical PMPL text and stewardship information are maintained at: - https://github.com/hyperpolymath/palimpsest-license - ------------------------------------------------------------------------- -FALLBACK LICENCE: Mozilla Public License 2.0 (MPL-2.0) ------------------------------------------------------------------------- - -Because MPL-2.0 is not yet recognised by the Open Source -Initiative (OSI) or equivalent bodies, this work also carries MPL-2.0 -as its legally-recognised fallback licence. - -In any jurisdiction, platform, or context where MPL-2.0 is -not accepted as a valid licence, or where an OSI-approved licence is -required, this work is instead governed by the Mozilla Public License, -Version 2.0. - -MPL-2.0 was chosen as the fallback because MPL-2.0 is -explicitly based on and extends MPL-2.0; it is therefore the closest -recognised equivalent to the intended licence. - -The complete MPL-2.0 text follows below. - ------------------------------------------------------------------------- - Mozilla Public License Version 2.0 ================================== @@ -109,17 +74,17 @@ Mozilla Public License Version 2.0 means the form of the work preferred for making modifications. 1.14. "You" (or "Your") - means an individual or a legal entity exercising rights under - this License. For legal entities, "You" includes any entity that - controls, is controlled by, or is under common control with You. - For the purposes of this definition, "control" means (a) the power, - direct or indirect, to cause the direction or management of such - entity, whether by contract or otherwise, or (b) ownership of more - than fifty percent (50%) of the outstanding shares or beneficial + means an individual or a legal entity exercising rights under this + License. For legal entities, "You" includes any entity that + controls, is controlled by, or is under common control with You. For + purposes of this definition, "control" means (a) the power, direct + or indirect, to cause the direction or management of such entity, + whether by contract or otherwise, or (b) ownership of more than + fifty percent (50%) of the outstanding shares or beneficial ownership of such entity. 2. License Grants and Conditions ---------------------------------- +-------------------------------- 2.1. Grants @@ -144,11 +109,11 @@ distributes such Contribution. 2.3. Limitations on Grant Scope -The licenses granted in this Section 2 are the only rights granted -under this License. No additional rights or licenses will be implied -from the distribution or licensing of Covered Software under this -License. Notwithstanding Section 2.1(b) above, no patent license is -granted by a Contributor: +The licenses granted in this Section 2 are the only rights granted under +this License. No additional rights or licenses will be implied from the +distribution or licensing of Covered Software under this License. +Notwithstanding Section 2.1(b) above, no patent license is granted by a +Contributor: (a) for any code that a Contributor has removed from Covered Software; or @@ -158,19 +123,19 @@ granted by a Contributor: Contributions with other software (except as part of its Contributor Version); or -(c) under Patent Claims infringed by Covered Software in the absence - of its Contributions. +(c) under Patent Claims infringed by Covered Software in the absence of + its Contributions. -This License does not grant any rights in the trademarks, service -marks, or logos of any Contributor (except as may be necessary to -comply with the notice requirements in Section 3.4). +This License does not grant any rights in the trademarks, service marks, +or logos of any Contributor (except as may be necessary to comply with +the notice requirements in Section 3.4). 2.4. Subsequent Licenses No Contributor makes additional grants as a result of Your choice to distribute the Covered Software under a subsequent version of this -License (see Section 10.2) or under the terms of a Secondary License -(if permitted under the terms of Section 3.3). +License (see Section 10.2) or under the terms of a Secondary License (if +permitted under the terms of Section 3.3). 2.5. Representation @@ -186,11 +151,11 @@ equivalents. 2.7. Conditions -Sections 3.1, 3.2, 3.3, and 3.4 are conditions of the licenses -granted in Section 2.1. +Sections 3.1, 3.2, 3.3, and 3.4 are conditions of the licenses granted +in Section 2.1. 3. Responsibilities --------------------- +------------------- 3.1. Distribution of Source Form @@ -207,10 +172,10 @@ Form. If You distribute Covered Software in Executable Form then: (a) such Covered Software must also be made available in Source Code - Form, as described in Section 3.1, and You must inform recipients - of the Executable Form how they can obtain a copy of such Source - Code Form by reasonable means in a timely manner, at a charge no - more than the cost of distribution to the recipient; and + Form, as described in Section 3.1, and You must inform recipients of + the Executable Form how they can obtain a copy of such Source Code + Form by reasonable means in a timely manner, at a charge no more + than the cost of distribution to the recipient; and (b) You may distribute such Executable Form under the terms of this License, or sublicense it under different terms, provided that the @@ -222,8 +187,8 @@ If You distribute Covered Software in Executable Form then: You may create and distribute a Larger Work under terms of Your choice, provided that You also comply with the requirements of this License for the Covered Software. If the Larger Work is a combination of Covered -Software with a work governed by one or more Secondary Licenses, and -the Covered Software is not Incompatible With Secondary Licenses, this +Software with a work governed by one or more Secondary Licenses, and the +Covered Software is not Incompatible With Secondary Licenses, this License permits You to additionally distribute such Covered Software under the terms of such Secondary License(s), so that the recipient of the Larger Work may, at their option, further distribute the Covered @@ -241,28 +206,28 @@ the extent required to remedy known factual inaccuracies. 3.5. Application of Additional Terms You may choose to offer, and to charge a fee for, warranty, support, -indemnity or liability obligations to one or more recipients of -Covered Software. However, You may do so only on Your own behalf, and -not on behalf of any Contributor. You must make it absolutely clear -that any such warranty, support, indemnity, or liability obligation is -offered by You alone, and You hereby agree to indemnify every -Contributor for any liability incurred by such Contributor as a result -of warranty, support, indemnity or liability terms You offer. You may -include additional disclaimers of warranty and limitations of liability -specific to any jurisdiction. +indemnity or liability obligations to one or more recipients of Covered +Software. However, You may do so only on Your own behalf, and not on +behalf of any Contributor. You must make it absolutely clear that any +such warranty, support, indemnity, or liability obligation is offered by +You alone, and You hereby agree to indemnify every Contributor for any +liability incurred by such Contributor as a result of warranty, support, +indemnity or liability terms You offer. You may include additional +disclaimers of warranty and limitations of liability specific to any +jurisdiction. 4. Inability to Comply Due to Statute or Regulation ------------------------------------------------------ +--------------------------------------------------- If it is impossible for You to comply with any of the terms of this License with respect to some or all of the Covered Software due to statute, judicial order, or regulation then You must: (a) comply with the terms of this License to the maximum extent possible; and (b) -describe the limitations and the code they affect. Such description -must be placed in a text file included with all distributions of the -Covered Software under this License. Except to the extent prohibited -by statute or regulation, such description must be sufficiently -detailed for a recipient of ordinary skill to be able to understand it. +describe the limitations and the code they affect. Such description must +be placed in a text file included with all distributions of the Covered +Software under this License. Except to the extent prohibited by statute +or regulation, such description must be sufficiently detailed for a +recipient of ordinary skill to be able to understand it. 5. Termination -------------- @@ -271,27 +236,27 @@ detailed for a recipient of ordinary skill to be able to understand it. if You fail to comply with any of its terms. However, if You become compliant, then the rights granted under this License from a particular Contributor are reinstated (a) provisionally, unless and until such -Contributor explicitly and finally terminates Your grants, and (b) on -an ongoing basis, if such Contributor fails to notify You of the +Contributor explicitly and finally terminates Your grants, and (b) on an +ongoing basis, if such Contributor fails to notify You of the non-compliance by some reasonable means prior to 60 days after You have come back into compliance. Moreover, Your grants from a particular Contributor are reinstated on an ongoing basis if such Contributor -notifies You of the non-compliance by some reasonable means, this is -the first time You have received notice of non-compliance with this -License from such Contributor, and You become compliant prior to 30 -days after Your receipt of the notice. +notifies You of the non-compliance by some reasonable means, this is the +first time You have received notice of non-compliance with this License +from such Contributor, and You become compliant prior to 30 days after +Your receipt of the notice. -5.2. If You initiate litigation against any entity by asserting a -patent infringement claim (excluding declaratory judgment actions, +5.2. If You initiate litigation against any entity by asserting a patent +infringement claim (excluding declaratory judgment actions, counter-claims, and cross-claims) alleging that a Contributor Version directly or indirectly infringes any patent, then the rights granted to You by any and all Contributors for the Covered Software under Section 2.1 of this License shall terminate. 5.3. In the event of termination under Sections 5.1 or 5.2 above, all -end user license agreements (excluding distributors and resellers) -which have been validly granted by You or Your distributors under this -License prior to termination shall survive termination. +end user license agreements (excluding distributors and resellers) which +have been validly granted by You or Your distributors under this License +prior to termination shall survive termination. ************************************************************************ * * @@ -346,7 +311,7 @@ Nothing in this Section shall prevent a party's ability to bring cross-claims or counter-claims. 9. Miscellaneous ------------------ +---------------- This License represents the complete agreement concerning the subject matter hereof. If any provision of this License is held to be @@ -356,14 +321,14 @@ that the language of a contract shall be construed against the drafter shall not be used to construe this License against a Contributor. 10. Versions of the License ----------------------------- +--------------------------- 10.1. New Versions -Mozilla Foundation is the license steward. Except as provided in -Section 10.3, no one other than the license steward has the right to -modify or publish new versions of this License. Each version will be -given a distinguishing version number. +Mozilla Foundation is the license steward. Except as provided in Section +10.3, no one other than the license steward has the right to modify or +publish new versions of this License. Each version will be given a +distinguishing version number. 10.2. Effect of New Versions @@ -392,17 +357,17 @@ Exhibit A - Source Code Form License Notice This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this - file, You can obtain one at http://mozilla.org/MPL/2.0/. + file, You can obtain one at https://mozilla.org/MPL/2.0/. If it is not possible or desirable to put the notice in a particular file, then You may include the notice in a location (such as a LICENSE -file in a relevant directory) where a recipient would be likely to -look for such a notice. +file in a relevant directory) where a recipient would be likely to look +for such a notice. You may add additional accurate notices of copyright ownership. Exhibit B - "Incompatible With Secondary Licenses" Notice ----------------------------------------------------------- +--------------------------------------------------------- This Source Code Form is "Incompatible With Secondary Licenses", as defined by the Mozilla Public License, v. 2.0. diff --git a/MAINTAINERS.adoc b/MAINTAINERS.adoc index a1c6544..becaa3e 100644 --- a/MAINTAINERS.adoc +++ b/MAINTAINERS.adoc @@ -1,4 +1,5 @@ // SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Maintainers :toc: preamble diff --git a/QUICKSTART-DEV.adoc b/QUICKSTART-DEV.adoc index 747abfd..4351cb3 100644 --- a/QUICKSTART-DEV.adoc +++ b/QUICKSTART-DEV.adoc @@ -1,4 +1,5 @@ // SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell // Template: QUICKSTART-DEV.adoc — clone → build → test → PR // Replace tangle, {{BUILD_CMD}}, {{TEST_CMD}}, {{LANG_STACK}} with actuals = tangle — Quick Start for Developers diff --git a/QUICKSTART-MAINTAINER.adoc b/QUICKSTART-MAINTAINER.adoc index 28ae274..11ef02f 100644 --- a/QUICKSTART-MAINTAINER.adoc +++ b/QUICKSTART-MAINTAINER.adoc @@ -1,4 +1,5 @@ // SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell // Template: QUICKSTART-MAINTAINER.adoc — packaging, deploying, and maintaining // Replace tangle, {{PACKAGE_NAME}}, {{DEPS}} with actuals = tangle — Quick Start for Platform Maintainers diff --git a/QUICKSTART-USER.adoc b/QUICKSTART-USER.adoc index 074d5d4..8513386 100644 --- a/QUICKSTART-USER.adoc +++ b/QUICKSTART-USER.adoc @@ -1,4 +1,5 @@ // SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell // Template: QUICKSTART-USER.adoc — 5-minute path to working software // Replace tangle, Tangle — See README.adoc for details., just run, Tangle started successfully. with actuals = tangle — Quick Start for Users diff --git a/READINESS.md b/READINESS.md index 3518ede..9bbf17b 100644 --- a/READINESS.md +++ b/READINESS.md @@ -1,4 +1,7 @@ - + # Component Readiness — Tangle (language) diff --git a/README-jtv.adoc b/README-jtv.adoc index 7c8504f..9a554f5 100644 --- a/README-jtv.adoc +++ b/README-jtv.adoc @@ -1,5 +1,8 @@ // SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = TANGLE-JTV: Julia-the-Viper Injection Blocks +image:https://img.shields.io/badge/OpenSSF-Best_Practices-green?logo=openssourcesecurity[OpenSSF Best Practices,link="https://www.bestpractices.dev/en/projects/new?repo_url=https://github.com/hyperpolymath/tangle"] + :toc: :source-highlighter: highlight.js :sectnums: diff --git a/README.adoc b/README.adoc index 62a8c9a..2829796 100644 --- a/README.adoc +++ b/README.adoc @@ -1,10 +1,11 @@ // SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell // SPDX-FileCopyrightText: 2025-2026 Jonathan D.A. Jewell = Tangle / KRL — Topological Programming Language image:https://img.shields.io/badge/OpenSSF-Best_Practices-green?logo=opensourcesecurity[OpenSSF Best Practices,link="https://www.bestpractices.dev/en/projects/new?repo_url=https://github.com/hyperpolymath/tangle"] -image:https://img.shields.io/badge/License-PMPL--1.0-blue.svg[License: PMPL-1.0,link="https://github.com/hyperpolymath/palimpsest-license"] +image:https://img.shields.io/badge/License-MPL_2.0-blue.svg[License: MPL-2.0,link="https://opensource.org/licenses/MPL-2.0"] image:https://api.thegreenwebfoundation.org/greencheckimage/github.com[Green Web,link="https://www.thegreenwebfoundation.org/green-web-check/?url=github.com"] A research language exploring *computation as topology*, where programs are structured objects and equivalence is defined by transformation. @@ -201,3 +202,10 @@ Recommended entry points: Tangle/KRL is best understood as: > a research language that treats programs as structured objects, with meaning defined by transformation and equivalence, supported by a partially mechanised formal core and an evolving implementation. + + +== License + +This project is licensed under the Mozilla Public License, v. 2.0. See the `LICENSE` file for details. + +SPDX-License-Identifier: MPL-2.0 diff --git a/ROADMAP.adoc b/ROADMAP.adoc index ecd7b9e..065585b 100644 --- a/ROADMAP.adoc +++ b/ROADMAP.adoc @@ -1,4 +1,5 @@ // SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = TANGLE & TANGLE-JTV Roadmap == Current Status diff --git a/RSR_OUTLINE.adoc b/RSR_OUTLINE.adoc index 3ce20ed..6c2a084 100644 --- a/RSR_OUTLINE.adoc +++ b/RSR_OUTLINE.adoc @@ -1,3 +1,5 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = RSR Template Repository image:[Palimpsest-MPL-1.0,link="https://github.com/hyperpolymath/palimpsest-license"] image:[Palimpsest,link="https://github.com/hyperpolymath/palimpsest-license"] diff --git a/SECURITY.md b/SECURITY.md index bede85e..92688d0 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,3 +1,7 @@ + # Security Policy # TEST-NEEDS: tangle ## CRG Grade: C — ACHIEVED 2026-04-04 diff --git a/TOPOLOGY.md b/TOPOLOGY.md index 5a93e0c..e39cc4f 100644 --- a/TOPOLOGY.md +++ b/TOPOLOGY.md @@ -1,4 +1,7 @@ - + # TOPOLOGY.md — tangle diff --git a/bench/bench_lexer.rs b/bench/bench_lexer.rs index 7865519..0cca2fa 100644 --- a/bench/bench_lexer.rs +++ b/bench/bench_lexer.rs @@ -1,4 +1,5 @@ // SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell //! Lexer performance benchmark for TANGLE (Rust frontend) //! //! Measures: diff --git a/bench/bench_parser_rust.rs b/bench/bench_parser_rust.rs index 143367a..bb37e19 100644 --- a/bench/bench_parser_rust.rs +++ b/bench/bench_parser_rust.rs @@ -1,4 +1,5 @@ // SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell // bench_parser_rust.rs -- Parser benchmark harness for Tangle (Rust) // // Generates a large synthetic Tangle program and measures diff --git a/bench/bench_sigma_ops.rs b/bench/bench_sigma_ops.rs index 06a5608..612e993 100644 --- a/bench/bench_sigma_ops.rs +++ b/bench/bench_sigma_ops.rs @@ -1,4 +1,5 @@ // SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell // (MPL-2.0 is automatic legal fallback until PMPL is formally recognised) // // bench_sigma_ops.rs — Tangle parser + IR ops benchmark with Six Sigma diff --git a/compiler/tangle-lsp/src/main.rs b/compiler/tangle-lsp/src/main.rs index c7fc0a6..afe731e 100644 --- a/compiler/tangle-lsp/src/main.rs +++ b/compiler/tangle-lsp/src/main.rs @@ -1,4 +1,5 @@ // SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell //! tangle-lsp — Language Server Protocol server for the Tangle language. //! //! Provides diagnostics, hover, completion, go-to-definition, and document diff --git a/compiler/tangle-wasm/src/lib.rs b/compiler/tangle-wasm/src/lib.rs index 9202608..600833f 100644 --- a/compiler/tangle-wasm/src/lib.rs +++ b/compiler/tangle-wasm/src/lib.rs @@ -1,4 +1,5 @@ // SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell // SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell //! WebAssembly backend for Tangle. diff --git a/contractiles/README.adoc b/contractiles/README.adoc index e3ddddd..846593d 100644 --- a/contractiles/README.adoc +++ b/contractiles/README.adoc @@ -1,4 +1,5 @@ // SPDX-License-Identifier: MPL-2.0 +// Owner: Jonathan D.A. Jewell = Tangle Contractiles :toc: :sectnums: diff --git a/contractiles/dust/Dustfile b/contractiles/dust/Dustfile deleted file mode 100644 index 6f93c6a..0000000 --- a/contractiles/dust/Dustfile +++ /dev/null @@ -1,29 +0,0 @@ -# SPDX-License-Identifier: PLMP-1.0-or-later -# Dustfile template - recovery and rollback semantics - -version: 1 - -recovery: - logs: - - name: decision-log - path: logs/decisions.json - reversible: true - handler: "log-replay --reverse logs/decisions.json" - - policy: - - name: policy-rollback - path: policy/policy.ncl - rollback: "git checkout HEAD~1 -- policy/policy.ncl" - notes: "Rollback policy to the previous known-good revision." - - gateway: - - name: bad-deployment - event: "deploy.failure" - undo: "kubectl rollout undo deployment/gateway" - notes: "Undo a failed deployment while preserving audit logs." - - dust-events: - - name: decision-log-to-dust - source: logs/decisions.json - transform: "dustify --input logs/decisions.json --output logs/dust-events.json" - notes: "Map gateway decision logs into reversible dust events." diff --git a/contractiles/intend/Intentfile.a2ml b/contractiles/intend/Intentfile.a2ml deleted file mode 100644 index 4bdffc3..0000000 --- a/contractiles/intend/Intentfile.a2ml +++ /dev/null @@ -1,22 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Intentfile (A2ML Canonical) -# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) - -@abstract: -Declared intent and purpose for Tangle. -@end - -## Purpose - -Tangle — // SPDX-License-Identifier: MPL-2.0 - -## Anti-Purpose - -This project is NOT: -- A fork or wrapper around another tool -- A monorepo (unless explicitly structured as one) - -## If In Doubt - -If you are unsure whether a change is in scope, ask. -Sensitive areas: ABI definitions, license headers, CI workflows. diff --git a/contractiles/must/Mustfile b/contractiles/must/Mustfile deleted file mode 100644 index dc2c6b6..0000000 --- a/contractiles/must/Mustfile +++ /dev/null @@ -1,35 +0,0 @@ -# SPDX-License-Identifier: PLMP-1.0-or-later -# Mustfile - declarative state contract (template) -# See: https://github.com/hyperpolymath/mustfile - -version: 1 - -metadata: - name: project-state-contract - spec: v0.0.1 - description: "Invariant checks for config, policy, gateway, logs, and schema." - -parameters: - gateway_port: "8080" - schema_version: "v0.0.1" - -checks: - - name: config-valid - description: "config/service.yaml must be valid." - run: "yq -e '.' config/service.yaml >/dev/null" - - - name: policy-compiles - description: "policy/policy.ncl must compile." - run: "nickel check policy/policy.ncl" - - - name: gateway-exposes-port - description: "Service must expose the configured port." - run: "bash -uc 'ss -lnt | rg \":${GATEWAY_PORT:-8080}\"'" - - - name: logs-are-json - description: "Logs must be JSON." - run: "bash -uc 'rg --files -g \"*.json\" logs | xargs -r jq -e .'" - - - name: schema-version-matches - description: "Schema must match version spec." - run: "bash -uc 'rg -n \"${SCHEMA_VERSION:-v0.0.1}\" schema'" diff --git a/contractiles/trust/Trustfile.a2ml b/contractiles/trust/Trustfile.a2ml deleted file mode 100644 index 723b615..0000000 --- a/contractiles/trust/Trustfile.a2ml +++ /dev/null @@ -1,25 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Trustfile (A2ML Canonical) -# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) - -@abstract: -Trust and provenance verification for Tangle. -Maximal trust by default — LLM may read, build, test, lint, format. -@end - -@trust-level: maximal -@trust-boundary: repo -@trust-actions: [read, build, test, lint, format] -@trust-deny: [delete-branch, force-push, modify-ci-secrets, publish] - -## Integrity - -### license-content -- description: LICENSE contains expected SPDX identifier -- run: grep -q 'SPDX\|License\|MIT\|Apache\|PMPL\|MPL' LICENSE -- severity: critical - -### no-secrets-committed -- description: No .env or credential files in repo -- run: test ! -f .env && test ! -f credentials.json && test ! -f .env.local -- severity: critical diff --git a/dialects/README.md b/dialects/README.md index d5dd95b..ba43913 100644 --- a/dialects/README.md +++ b/dialects/README.md @@ -1,3 +1,7 @@ + # Tangle Dialects — hosted DSL scaffolds Tangle is a Turing-complete topological programming language. It is NOT diff --git a/dialects/braid-calculus/README.md b/dialects/braid-calculus/README.md index 7b74d3b..1c6a7b5 100644 --- a/dialects/braid-calculus/README.md +++ b/dialects/braid-calculus/README.md @@ -1,3 +1,7 @@ + # Braid Calculus — Tangle DSL Sketch **Status:** sketch. Grammar drafted; no parser or implementation yet. diff --git a/dialects/quantum-circuit/README.md b/dialects/quantum-circuit/README.md index f854b53..f14dae9 100644 --- a/dialects/quantum-circuit/README.md +++ b/dialects/quantum-circuit/README.md @@ -1,3 +1,7 @@ + # Quantum Circuit Calculus — Tangle DSL Sketch **Status:** sketch. Grammar drafted; no parser or implementation yet. diff --git a/dialects/skein-algebra/README.md b/dialects/skein-algebra/README.md index 0f0aafa..a80731a 100644 --- a/dialects/skein-algebra/README.md +++ b/dialects/skein-algebra/README.md @@ -1,4 +1,7 @@ - + # Skein Algebra — Tangle DSL Sketch diff --git a/dialects/string-diagram/README.md b/dialects/string-diagram/README.md index 9309039..74ecd24 100644 --- a/dialects/string-diagram/README.md +++ b/dialects/string-diagram/README.md @@ -1,3 +1,7 @@ + # String Diagram Calculus — Tangle DSL Sketch **Status:** sketch. Grammar drafted; no parser or implementation yet. diff --git a/dialects/virtual-knot/README.md b/dialects/virtual-knot/README.md index ae0ffc8..f396054 100644 --- a/dialects/virtual-knot/README.md +++ b/dialects/virtual-knot/README.md @@ -1,4 +1,7 @@ - + # Virtual Knot Calculus — Tangle DSL Sketch diff --git a/docs/CITATIONS.adoc b/docs/CITATIONS.adoc index 37fdb0f..52ba528 100644 --- a/docs/CITATIONS.adoc +++ b/docs/CITATIONS.adoc @@ -1,3 +1,5 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = RSR-template-repo - Citation Guide :toc: diff --git a/docs/PROOF-REGRESSION-WORKFLOW.adoc b/docs/PROOF-REGRESSION-WORKFLOW.adoc index d5c90c3..614e961 100644 --- a/docs/PROOF-REGRESSION-WORKFLOW.adoc +++ b/docs/PROOF-REGRESSION-WORKFLOW.adoc @@ -1,6 +1,5 @@ // SPDX-License-Identifier: MPL-2.0 -// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) - +// Copyright (c) Jonathan D.A. Jewell = Proof-Regression Workflow (Tangle's Lean 4 Integration) Jonathan Jewell (hyperpolymath) :toc: diff --git a/docs/spec/DECISIONS-LOCKED.md b/docs/spec/DECISIONS-LOCKED.md index 109b632..c729771 100644 --- a/docs/spec/DECISIONS-LOCKED.md +++ b/docs/spec/DECISIONS-LOCKED.md @@ -1,3 +1,7 @@ + # TANGLE & TANGLE-JTV Design Decisions (LOCKED 2026-02-12) This document records all locked design decisions for: diff --git a/docs/spec/FEATURE-COVERAGE.md b/docs/spec/FEATURE-COVERAGE.md index 5e1792b..21371b3 100644 --- a/docs/spec/FEATURE-COVERAGE.md +++ b/docs/spec/FEATURE-COVERAGE.md @@ -1,3 +1,7 @@ + # TANGLE & TANGLE-JTV Feature Coverage SPDX-License-Identifier: MPL-2.0 diff --git a/docs/spec/FORMAL-SEMANTICS.md b/docs/spec/FORMAL-SEMANTICS.md index dd04f87..1ebd54e 100644 --- a/docs/spec/FORMAL-SEMANTICS.md +++ b/docs/spec/FORMAL-SEMANTICS.md @@ -1,3 +1,7 @@ + # TANGLE & TANGLE-JTV Formal Semantics Specification Version: 1.0.0-draft diff --git a/docs/spec/UNANSWERED-QUESTIONS.md b/docs/spec/UNANSWERED-QUESTIONS.md index 0e2238a..02f1517 100644 --- a/docs/spec/UNANSWERED-QUESTIONS.md +++ b/docs/spec/UNANSWERED-QUESTIONS.md @@ -1,3 +1,7 @@ + # TANGLE & TANGLE-JTV — Questions Status Last updated: 2026-02-12 diff --git a/docs/tech-debt-2026-05-26.md b/docs/tech-debt-2026-05-26.md index 9eb88ec..01d52bc 100644 --- a/docs/tech-debt-2026-05-26.md +++ b/docs/tech-debt-2026-05-26.md @@ -1,4 +1,5 @@ SPDX-License-Identifier: MPL-2.0 SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) --> diff --git a/ffi/zig/build.zig b/ffi/zig/build.zig index f76166d..6b116fc 100644 --- a/ffi/zig/build.zig +++ b/ffi/zig/build.zig @@ -1,5 +1,6 @@ -// TANGLE FFI Build Configuration // SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell +// TANGLE FFI Build Configuration const std = @import("std"); diff --git a/ffi/zig/src/main.zig b/ffi/zig/src/main.zig index 823a1bb..a22feec 100644 --- a/ffi/zig/src/main.zig +++ b/ffi/zig/src/main.zig @@ -1,9 +1,10 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell // TANGLE FFI Implementation // // This module implements the C-compatible FFI declared in src/abi/Foreign.idr // All types and layouts must match the Idris2 ABI definitions. // -// SPDX-License-Identifier: MPL-2.0 const std = @import("std"); diff --git a/ffi/zig/test/integration_test.zig b/ffi/zig/test/integration_test.zig index 83c8bc8..d53dd7e 100644 --- a/ffi/zig/test/integration_test.zig +++ b/ffi/zig/test/integration_test.zig @@ -1,5 +1,6 @@ -// TANGLE Integration Tests // SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell +// TANGLE Integration Tests const std = @import("std"); const testing = std.testing; diff --git a/flake.nix b/flake.nix deleted file mode 100644 index 16c180b..0000000 --- a/flake.nix +++ /dev/null @@ -1,116 +0,0 @@ -{ - description = "tangle - {project-description}"; - - # *REMINDER: Update inputs with actual dependencies* - inputs = { - nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable"; - flake-utils.url = "github:numtide/flake-utils"; - # Add language-specific inputs: - # rust-overlay.url = "github:oxalica/rust-overlay"; # For Rust - # fenix.url = "github:nix-community/fenix"; # Alternative Rust - }; - - outputs = { self, nixpkgs, flake-utils, ... }@inputs: - flake-utils.lib.eachDefaultSystem (system: - let - pkgs = import nixpkgs { - inherit system; - # overlays = [ (import inputs.rust-overlay) ]; # For Rust - }; - - # *REMINDER: Define build dependencies* - buildInputs = with pkgs; [ - # Language-specific dependencies: - # gnat13 # Ada - # cargo rustc # Rust - # elixir # Elixir - # For build tools: - just - podman - git - ]; - - # *REMINDER: Define development dependencies* - nativeBuildInputs = with pkgs; [ - # Development tools: - ripgrep # Code search - lychee # Link validation - # Language-specific: - # rustfmt clippy # Rust - # mix # Elixir - ]; - - in - { - # Development shell - devShells.default = pkgs.mkShell { - inherit buildInputs nativeBuildInputs; - - shellHook = '' - echo "🚀 tangle development environment" - echo "Language: idris2" - echo "" - echo "Available commands:" - echo " just --list # Show all tasks" - echo " just setup # Set up environment" - echo " just build # Build project" - echo " just test # Run tests" - echo " just validate # RSR compliance" - echo "" - # *REMINDER: Add language-specific environment setup* - # export CARGO_HOME=$PWD/.cargo # Rust - # export MIX_HOME=$PWD/.mix # Elixir - ''; - }; - - # Packages - packages.default = pkgs.stdenv.mkDerivation { - pname = "tangle"; - version = "0.1.0"; - src = ./.; - - inherit buildInputs nativeBuildInputs; - - buildPhase = '' - # *REMINDER: Add build commands* - # For Rust: cargo build --release - # For Elixir: mix compile - # For Ada: gprbuild -P tangle.gpr -XMODE=release - ''; - - installPhase = '' - mkdir -p $out/bin - # *REMINDER: Add install commands* - # cp target/release/tangle $out/bin/ # Rust - # cp bin/tangle $out/bin/ # Ada - ''; - - meta = with pkgs.lib; { - description = "{project-description}"; - homepage = "{repo-url}"; - license = with licenses; [ mit ]; # MIT + Palimpsest - maintainers = [ "{maintainer-name}" ]; - platforms = platforms.unix; - }; - }; - - # Apps - apps.default = { - type = "app"; - program = "${self.packages.${system}.default}/bin/tangle"; - }; - - # Checks (CI/CD integration) - checks = { - build = self.packages.${system}.default; - # *REMINDER: Add test checks* - test = pkgs.runCommand "test-tangle" { - buildInputs = [ self.packages.${system}.default ]; - } '' - # Run tests here - touch $out - ''; - }; - } - ); -} diff --git a/llm-warmup-dev.md b/llm-warmup-dev.md index 65da3b8..7092e48 100644 --- a/llm-warmup-dev.md +++ b/llm-warmup-dev.md @@ -1,3 +1,7 @@ + # LLM Warmup — tangle (Developer) ## What is tangle? diff --git a/llm-warmup-user.md b/llm-warmup-user.md index 24b2ea9..ea564e6 100644 --- a/llm-warmup-user.md +++ b/llm-warmup-user.md @@ -1,3 +1,7 @@ + # LLM Warmup — tangle (User) ## What is tangle? diff --git a/playground/README.md b/playground/README.md index 7161666..b73dc98 100644 --- a/playground/README.md +++ b/playground/README.md @@ -1,3 +1,7 @@ + # Tangle Playground A local PWA playground for the Tangle topological programming language. diff --git a/spec/README.adoc b/spec/README.adoc index 0d42b8d..c140161 100644 --- a/spec/README.adoc +++ b/spec/README.adoc @@ -1,4 +1,5 @@ // SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell // @taxonomy: spec/index = tangle — Specification Directory :toc: diff --git a/src/rust/fuzz/fuzz_targets/fuzz_lexer.rs b/src/rust/fuzz/fuzz_targets/fuzz_lexer.rs index 654ed99..9e4755d 100644 --- a/src/rust/fuzz/fuzz_targets/fuzz_lexer.rs +++ b/src/rust/fuzz/fuzz_targets/fuzz_lexer.rs @@ -1,4 +1,5 @@ // SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell //! Fuzz target for the Tangle (Rust) lexer. //! //! Invariant: the lexer must NEVER panic on ANY input. It should always diff --git a/src/rust/fuzz/fuzz_targets/fuzz_parser.rs b/src/rust/fuzz/fuzz_targets/fuzz_parser.rs index f4b9e92..aa5411c 100644 --- a/src/rust/fuzz/fuzz_targets/fuzz_parser.rs +++ b/src/rust/fuzz/fuzz_targets/fuzz_parser.rs @@ -1,4 +1,5 @@ // SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell // SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell // // Fuzz target for the TANGLE (Rust) parser. diff --git a/src/rust/src/ast.rs b/src/rust/src/ast.rs index 7f4da9d..e28eb22 100644 --- a/src/rust/src/ast.rs +++ b/src/rust/src/ast.rs @@ -1,5 +1,5 @@ // SPDX-License-Identifier: MPL-2.0 -// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +// Copyright (c) Jonathan D.A. Jewell // // ast.rs — Abstract syntax tree for TANGLE // diff --git a/src/rust/src/ast_jtv.rs b/src/rust/src/ast_jtv.rs index 865445e..e7f0b4c 100644 --- a/src/rust/src/ast_jtv.rs +++ b/src/rust/src/ast_jtv.rs @@ -1,4 +1,5 @@ // SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell // ast_jtv.rs — AST extensions for TANGLE-JTV injection blocks // // Two injection syntaxes: diff --git a/src/rust/src/eval.rs b/src/rust/src/eval.rs index 4f8dc89..5da9bce 100644 --- a/src/rust/src/eval.rs +++ b/src/rust/src/eval.rs @@ -1,5 +1,5 @@ // SPDX-License-Identifier: MPL-2.0 -// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +// Copyright (c) Jonathan D.A. Jewell // // eval.rs — Tree-walking interpreter for TANGLE // diff --git a/src/rust/src/lexer.rs b/src/rust/src/lexer.rs index e65b55a..43c4b15 100644 --- a/src/rust/src/lexer.rs +++ b/src/rust/src/lexer.rs @@ -1,4 +1,5 @@ // SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell // lexer.rs — TANGLE + TANGLE-JTV tokenizer with mode switching // // Three lexing modes: diff --git a/src/rust/src/lib.rs b/src/rust/src/lib.rs index 1e008c4..ec32552 100644 --- a/src/rust/src/lib.rs +++ b/src/rust/src/lib.rs @@ -1,4 +1,5 @@ // SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell // lib.rs — tanglec library root #![forbid(unsafe_code)] diff --git a/src/rust/src/main.rs b/src/rust/src/main.rs index 4ad554d..48ca411 100644 --- a/src/rust/src/main.rs +++ b/src/rust/src/main.rs @@ -1,5 +1,5 @@ // SPDX-License-Identifier: MPL-2.0 -// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +// Copyright (c) Jonathan D.A. Jewell // // main.rs — tanglec CLI entry point // diff --git a/src/rust/src/parser.rs b/src/rust/src/parser.rs index 7193e35..321d7d0 100644 --- a/src/rust/src/parser.rs +++ b/src/rust/src/parser.rs @@ -1,4 +1,5 @@ // SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell // parser.rs — Recursive descent parser for TANGLE // // Precedence (lowest to highest): diff --git a/src/rust/src/parser_jtv.rs b/src/rust/src/parser_jtv.rs index 303eb24..21eacfe 100644 --- a/src/rust/src/parser_jtv.rs +++ b/src/rust/src/parser_jtv.rs @@ -1,4 +1,5 @@ // SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell // parser_jtv.rs — Parsers for TANGLE-JTV injection blocks // // Harvard data expression precedence (lowest to highest): diff --git a/src/rust/src/sexpr.rs b/src/rust/src/sexpr.rs index b02a00a..959068f 100644 --- a/src/rust/src/sexpr.rs +++ b/src/rust/src/sexpr.rs @@ -1,5 +1,5 @@ // SPDX-License-Identifier: MPL-2.0 -// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +// Copyright (c) Jonathan D.A. Jewell // // sexpr.rs — S-expression and JSON AST dump for TANGLE // diff --git a/verification/README.adoc b/verification/README.adoc index 3ece357..667f255 100644 --- a/verification/README.adoc +++ b/verification/README.adoc @@ -1,4 +1,5 @@ // SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell // @taxonomy: verification/index = tangle — Verification Directory :toc: