diff --git a/.devcontainer/README.adoc b/.devcontainer/README.adoc index 1bda9be..dd19ddf 100644 --- a/.devcontainer/README.adoc +++ b/.devcontainer/README.adoc @@ -1,4 +1,5 @@ // SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Dev Container Usage :author: Jonathan D.A. Jewell diff --git a/.github/CODE_OF_CONDUCT.md b/.github/CODE_OF_CONDUCT.md index 63fb712..8348e65 100644 --- a/.github/CODE_OF_CONDUCT.md +++ b/.github/CODE_OF_CONDUCT.md @@ -1,3 +1,7 @@ + # Code of Conduct # Clone the repository git clone https://github.com/hyperpolymath/standards.git # Note: A2ML is located in standards/a2ml-validate-action.git @@ -33,7 +37,7 @@ a2ml-validate-action/ ├── .machine_readable/ # ALL machine-readable content (Perimeter 1) │ ├── *.a2ml # State files (STATE, META, ECOSYSTEM, etc.) │ ├── bot_directives/ # Bot configs -│ └── contractiles/ # Policy contracts (k9, dust, lust, must, trust) +│ └── contractiles/ # Policy contracts (k9, dust, intend, must, trust) ├── .well-known/ # Protocol files (Perimeter 1-3) ├── .github/ # GitHub config (Perimeter 1) │ ├── ISSUE_TEMPLATE/ diff --git a/.github/DIRECTORY.adoc b/.github/DIRECTORY.adoc index a97d220..b4caddf 100644 --- a/.github/DIRECTORY.adoc +++ b/.github/DIRECTORY.adoc @@ -1 +1,3 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = .github Pillar diff --git a/.github/GOVERNANCE.md b/.github/GOVERNANCE.md index 5a7f911..98ce21b 100644 --- a/.github/GOVERNANCE.md +++ b/.github/GOVERNANCE.md @@ -1,5 +1,7 @@ - - + # Project Governance This document describes the governance model for **a2ml-validate-action**. diff --git a/.github/SECURITY.md b/.github/SECURITY.md index 2fc76f1..8ea36d5 100644 --- a/.github/SECURITY.md +++ b/.github/SECURITY.md @@ -1,3 +1,7 @@ + # Security Policy + diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 63eb6ad..9f5155c 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,4 +1,7 @@ - + ## Summary diff --git a/.github/workflows/boj-build.yml b/.github/workflows/boj-build.yml index 2d3ca0d..4a74fc4 100644 --- a/.github/workflows/boj-build.yml +++ b/.github/workflows/boj-build.yml @@ -7,6 +7,7 @@ on: jobs: trigger-boj: runs-on: ubuntu-latest + timeout-minutes: 15 steps: - name: Checkout uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 diff --git a/.github/workflows/casket-pages.yml b/.github/workflows/casket-pages.yml index ad8fd14..87c1e3f 100644 --- a/.github/workflows/casket-pages.yml +++ b/.github/workflows/casket-pages.yml @@ -18,6 +18,7 @@ concurrency: jobs: build: runs-on: ubuntu-latest + timeout-minutes: 15 steps: - name: Checkout uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4 @@ -109,6 +110,7 @@ jobs: name: github-pages url: ${{ steps.deployment.outputs.page_url }} runs-on: ubuntu-latest + timeout-minutes: 15 needs: build steps: - name: Deploy to GitHub Pages diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml index c475caf..e547933 100644 --- a/.github/workflows/codeql.yml +++ b/.github/workflows/codeql.yml @@ -23,6 +23,7 @@ permissions: jobs: analyze: runs-on: ubuntu-latest + timeout-minutes: 15 permissions: contents: read security-events: write diff --git a/.github/workflows/dogfood-gate.yml b/.github/workflows/dogfood-gate.yml index a9b8da5..3807e9a 100644 --- a/.github/workflows/dogfood-gate.yml +++ b/.github/workflows/dogfood-gate.yml @@ -22,6 +22,7 @@ jobs: a2ml-validate: name: Validate A2ML manifests runs-on: ubuntu-latest + timeout-minutes: 15 steps: - name: Checkout repository @@ -66,6 +67,7 @@ jobs: k9-validate: name: Validate K9 contracts runs-on: ubuntu-latest + timeout-minutes: 15 steps: - name: Checkout repository @@ -115,6 +117,7 @@ jobs: empty-lint: name: Empty-linter (invisible characters) runs-on: ubuntu-latest + timeout-minutes: 15 steps: - name: Checkout repository @@ -179,6 +182,7 @@ jobs: groove-check: name: Groove manifest check runs-on: ubuntu-latest + timeout-minutes: 15 steps: - name: Checkout repository @@ -237,6 +241,7 @@ jobs: eclexiaiser-validate: name: Validate eclexiaiser manifest runs-on: ubuntu-latest + timeout-minutes: 15 steps: - name: Checkout repository @@ -300,6 +305,7 @@ print(f'Valid: {project[\"name\"]} ({len(functions)} function(s))') dogfood-summary: name: Dogfooding compliance summary runs-on: ubuntu-latest + timeout-minutes: 15 needs: [a2ml-validate, k9-validate, empty-lint, groove-check, eclexiaiser-validate] if: always() diff --git a/.github/workflows/governance.yml b/.github/workflows/governance.yml index 653ef98..1b4e269 100644 --- a/.github/workflows/governance.yml +++ b/.github/workflows/governance.yml @@ -31,4 +31,5 @@ permissions: 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 dfacf3b..127905d 100644 --- a/.github/workflows/hypatia-scan.yml +++ b/.github/workflows/hypatia-scan.yml @@ -43,6 +43,7 @@ jobs: scan: name: Hypatia Neurosymbolic Analysis runs-on: ubuntu-latest + timeout-minutes: 15 steps: - name: Checkout repository diff --git a/.github/workflows/instant-sync.yml b/.github/workflows/instant-sync.yml index 228dc43..01646a7 100644 --- a/.github/workflows/instant-sync.yml +++ b/.github/workflows/instant-sync.yml @@ -14,6 +14,7 @@ permissions: jobs: dispatch: runs-on: ubuntu-latest + timeout-minutes: 15 steps: - name: Trigger Propagation uses: peter-evans/repository-dispatch@28959ce8df70de7be546dd1250a005dd32156697 # v3 diff --git a/.github/workflows/mirror.yml b/.github/workflows/mirror.yml index efdb7b7..f86bc9c 100644 --- a/.github/workflows/mirror.yml +++ b/.github/workflows/mirror.yml @@ -13,6 +13,7 @@ permissions: jobs: mirror-gitlab: runs-on: ubuntu-latest + timeout-minutes: 15 if: vars.GITLAB_MIRROR_ENABLED == 'true' steps: - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 @@ -31,6 +32,7 @@ jobs: mirror-bitbucket: runs-on: ubuntu-latest + timeout-minutes: 15 if: vars.BITBUCKET_MIRROR_ENABLED == 'true' steps: - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 @@ -49,6 +51,7 @@ jobs: mirror-codeberg: runs-on: ubuntu-latest + timeout-minutes: 15 if: vars.CODEBERG_MIRROR_ENABLED == 'true' steps: - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 @@ -67,6 +70,7 @@ jobs: mirror-sourcehut: runs-on: ubuntu-latest + timeout-minutes: 15 if: vars.SOURCEHUT_MIRROR_ENABLED == 'true' steps: - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 @@ -85,6 +89,7 @@ jobs: mirror-disroot: runs-on: ubuntu-latest + timeout-minutes: 15 if: vars.DISROOT_MIRROR_ENABLED == 'true' steps: - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 @@ -103,6 +108,7 @@ jobs: mirror-gitea: runs-on: ubuntu-latest + timeout-minutes: 15 if: vars.GITEA_MIRROR_ENABLED == 'true' steps: - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 @@ -121,6 +127,7 @@ jobs: mirror-radicle: runs-on: ubuntu-latest + timeout-minutes: 15 if: vars.RADICLE_MIRROR_ENABLED == 'true' steps: - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index b80da1c..5ec671c 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -18,6 +18,7 @@ jobs: build: name: Build Artifacts runs-on: ubuntu-latest + timeout-minutes: 15 permissions: contents: read steps: @@ -34,7 +35,7 @@ jobs: # mix release # TODO: Upload build artifacts if needed - # - uses: actions/upload-artifact@v4 + # - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4 # with: # name: release-artifacts # path: target/release/ @@ -42,6 +43,7 @@ jobs: changelog: name: Generate Changelog runs-on: ubuntu-latest + timeout-minutes: 15 permissions: contents: read outputs: @@ -88,13 +90,14 @@ jobs: name: Create GitHub Release needs: [build, changelog] runs-on: ubuntu-latest + timeout-minutes: 15 permissions: contents: write steps: - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 # TODO: Download build artifacts if uploading to the release - # - uses: actions/download-artifact@v4 + # - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4 # with: # name: release-artifacts # path: artifacts/ diff --git a/.github/workflows/rhodibot.yml b/.github/workflows/rhodibot.yml index a82f178..471d9d4 100644 --- a/.github/workflows/rhodibot.yml +++ b/.github/workflows/rhodibot.yml @@ -27,6 +27,7 @@ permissions: jobs: rhodibot: runs-on: ubuntu-latest + timeout-minutes: 15 steps: - name: Checkout uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 diff --git a/.github/workflows/scorecard-enforcer.yml b/.github/workflows/scorecard-enforcer.yml index 6933b78..57535d0 100644 --- a/.github/workflows/scorecard-enforcer.yml +++ b/.github/workflows/scorecard-enforcer.yml @@ -23,6 +23,7 @@ permissions: jobs: scorecard: runs-on: ubuntu-latest + timeout-minutes: 15 permissions: security-events: write id-token: write # For OIDC @@ -61,6 +62,7 @@ jobs: # Check specific high-priority items check-critical: runs-on: ubuntu-latest + timeout-minutes: 15 steps: - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 diff --git a/.github/workflows/scorecard.yml b/.github/workflows/scorecard.yml index 620ed0a..7c792b4 100644 --- a/.github/workflows/scorecard.yml +++ b/.github/workflows/scorecard.yml @@ -21,6 +21,7 @@ permissions: jobs: analysis: runs-on: ubuntu-latest + timeout-minutes: 15 permissions: security-events: write id-token: write diff --git a/.github/workflows/secret-scanner.yml b/.github/workflows/secret-scanner.yml index 3ba3bac..1fcbb66 100644 --- a/.github/workflows/secret-scanner.yml +++ b/.github/workflows/secret-scanner.yml @@ -21,6 +21,7 @@ permissions: jobs: trufflehog: runs-on: ubuntu-latest + timeout-minutes: 15 steps: - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v4 with: @@ -35,6 +36,7 @@ jobs: gitleaks: runs-on: ubuntu-latest + timeout-minutes: 15 steps: - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v4 with: @@ -48,6 +50,7 @@ jobs: # Rust-specific: Check for hardcoded crypto values rust-secrets: runs-on: ubuntu-latest + timeout-minutes: 15 steps: - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v4 diff --git a/.github/workflows/static-analysis-gate.yml b/.github/workflows/static-analysis-gate.yml index af0a0f3..ccb4883 100644 --- a/.github/workflows/static-analysis-gate.yml +++ b/.github/workflows/static-analysis-gate.yml @@ -19,6 +19,7 @@ jobs: panic-attack-assail: name: panic-attack assail runs-on: ubuntu-latest + timeout-minutes: 15 steps: - name: Checkout repository @@ -123,6 +124,7 @@ jobs: hypatia-scan: name: Hypatia neurosymbolic scan runs-on: ubuntu-latest + timeout-minutes: 15 steps: - name: Checkout repository @@ -235,6 +237,7 @@ jobs: deposit-findings: name: Deposit findings for gitbot-fleet runs-on: ubuntu-latest + timeout-minutes: 15 needs: [panic-attack-assail, hypatia-scan] if: always() diff --git a/.machine_readable/6a2/0-AI-MANIFEST.a2ml b/.machine_readable/6a2/0-AI-MANIFEST.a2ml new file mode 100644 index 0000000..6bf1f8c --- /dev/null +++ b/.machine_readable/6a2/0-AI-MANIFEST.a2ml @@ -0,0 +1,31 @@ +# 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 + +## Protocol + +When multiple agents may write to A2ML files concurrently: +1. Read file and record git-sha-at-read in [provenance] section +2. Lock by creating .lock- +3. Write updated file with new [provenance] metadata +4. Release by removing lock file +5. On conflict: re-read and retry if git-sha-at-read does not match HEAD + diff --git a/.machine_readable/6a2/README.adoc b/.machine_readable/6a2/README.adoc new file mode 100644 index 0000000..bc033d7 --- /dev/null +++ b/.machine_readable/6a2/README.adoc @@ -0,0 +1,30 @@ +// 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 + +## Generation + +These files may be generated from .scm source files using transpilation tools. +Source .scm files should be removed after successful transpilation. + +## See Also + +- [A2ML Repository Template](https://github.com/hyperpolymath/standards/blob/main/A2ML-REPO-TEMPLATE.adoc) +- [6A2 Format Family](https://github.com/hyperpolymath/standards#a2ml-format-family-7-formats) + diff --git a/.machine_readable/6a2/anchor/0-AI-MANIFEST.a2ml b/.machine_readable/6a2/anchor/0-AI-MANIFEST.a2ml new file mode 100644 index 0000000..0dd6825 --- /dev/null +++ b/.machine_readable/6a2/anchor/0-AI-MANIFEST.a2ml @@ -0,0 +1,21 @@ +# AI Manifest for Anchor Directory + +## Purpose + +This manifest declares the AI-assistant context for the anchor machine-readable metadata directory. + +## Canonical Locations + +ANCHOR.a2ml files MUST exist in this directory. + +## Multiple Versions + +Unlike other A2ML files, multiple versions of ANCHOR.a2ml with different dates MAY exist. +Each version represents a specific recalibration point. + +## Invariants + +- Multiple versions with different dates are permitted +- No other A2ML files in this directory +- Single source of truth for anchor documents + diff --git a/.machine_readable/anchors/ANCHOR.a2ml b/.machine_readable/6a2/anchor/ANCHOR.a2ml similarity index 100% rename from .machine_readable/anchors/ANCHOR.a2ml rename to .machine_readable/6a2/anchor/ANCHOR.a2ml diff --git a/.machine_readable/6a2/anchor/README.adoc b/.machine_readable/6a2/anchor/README.adoc new file mode 100644 index 0000000..bd23e35 --- /dev/null +++ b/.machine_readable/6a2/anchor/README.adoc @@ -0,0 +1,25 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell +# A2ML Anchor Directory + +This directory contains ANCHOR.a2ml files for project recalibration and scope intervention. + +## Files + +- `ANCHOR.a2ml` - Project recalibration, scope intervention, canonical authority + +## Multiple Versions + +Unlike other A2ML files, multiple versions of ANCHOR.a2ml with different dates may exist. +Each version represents a specific recalibration point in the project history. + +## Standards Compliance + +These files follow the ANCHOR.a2ml specification from: +https://github.com/hyperpolymath/standards/tree/main/anchor-a2ml + +## See Also + +- [A2ML Repository Template](https://github.com/hyperpolymath/standards/blob/main/A2ML-REPO-TEMPLATE.adoc) +- [Anchor A2ML Spec](https://github.com/hyperpolymath/standards/tree/main/anchor-a2ml) + diff --git a/.machine_readable/ADJUST.contractile b/.machine_readable/ADJUST.contractile deleted file mode 100644 index 819a52e..0000000 --- a/.machine_readable/ADJUST.contractile +++ /dev/null @@ -1,126 +0,0 @@ -; SPDX-License-Identifier: MPL-2.0 -; ADJUST.contractile — Accessibility invariants for a2ml-validate-action -; "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 "a2ml-validate-action") - - (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 1094872..0000000 --- a/.machine_readable/INTENT.contractile +++ /dev/null @@ -1,72 +0,0 @@ -; SPDX-License-Identifier: MPL-2.0 -; INTENT.contractile — Purpose and scope for a2ml-validate-action -; 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 "a2ml-validate-action") - - ; === 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 5e3b5be..0000000 --- a/.machine_readable/MUST.contractile +++ /dev/null @@ -1,91 +0,0 @@ -; SPDX-License-Identifier: MPL-2.0 -; MUST.contractile — Baseline invariants for a2ml-validate-action -; 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 "a2ml-validate-action") - - ; === 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/README.adoc b/.machine_readable/README.adoc index 471d6c7..e72996d 100644 --- a/.machine_readable/README.adoc +++ b/.machine_readable/README.adoc @@ -1 +1,3 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = .machine_readable Pillar diff --git a/.machine_readable/TRUST.contractile b/.machine_readable/TRUST.contractile deleted file mode 100644 index 4457215..0000000 --- a/.machine_readable/TRUST.contractile +++ /dev/null @@ -1,80 +0,0 @@ -; SPDX-License-Identifier: MPL-2.0 -; TRUST.contractile — Trust boundaries for a2ml-validate-action -; 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 "a2ml-validate-action") - - (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/ai/PLACEHOLDERS.adoc b/.machine_readable/ai/PLACEHOLDERS.adoc index 515a515..23a711d 100644 --- a/.machine_readable/ai/PLACEHOLDERS.adoc +++ b/.machine_readable/ai/PLACEHOLDERS.adoc @@ -1,3 +1,5 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Template Placeholders # Template Placeholders diff --git a/.machine_readable/ai/README.adoc b/.machine_readable/ai/README.adoc index 121bbc8..8cf2ea7 100644 --- a/.machine_readable/ai/README.adoc +++ b/.machine_readable/ai/README.adoc @@ -1,3 +1,5 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = AI Guidance Directory Put AI-facing instructions in this folder. diff --git a/.machine_readable/anchors/README.adoc b/.machine_readable/anchors/README.adoc index 1b27c02..c264945 100644 --- a/.machine_readable/anchors/README.adoc +++ b/.machine_readable/anchors/README.adoc @@ -1 +1,3 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = anchors Registry diff --git a/.machine_readable/agent_instructions/README.adoc b/.machine_readable/bot_directives/README.adoc similarity index 88% rename from .machine_readable/agent_instructions/README.adoc rename to .machine_readable/bot_directives/README.adoc index 9bc2e24..a5315c7 100644 --- a/.machine_readable/agent_instructions/README.adoc +++ b/.machine_readable/bot_directives/README.adoc @@ -1,5 +1,5 @@ // SPDX-License-Identifier: MPL-2.0 -// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +// Copyright (c) Jonathan D.A. Jewell = Agent Instructions :toc: preamble @@ -32,7 +32,7 @@ Methodology-aware configuration for AI agents. Read by any AI agent == Relationship to Other Files * `AGENTIC.a2ml` says WHAT agents can do (permissions, gating) -* `agent_instructions/` says HOW agents should work (methodology) +* `bot_directives/` 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) 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/configs/README.adoc b/.machine_readable/configs/README.adoc index 616b9e7..2ab097e 100644 --- a/.machine_readable/configs/README.adoc +++ b/.machine_readable/configs/README.adoc @@ -1 +1,3 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = configs Registry 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..b6e20af --- /dev/null +++ b/.machine_readable/contractiles/Justfile @@ -0,0 +1,1026 @@ +# SPDX-License-Identifier: MPL-2.0 +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# RSR Standard Justfile Template +# https://just.systems/man/en/ +# +# Copy this file to new projects and customize the placeholder values. +# +# Run `just` to see all available recipes +# Run `just cookbook` to generate docs/just-cookbook.adoc +# Run `just combinations` to see matrix recipe options + +set shell := ["bash", "-uc"] +set dotenv-load := true +set positional-arguments := true + +# Import auto-generated contractile recipes (must-check, trust-verify, etc.) +# Re-generate with: contractile gen-just +import? "contractile.just" + +# Project metadata — customize these +project := "a2ml-validate-action" +version := "0.1.0" +tier := "infrastructure" # 1 | 2 | infrastructure + +# ═══════════════════════════════════════════════════════════════════════════════ +# DEFAULT & HELP +# ═══════════════════════════════════════════════════════════════════════════════ + +# Show all available recipes with descriptions +default: + @just --list --unsorted + +# Show detailed help for a specific recipe +help recipe="": + #!/usr/bin/env bash + if [ -z "{{recipe}}" ]; then + just --list --unsorted + echo "" + echo "Usage: just help " + echo " just cookbook # Generate full documentation" + echo " just combinations # Show matrix recipes" + else + just --show "{{recipe}}" 2>/dev/null || echo "Recipe '{{recipe}}' not found" + fi + +# Show this project's info +info: + @echo "Project: {{project}}" + @echo "Version: {{version}}" + @echo "RSR Tier: {{tier}}" + @echo "Recipes: $(just --summary | wc -w)" + @[ -f ".machine_readable/STATE.a2ml" ] && grep -oP 'phase\s*=\s*"\K[^"]+' .machine_readable/STATE.a2ml | head -1 | xargs -I{} echo "Phase: {}" || true + +# ═══════════════════════════════════════════════════════════════════════════════ +# INIT — Bootstrap a new project from this template +# ═══════════════════════════════════════════════════════════════════════════════ + +# Interactive project bootstrap — replaces all {{PLACEHOLDER}} tokens +init: + #!/usr/bin/env bash + set -euo pipefail + + echo "═══════════════════════════════════════════════════" + echo " RSR Project Bootstrap" + echo "═══════════════════════════════════════════════════" + echo "" + + # --- Load defaults from config (if exists) --- + # Create yours: ~/.config/rsr/defaults + # Format: OWNER=myorg AUTHOR="My Name" AUTHOR_EMAIL=me@example.org ... + DEFAULTS="${XDG_CONFIG_HOME:-$HOME/.config}/rsr/defaults" + if [ -f "$DEFAULTS" ]; then + echo "Loading defaults from $DEFAULTS" + # shellcheck source=/dev/null + source "$DEFAULTS" + echo "" + fi + + # --- Required values (pre-filled from defaults if available) --- + read -rp "Project name (human-readable, e.g. My Project): " PROJECT_NAME + [ -z "$PROJECT_NAME" ] && echo "Error: project name required" && exit 1 + + read -rp "Repository slug (e.g. my-project): " REPO + [ -z "$REPO" ] && echo "Error: repo slug required" && exit 1 + + read -rp "Owner [${OWNER:-}]: " _OWNER + OWNER="${_OWNER:-${OWNER:-}}" + [ -z "$OWNER" ] && echo "Error: owner required" && exit 1 + + read -rp "Author full name [${AUTHOR:-}]: " _AUTHOR + AUTHOR="${_AUTHOR:-${AUTHOR:-}}" + [ -z "$AUTHOR" ] && echo "Error: author name required" && exit 1 + + read -rp "Author email [${AUTHOR_EMAIL:-}]: " _AUTHOR_EMAIL + AUTHOR_EMAIL="${_AUTHOR_EMAIL:-${AUTHOR_EMAIL:-}}" + [ -z "$AUTHOR_EMAIL" ] && echo "Error: email required" && exit 1 + + # --- Optional values (pre-filled from defaults if available) --- + read -rp "Author organization [${AUTHOR_ORG:-none}]: " _AUTHOR_ORG + AUTHOR_ORG="${_AUTHOR_ORG:-${AUTHOR_ORG:-}}" + + read -rp "Previous/alt email [${AUTHOR_EMAIL_ALT:-none}]: " _AUTHOR_EMAIL_ALT + AUTHOR_EMAIL_ALT="${_AUTHOR_EMAIL_ALT:-${AUTHOR_EMAIL_ALT:-}}" + + read -rp "Project description []: " PROJECT_DESCRIPTION + + read -rp "Forge domain [${FORGE:-github.com}]: " _FORGE + FORGE="${_FORGE:-${FORGE:-github.com}}" + + read -rp "Security contact email [${SECURITY_EMAIL:-$AUTHOR_EMAIL}]: " _SECURITY_EMAIL + SECURITY_EMAIL="${_SECURITY_EMAIL:-${SECURITY_EMAIL:-$AUTHOR_EMAIL}}" + + read -rp "Conduct contact email [${CONDUCT_EMAIL:-$AUTHOR_EMAIL}]: " _CONDUCT_EMAIL + CONDUCT_EMAIL="${_CONDUCT_EMAIL:-${CONDUCT_EMAIL:-$AUTHOR_EMAIL}}" + + read -rp "Project type (library|binary|monorepo|service|website) [library]: " PROJECT_TYPE + PROJECT_TYPE="${PROJECT_TYPE:-library}" + + read -rp "Website URL [https://${FORGE}/${OWNER}/${REPO}]: " WEBSITE + WEBSITE="${WEBSITE:-https://${FORGE}/${OWNER}/${REPO}}" + + # --- Container values (optional — only relevant if container/ exists) --- + if [ -d "container" ]; then + echo "" + echo "── Container configuration (optional) ─────────" + read -rp "Service name [${REPO}]: " _SERVICE_NAME + SERVICE_NAME="${_SERVICE_NAME:-${REPO}}" + read -rp "Primary port [8080]: " _PORT + PORT="${_PORT:-8080}" + read -rp "Container registry [ghcr.io/${OWNER}]: " _REGISTRY + REGISTRY="${_REGISTRY:-ghcr.io/${OWNER}}" + else + SERVICE_NAME="${REPO}" + PORT="8080" + REGISTRY="ghcr.io/${OWNER}" + fi + + # --- Derived values --- + PROJECT_UPPER=$(echo "$REPO" | tr '[:lower:]-' '[:upper:]_') + PROJECT_LOWER=$(echo "$REPO" | tr '[:upper:]-' '[:lower:]_') + CURRENT_YEAR=$(date +%Y) + CURRENT_DATE=$(date +%Y-%m-%d) + VERSION="0.1.0" + + # Derive citation name parts (best-effort split on last space) + AUTHOR_LAST="${AUTHOR##* }" + AUTHOR_FIRST="${AUTHOR% *}" + FIRST_INITIAL="${AUTHOR_FIRST:0:1}." + if [ "$AUTHOR_LAST" = "$AUTHOR_FIRST" ]; then + AUTHOR_FIRST="$AUTHOR" + AUTHOR_LAST="" + FIRST_INITIAL="" + fi + + echo "" + echo "── Summary ──────────────────────────────────────" + echo " Project: $PROJECT_NAME" + echo " Repo: $REPO" + echo " Owner: $OWNER" + echo " Author: $AUTHOR <$AUTHOR_EMAIL>" + [ -n "$AUTHOR_ORG" ] && echo " Organization: $AUTHOR_ORG" + echo " Forge: $FORGE" + echo " Year: $CURRENT_YEAR" + echo "────────────────────────────────────────────────" + echo "" + read -rp "Proceed? [Y/n] " CONFIRM + [[ "${CONFIRM:-Y}" =~ ^[Nn] ]] && echo "Aborted." && exit 0 + + echo "" + echo "Replacing placeholders..." + + # Brace tokens as variables (hex avoids just interpolation) + LB=$(printf '\x7b\x7b') + RB=$(printf '\x7d\x7d') + + # Build the sed expression list + # Note: using | as delimiter since URLs contain / + SED_ARGS=( + -e "s|${LB}PROJECT_NAME${RB}|${PROJECT_NAME}|g" + -e "s|${LB}PROJECT_DESCRIPTION${RB}|${PROJECT_DESCRIPTION}|g" + -e "s|${LB}PROJECT${RB}|${PROJECT_UPPER}|g" + -e "s|${LB}project${RB}|${PROJECT_LOWER}|g" + -e "s|${LB}REPO${RB}|${REPO}|g" + -e "s|${LB}OWNER${RB}|${OWNER}|g" + -e "s|${LB}AUTHOR${RB}|${AUTHOR}|g" + -e "s|${LB}AUTHOR_EMAIL${RB}|${AUTHOR_EMAIL}|g" + -e "s|${LB}AUTHOR_ORG${RB}|${AUTHOR_ORG}|g" + -e "s|${LB}AUTHOR_LAST${RB}|${AUTHOR_LAST}|g" + -e "s|${LB}AUTHOR_FIRST${RB}|${AUTHOR_FIRST}|g" + -e "s|${LB}AUTHOR_INITIALS${RB}|${FIRST_INITIAL}|g" + -e "s|${LB}FORGE${RB}|${FORGE}|g" + -e "s|${LB}CURRENT_YEAR${RB}|${CURRENT_YEAR}|g" + -e "s|${LB}CURRENT_DATE${RB}|${CURRENT_DATE}|g" + -e "s|${LB}DATE${RB}|${CURRENT_DATE}|g" + -e "s|${LB}SECURITY_EMAIL${RB}|${SECURITY_EMAIL}|g" + -e "s|${LB}CONDUCT_EMAIL${RB}|${CONDUCT_EMAIL}|g" + -e "s|${LB}LICENSE${RB}|MPL-2.0|g" + -e "s|${LB}CONDUCT_TEAM${RB}|Code of Conduct Committee|g" + -e "s|${LB}RESPONSE_TIME${RB}|48 hours|g" + -e "s|${LB}MAIN_BRANCH${RB}|main|g" + -e "s|${LB}PROJECT_PURPOSE${RB}|${PROJECT_DESCRIPTION}|g" + -e "s|${LB}PROJECT_ROLE${RB}|${PROJECT_TYPE}|g" + -e "s|${LB}PROJECT_TYPE${RB}|${PROJECT_TYPE}|g" + -e "s|${LB}WEBSITE${RB}|${WEBSITE}|g" + -e "s|${LB}SERVICE_NAME${RB}|${SERVICE_NAME}|g" + -e "s|${LB}PORT${RB}|${PORT}|g" + -e "s|${LB}REGISTRY${RB}|${REGISTRY}|g" + -e "s|${LB}IMAGE${RB}|${REGISTRY}/${SERVICE_NAME}|g" + -e "s|${LB}VERSION${RB}|${VERSION}|g" + -e "s|${LB}EMAIL${RB}|${AUTHOR_EMAIL}|g" + ) + [ -n "$AUTHOR_EMAIL_ALT" ] && SED_ARGS+=(-e "s|${LB}AUTHOR_EMAIL_ALT${RB}|${AUTHOR_EMAIL_ALT}|g") + + # Replace in all text files (skip .git, LICENSE text, and binaries) + find . -type f \ + -not -path './.git/*' \ + -not -name 'MPL-2.0.txt' \ + -not -name '*.png' -not -name '*.jpg' -not -name '*.gif' \ + -not -name '*.woff' -not -name '*.woff2' \ + | while read -r file; do + if file --brief "$file" | grep -qi 'text\|ascii\|utf'; then + sed -i "${SED_ARGS[@]}" "$file" + fi + done + + # Also replace [YOUR-REPO-NAME] and [YOUR-NAME/ORG] in AI manifest + sed -i "s|\[YOUR-REPO-NAME\]|${PROJECT_NAME}|g" 0-AI-MANIFEST.a2ml 2>/dev/null || true + sed -i "s|\[YOUR-NAME/ORG\]|${OWNER}|g" 0-AI-MANIFEST.a2ml 2>/dev/null || true + + echo "" + echo "── Validation ───────────────────────────────────" + + # Check for remaining placeholders + PATTERN="${LB}[A-Z_]*${RB}" + REMAINING=$(grep -rl "$PATTERN" . --include='*.md' --include='*.adoc' --include='*.yml' --include='*.yaml' --include='*.a2ml' --include='*.toml' --include='*.scm' --include='*.ncl' --include='*.nix' --include='*.json' --include='*.sh' 2>/dev/null | grep -v '.git/' | grep -v '.machine_readable/ai/PLACEHOLDERS.adoc' || true) + if [ -n "$REMAINING" ]; then + echo "WARNING: Remaining placeholders in:" + echo "$REMAINING" | sed 's/^/ /' + echo "" + echo "Run: grep -rn '$LB' . --include='*.md' to inspect" + else + echo "All placeholders replaced successfully!" + fi + + # K9-SVC validation (if available) + if command -v k9-svc >/dev/null 2>&1; then + echo "" + echo "Running k9-svc validation..." + k9-svc validate . 2>/dev/null || true + fi + + echo "" + echo "Done! Next steps:" + echo " 1. Review changes: git diff" + echo " 2. Remove template cruft: rm .machine_readable/ai/PLACEHOLDERS.adoc" + echo " 3. Customize README.adoc for your project" + echo " 4. Commit: git add -A && git commit -m 'feat: initialize from RSR template'" + echo " 5. Push: git remote add origin git@${FORGE}:${OWNER}/${REPO}.git && git push -u origin main" + +# ═══════════════════════════════════════════════════════════════════════════════ +# BUILD & COMPILE +# ═══════════════════════════════════════════════════════════════════════════════ + +# Build the project (debug mode) +build *args: + @echo "Building {{project}} (debug)..." + # TODO: Replace with your build command + # Examples: + # cargo build {{args}} # Rust + # mix compile {{args}} # Elixir + # zig build {{args}} # Zig + # deno task build {{args}} # Deno/ReScript + @echo "Build complete" + +# Build in release mode with optimizations +build-release *args: + @echo "Building {{project}} (release)..." + # TODO: Replace with your release build command + # Examples: + # cargo build --release {{args}} + # MIX_ENV=prod mix compile {{args}} + # zig build -Doptimize=ReleaseFast {{args}} + @echo "Release build complete" + +# Build and watch for changes (requires entr or similar) +build-watch: + @echo "Watching for changes..." + # TODO: Customize file patterns for your language + # Examples: + # find src -name '*.rs' | entr -c just build + # mix compile --force --warnings-as-errors + # deno task dev + +# Clean build artifacts [reversible: rebuild with `just build`] +clean: + @echo "Cleaning..." + # TODO: Customize for your build system + rm -rf target/ _build/ build/ dist/ out/ obj/ bin/ + +# Deep clean including caches [reversible: rebuild] +clean-all: clean + rm -rf .cache .tmp + +# ═══════════════════════════════════════════════════════════════════════════════ +# TEST & QUALITY +# ═══════════════════════════════════════════════════════════════════════════════ + +# Run all tests +test *args: + @echo "Running tests..." + # TODO: Replace with your test command + # Examples: + # cargo test {{args}} + # mix test {{args}} + # zig build test {{args}} + # deno test {{args}} + @echo "Tests passed!" + +# Run tests with verbose output +test-verbose: + @echo "Running tests (verbose)..." + # TODO: Replace with verbose test command + +# Smoke test +test-smoke: + @echo "Smoke test..." + # TODO: Add basic sanity checks + +# Run all quality checks +quality: fmt-check lint test + @echo "All quality checks passed!" + +# Fix all auto-fixable issues [reversible: git checkout] +fix: fmt + @echo "Fixed all auto-fixable issues" + +# ═══════════════════════════════════════════════════════════════════════════════ +# LINT & FORMAT +# ═══════════════════════════════════════════════════════════════════════════════ + +# Format all source files [reversible: git checkout] +fmt: + @echo "Formatting source files..." + # TODO: Replace with your formatter + # Examples: + # cargo fmt + # mix format + # gleam format + # deno fmt + +# Check formatting without changes +fmt-check: + @echo "Checking formatting..." + # TODO: Replace with your format check + # Examples: + # cargo fmt --check + # mix format --check-formatted + # gleam format --check + +# Run linter +lint: + @echo "Linting source files..." + # TODO: Replace with your linter + # Examples: + # cargo clippy -- -D warnings + # mix credo --strict + # gleam check + +# ═══════════════════════════════════════════════════════════════════════════════ +# RUN & EXECUTE +# ═══════════════════════════════════════════════════════════════════════════════ + +# Run the application +run *args: build + # TODO: Replace with your run command + echo "Run not configured yet" + +# Run with verbose output +run-verbose *args: build + # TODO: Replace with verbose run command + echo "Run not configured yet" + +# Install to user path +install: build-release + @echo "Installing {{project}}..." + # TODO: Replace with your install command + +# ═══════════════════════════════════════════════════════════════════════════════ +# DEPENDENCIES +# ═══════════════════════════════════════════════════════════════════════════════ + +# Install/check all dependencies +deps: + @echo "Checking dependencies..." + # TODO: Replace with your dependency check + # Examples: + # cargo check + # mix deps.get + # gleam deps download + @echo "All dependencies satisfied" + +# Audit dependencies for vulnerabilities +deps-audit: + @echo "Auditing for vulnerabilities..." + # TODO: Replace with your audit command + # Examples: + # cargo audit + # mix audit + @command -v trivy >/dev/null && trivy fs --severity HIGH,CRITICAL --quiet . || true + @command -v gitleaks >/dev/null && gitleaks detect --source . --no-git --quiet || true + @echo "Audit complete" + +# ═══════════════════════════════════════════════════════════════════════════════ +# DOCUMENTATION +# ═══════════════════════════════════════════════════════════════════════════════ + +# Generate all documentation +docs: + @mkdir -p docs/generated docs/man + just cookbook + just man + @echo "Documentation generated in docs/" + +# Generate justfile cookbook documentation +cookbook: + #!/usr/bin/env bash + mkdir -p docs + OUTPUT="docs/just-cookbook.adoc" + echo "= {{project}} Justfile Cookbook" > "$OUTPUT" + echo ":toc: left" >> "$OUTPUT" + echo ":toclevels: 3" >> "$OUTPUT" + echo "" >> "$OUTPUT" + echo "Generated: $(date -Iseconds)" >> "$OUTPUT" + echo "" >> "$OUTPUT" + echo "== Recipes" >> "$OUTPUT" + echo "" >> "$OUTPUT" + just --list --unsorted | while read -r line; do + if [[ "$line" =~ ^[[:space:]]+([a-z_-]+) ]]; then + recipe="${BASH_REMATCH[1]}" + echo "=== $recipe" >> "$OUTPUT" + echo "" >> "$OUTPUT" + echo "[source,bash]" >> "$OUTPUT" + echo "----" >> "$OUTPUT" + echo "just $recipe" >> "$OUTPUT" + echo "----" >> "$OUTPUT" + echo "" >> "$OUTPUT" + fi + done + echo "Generated: $OUTPUT" + +# Generate man page +man: + #!/usr/bin/env bash + mkdir -p docs/man + cat > docs/man/{{project}}.1 << EOF + .TH {{project}} 1 "$(date +%Y-%m-%d)" "{{version}}" "{{project}} Manual" + .SH NAME + {{project}} \- RSR-compliant project + .SH SYNOPSIS + .B just + [recipe] [args...] + .SH DESCRIPTION + RSR (Rhodium Standard Repository) project managed with just. + .SH AUTHOR + $(git config user.name 2>/dev/null || echo "Author") <$(git config user.email 2>/dev/null || echo "email")> + EOF + echo "Generated: docs/man/{{project}}.1" + +# ═══════════════════════════════════════════════════════════════════════════════ +# CONTAINERS (stapeln ecosystem — Podman + Chainguard Wolfi) +# ═══════════════════════════════════════════════════════════════════════════════ + +# Initialise container templates — substitute placeholders with project values +container-init: + #!/usr/bin/env bash + set -euo pipefail + + if [ ! -d "container" ]; then + echo "Error: container/ directory not found." + echo "This repo may not have been created from rsr-template-repo." + exit 1 + fi + + echo "=== Container Template Initialisation ===" + echo "" + + # Load RSR defaults if available + DEFAULTS="${XDG_CONFIG_HOME:-$HOME/.config}/rsr/defaults" + if [ -f "$DEFAULTS" ]; then + echo "Loading defaults from $DEFAULTS" + # shellcheck source=/dev/null + source "$DEFAULTS" + echo "" + fi + + # Prompt for container-specific values + read -rp "Service name (e.g. my-api) [{{project}}]: " _SERVICE_NAME + SERVICE_NAME="${_SERVICE_NAME:-{{project}}}" + + read -rp "Primary port [8080]: " _PORT + PORT="${_PORT:-8080}" + + read -rp "Container registry [ghcr.io/${OWNER:-hyperpolymath}]: " _REGISTRY + REGISTRY="${_REGISTRY:-ghcr.io/${OWNER:-hyperpolymath}}" + + echo "" + echo " Service: $SERVICE_NAME" + echo " Port: $PORT" + echo " Registry: $REGISTRY" + echo "" + read -rp "Proceed? [Y/n] " CONFIRM + [[ "${CONFIRM:-Y}" =~ ^[Nn] ]] && echo "Aborted." && exit 0 + + echo "" + echo "Replacing container placeholders..." + + # Brace tokens as variables (hex escapes avoid just interpolation) + LB=$(printf '\x7b\x7b') + RB=$(printf '\x7d\x7d') + + SED_ARGS=( + -e "s|${LB}SERVICE_NAME${RB}|${SERVICE_NAME}|g" + -e "s|${LB}PORT${RB}|${PORT}|g" + -e "s|${LB}REGISTRY${RB}|${REGISTRY}|g" + ) + + find container/ -type f | while read -r file; do + if file --brief "$file" | grep -qi 'text\|ascii\|utf'; then + sed -i "${SED_ARGS[@]}" "$file" + fi + done + + echo "Container templates initialised." + echo "" + echo "Next steps:" + echo " 1. Edit container/Containerfile — add your build commands" + echo " 2. Edit container/entrypoint.sh — set your application binary" + echo " 3. Review container/compose.toml — adjust services and volumes" + echo " 4. Build: just container-build" + +# Build container image via cerro-torre pipeline +container-build *args: + #!/usr/bin/env bash + if [ -f "container/ct-build.sh" ]; then + cd container && ./ct-build.sh {{args}} + elif [ -f "container/Containerfile" ]; then + podman build -t {{project}}:latest -f container/Containerfile . + elif [ -f "Containerfile" ]; then + podman build -t {{project}}:latest -f Containerfile . + else + echo "No Containerfile found in container/ or project root" + exit 1 + fi + +# Verify compose configuration +container-verify: + #!/usr/bin/env bash + if [ ! -f "container/compose.toml" ]; then + echo "No container/compose.toml found" + exit 1 + fi + cd container + if command -v selur-compose &>/dev/null; then + selur-compose verify + else + echo "selur-compose not found, falling back to podman compose" + podman compose --file compose.toml config + fi + +# Start container stack +container-up *args: + #!/usr/bin/env bash + if [ ! -f "container/compose.toml" ]; then + echo "No container/compose.toml found" + exit 1 + fi + cd container + if command -v selur-compose &>/dev/null; then + selur-compose up {{args}} + else + podman compose --file compose.toml up {{args}} + fi + +# Stop container stack +container-down: + #!/usr/bin/env bash + cd container 2>/dev/null || { echo "No container/ directory"; exit 1; } + if command -v selur-compose &>/dev/null; then + selur-compose down + else + podman compose --file compose.toml down + fi + +# Sign and verify container bundle (build + pack + sign + verify) +container-sign: + #!/usr/bin/env bash + if [ -f "container/ct-build.sh" ]; then + cd container && ./ct-build.sh + else + echo "No container/ct-build.sh found" + exit 1 + fi + +# Push signed bundle to registry +container-push: + #!/usr/bin/env bash + if [ -f "container/ct-build.sh" ]; then + cd container && ./ct-build.sh --push + else + echo "No container/ct-build.sh found — falling back to podman push" + podman push {{project}}:latest + fi + +# Run container interactively (for debugging) +container-run *args: + podman run --rm -it {{project}}:latest {{args}} + +# ═══════════════════════════════════════════════════════════════════════════════ +# CI & AUTOMATION +# ═══════════════════════════════════════════════════════════════════════════════ + +# Run full CI pipeline locally +ci: deps quality + @echo "CI pipeline complete!" + +# Install git hooks +install-hooks: + @mkdir -p .git/hooks + @cat > .git/hooks/pre-commit << 'HOOKEOF' + #!/bin/bash + just fmt-check || exit 1 + just lint || exit 1 + HOOKEOF + @chmod +x .git/hooks/pre-commit + @echo "Git hooks installed" + +# ═══════════════════════════════════════════════════════════════════════════════ +# SECURITY +# ═══════════════════════════════════════════════════════════════════════════════ + +# Run security audit +security: deps-audit + @echo "=== Security Audit ===" + @command -v gitleaks >/dev/null && gitleaks detect --source . --verbose || true + @command -v trivy >/dev/null && trivy fs --severity HIGH,CRITICAL . || true + @echo "Security audit complete" + +# Generate SBOM +sbom: + @mkdir -p docs/security + @command -v syft >/dev/null && syft . -o spdx-json > docs/security/sbom.spdx.json || echo "syft not found" + +# ═══════════════════════════════════════════════════════════════════════════════ +# VALIDATION & COMPLIANCE +# ═══════════════════════════════════════════════════════════════════════════════ + +# Validate RSR compliance +validate-rsr: + #!/usr/bin/env bash + echo "=== RSR Compliance Check ===" + MISSING="" + for f in .editorconfig .gitignore Justfile README.adoc LICENSE 0-AI-MANIFEST.a2ml; do + [ -f "$f" ] || MISSING="$MISSING $f" + done + for f in .machine_readable/STATE.a2ml .machine_readable/META.a2ml .machine_readable/ECOSYSTEM.a2ml .machine_readable/anchors/ANCHOR.a2ml .machine_readable/policies/MAINTENANCE-AXES.a2ml .machine_readable/policies/MAINTENANCE-CHECKLIST.a2ml .machine_readable/policies/SOFTWARE-DEVELOPMENT-APPROACH.a2ml; do + [ -f "$f" ] || MISSING="$MISSING $f" + done + for f in licensing/exhibits/EXHIBIT-A-ETHICAL-USE.txt licensing/exhibits/EXHIBIT-B-QUANTUM-SAFE.txt licensing/texts/MPL-2.0.txt; do + [ -f "$f" ] || MISSING="$MISSING $f" + done + for f in src/interface/abi src/interface/ffi src/interface/generated; do + [ -d "$f" ] || MISSING="$MISSING $f" + done + for f in docs/maintenance/MAINTENANCE-CHECKLIST.adoc docs/practice/SOFTWARE-DEVELOPMENT-APPROACH.adoc; do + [ -f "$f" ] || MISSING="$MISSING $f" + done + if [ -f ".machine_readable/META.a2ml" ]; then + grep -q 'axis-1 = "must > intend > like"' .machine_readable/META.a2ml || MISSING="$MISSING META.a2ml:axis-1" + grep -q 'axis-2 = "corrective > adaptive > perfective"' .machine_readable/META.a2ml || MISSING="$MISSING META.a2ml:axis-2" + grep -q 'axis-3 = "systems > compliance > effects"' .machine_readable/META.a2ml || MISSING="$MISSING META.a2ml:axis-3" + grep -q 'scoping-first = true' .machine_readable/META.a2ml || MISSING="$MISSING META.a2ml:scoping-first" + grep -q 'idris-unsound-scan = "believe_me/assert_total"' .machine_readable/META.a2ml || MISSING="$MISSING META.a2ml:idris-unsound-scan" + grep -q 'audit-focus = "systems in place, documentation explains actual state, safety/security accounted for, observed effects reviewed"' .machine_readable/META.a2ml || MISSING="$MISSING META.a2ml:audit-focus" + grep -q 'compliance-focus = "seams/compromises/exception register, bounded exceptions, anti-drift checks"' .machine_readable/META.a2ml || MISSING="$MISSING META.a2ml:compliance-focus" + grep -q 'effects-evidence = "benchmark execution/results and maintainer status dialogue/review"' .machine_readable/META.a2ml || MISSING="$MISSING META.a2ml:effects-evidence" + grep -q 'compliance-tooling = "panic-attack"' .machine_readable/policies/MAINTENANCE-AXES.a2ml || MISSING="$MISSING MAINTENANCE-AXES.a2ml:compliance-tooling" + grep -q 'effects-tooling = "ecological checking with sustainabot guidance"' .machine_readable/policies/MAINTENANCE-AXES.a2ml || MISSING="$MISSING MAINTENANCE-AXES.a2ml:effects-tooling" + grep -q 'source-human = "docs/maintenance/MAINTENANCE-CHECKLIST.adoc"' .machine_readable/policies/MAINTENANCE-CHECKLIST.a2ml || MISSING="$MISSING MAINTENANCE-CHECKLIST.a2ml:source-human" + grep -q 'source-human = "docs/practice/SOFTWARE-DEVELOPMENT-APPROACH.adoc"' .machine_readable/policies/SOFTWARE-DEVELOPMENT-APPROACH.a2ml || MISSING="$MISSING SOFTWARE-DEVELOPMENT-APPROACH.a2ml:source-human" + fi + if [ -n "$MISSING" ]; then + echo "MISSING:$MISSING" + exit 1 + fi + echo "RSR compliance: PASS" + +# Validate STATE.a2ml syntax +validate-state: + @if [ -f ".machine_readable/STATE.a2ml" ]; then \ + grep -q '^\[metadata\]' .machine_readable/STATE.a2ml && \ + grep -q 'project\s*=' .machine_readable/STATE.a2ml && \ + echo "STATE.a2ml: valid" || echo "STATE.a2ml: INVALID (missing required sections)"; \ + else \ + echo "No .machine_readable/STATE.a2ml found"; \ + fi + +# Validate AI installation guide completeness (finishbot pre-release check) +validate-ai-install: + #!/usr/bin/env bash + echo "=== AI Installation Guide Check ===" + GUIDE="docs/AI_INSTALLATION_GUIDE.adoc" + README="README.adoc" + ERRORS=0 + + # Check guide exists + if [ ! -f "$GUIDE" ]; then + echo "MISSING: $GUIDE (create from template: docs/AI_INSTALLATION_GUIDE.adoc)" + ERRORS=$((ERRORS + 1)) + else + # Check for unfilled TODO markers + TODOS=$(grep -c '\[TODO-AI-INSTALL' "$GUIDE" 2>/dev/null || true) + if [ "$TODOS" -gt 0 ]; then + echo "INCOMPLETE: $GUIDE has $TODOS unfilled [TODO-AI-INSTALL] markers:" + grep -n '\[TODO-AI-INSTALL' "$GUIDE" | head -10 + ERRORS=$((ERRORS + 1)) + else + echo "$GUIDE: complete (no TODO markers)" + fi + + # Check AI implementation section exists + if ! grep -q 'ai-implementation' "$GUIDE" 2>/dev/null; then + echo "MISSING: [[ai-implementation]] anchor in $GUIDE" + ERRORS=$((ERRORS + 1)) + fi + + # Check privacy notice exists + if ! grep -qi 'privacy' "$GUIDE" 2>/dev/null; then + echo "MISSING: Privacy notice in $GUIDE" + ERRORS=$((ERRORS + 1)) + fi + + # Check install commands exist (not just placeholders) + if ! grep -q 'git clone' "$GUIDE" 2>/dev/null; then + echo "WARNING: No git clone command found in $GUIDE -- install commands may be incomplete" + fi + fi + + # Check README has AI install section + if [ -f "$README" ]; then + if ! grep -qi 'AI-Assisted Installation' "$README" 2>/dev/null; then + echo "MISSING: AI-Assisted Installation section in $README" + echo " Copy from docs/AI-INSTALL-README-SECTION.adoc" + ERRORS=$((ERRORS + 1)) + fi + + # Check README for unfilled TODO markers + README_TODOS=$(grep -c '\[TODO-AI-INSTALL' "$README" 2>/dev/null || true) + if [ "$README_TODOS" -gt 0 ]; then + echo "INCOMPLETE: $README has $README_TODOS unfilled [TODO-AI-INSTALL] markers" + ERRORS=$((ERRORS + 1)) + fi + fi + + if [ "$ERRORS" -gt 0 ]; then + echo "" + echo "AI install guide: FAIL ($ERRORS issues)" + exit 1 + fi + echo "AI install guide: PASS" + +# Full validation suite +validate: validate-rsr validate-state validate-ai-install + @echo "All validations passed!" + +# ═══════════════════════════════════════════════════════════════════════════════ +# STATE MANAGEMENT +# ═══════════════════════════════════════════════════════════════════════════════ + +# Update STATE.a2ml timestamp +state-touch: + @if [ -f ".machine_readable/STATE.a2ml" ]; then \ + sed -i 's/last-updated = "[^"]*"/last-updated = "'"$(date +%Y-%m-%d)"'"/' .machine_readable/STATE.a2ml && \ + echo "STATE.a2ml timestamp updated"; \ + fi + +# Show current phase from STATE.a2ml +state-phase: + @grep -oP 'phase\s*=\s*"\K[^"]+' .machine_readable/STATE.a2ml 2>/dev/null | head -1 || echo "unknown" + +# ═══════════════════════════════════════════════════════════════════════════════ +# GUIX & NIX +# ═══════════════════════════════════════════════════════════════════════════════ + +# Enter Guix development shell (primary) +guix-shell: + guix shell -D -f guix.scm + +# Build with Guix +guix-build: + guix build -f guix.scm + +# Enter Nix development shell (fallback) +nix-shell: + @if [ -f "flake.nix" ]; then nix develop; else echo "No flake.nix"; fi + +# ═══════════════════════════════════════════════════════════════════════════════ +# HYBRID AUTOMATION +# ═══════════════════════════════════════════════════════════════════════════════ + +# Run local automation tasks +automate task="all": + #!/usr/bin/env bash + case "{{task}}" in + all) just fmt && just lint && just test && just docs && just state-touch ;; + cleanup) just clean && find . -name "*.orig" -delete && find . -name "*~" -delete ;; + update) just deps && just validate ;; + *) echo "Unknown: {{task}}. Use: all, cleanup, update" && exit 1 ;; + esac + +# ═══════════════════════════════════════════════════════════════════════════════ +# COMBINATORIC MATRIX RECIPES +# ═══════════════════════════════════════════════════════════════════════════════ + +# Build matrix: [debug|release] x [target] x [features] +build-matrix mode="debug" target="" features="": + @echo "Build matrix: mode={{mode}} target={{target}} features={{features}}" + +# Test matrix: [unit|integration|e2e|all] x [verbosity] x [parallel] +test-matrix suite="unit" verbosity="normal" parallel="true": + @echo "Test matrix: suite={{suite}} verbosity={{verbosity}} parallel={{parallel}}" + +# Container matrix: [build|run|push|shell|scan] x [registry] x [tag] +container-matrix action="build" registry="ghcr.io/hyperpolymath" tag="latest": + @echo "Container matrix: action={{action}} registry={{registry}} tag={{tag}}" + +# CI matrix: [lint|test|build|security|all] x [quick|full] +ci-matrix stage="all" depth="quick": + @echo "CI matrix: stage={{stage}} depth={{depth}}" + +# Show all matrix combinations +combinations: + @echo "=== Combinatoric Matrix Recipes ===" + @echo "" + @echo "Build Matrix: just build-matrix [debug|release] [target] [features]" + @echo "Test Matrix: just test-matrix [unit|integration|e2e|all] [verbosity] [parallel]" + @echo "Container: just container-matrix [build|run|push|shell|scan] [registry] [tag]" + @echo "CI Matrix: just ci-matrix [lint|test|build|security|all] [quick|full]" + +# ═══════════════════════════════════════════════════════════════════════════════ +# VERSION CONTROL +# ═══════════════════════════════════════════════════════════════════════════════ + +# Show git status +status: + @git status --short + +# Show recent commits +log count="20": + @git log --oneline -{{count}} + +# Generate CHANGELOG.md with git-cliff +changelog: + @command -v git-cliff >/dev/null || { echo "git-cliff not found — install: cargo install git-cliff"; exit 1; } + git cliff --config .machine_readable/configs/git-cliff/cliff.toml --output CHANGELOG.md + @echo "Generated CHANGELOG.md" + +# Preview changelog for unreleased commits (does not write) +changelog-preview: + @command -v git-cliff >/dev/null || { echo "git-cliff not found — install: cargo install git-cliff"; exit 1; } + git cliff --config .machine_readable/configs/git-cliff/cliff.toml --unreleased --strip header + +# Tag a new release (usage: just release-tag 1.2.3) +release-tag version: + #!/usr/bin/env bash + TAG="v{{version}}" + if git rev-parse "$TAG" >/dev/null 2>&1; then + echo "Tag $TAG already exists" + exit 1 + fi + just changelog + git add CHANGELOG.md + git commit -m "chore(release): prepare $TAG" + git tag -a "$TAG" -m "Release $TAG" + echo "Created tag $TAG — push with: git push origin main --tags" + +# ═══════════════════════════════════════════════════════════════════════════════ +# UTILITIES +# ═══════════════════════════════════════════════════════════════════════════════ + +# Count lines of code +loc: + @find . \( -name "*.rs" -o -name "*.ex" -o -name "*.exs" -o -name "*.res" -o -name "*.gleam" -o -name "*.zig" -o -name "*.idr" -o -name "*.hs" -o -name "*.ncl" -o -name "*.scm" -o -name "*.adb" -o -name "*.ads" \) -not -path './target/*' -not -path './_build/*' 2>/dev/null | xargs wc -l 2>/dev/null | tail -1 || echo "0" + +# Show TODO comments +todos: + @grep -rn "TODO\|FIXME\|HACK\|XXX" --include="*.rs" --include="*.ex" --include="*.res" --include="*.gleam" --include="*.zig" --include="*.idr" --include="*.hs" . 2>/dev/null || echo "No TODOs" + +# Open in editor +edit: + ${EDITOR:-code} . + +# Run high-rigor security assault using panic-attacker +maint-assault: + @./.machine_readable/scripts/maintenance/maint-assault.sh + +# Run panic-attacker pre-commit scan +assail: + @command -v panic-attack >/dev/null 2>&1 && panic-attack assail . || echo "panic-attack not found — install from https://github.com/hyperpolymath/panic-attacker" + +# ═══════════════════════════════════════════════════════════════════════════════ +# ONBOARDING & DIAGNOSTICS +# ═══════════════════════════════════════════════════════════════════════════════ + +# Check all required toolchain dependencies and report health +doctor: + #!/usr/bin/env bash + echo "═══════════════════════════════════════════════════" + echo " A2Ml Validate Action Doctor — Toolchain Health Check" + echo "═══════════════════════════════════════════════════" + echo "" + PASS=0; FAIL=0; WARN=0 + check() { + local name="$1" cmd="$2" min="$3" + if command -v "$cmd" >/dev/null 2>&1; then + VER=$("$cmd" --version 2>&1 | head -1) + echo " [OK] $name — $VER" + PASS=$((PASS + 1)) + else + echo " [FAIL] $name — not found (need $min+)" + FAIL=$((FAIL + 1)) + fi + } + check "just" just "1.25" + check "git" git "2.40" +# Optional tools +if command -v panic-attack >/dev/null 2>&1; then + echo " [OK] panic-attack — available" + PASS=$((PASS + 1)) +else + echo " [WARN] panic-attack — not found (pre-commit scanner)" + WARN=$((WARN + 1)) +fi + echo "" + echo " Result: $PASS passed, $FAIL failed, $WARN warnings" + if [ "$FAIL" -gt 0 ]; then + echo " Run 'just heal' to attempt automatic repair." + exit 1 + fi + echo " All required tools present." + +# Attempt to automatically install missing tools +heal: + #!/usr/bin/env bash + echo "═══════════════════════════════════════════════════" + echo " A2Ml Validate Action Heal — Automatic Tool Installation" + echo "═══════════════════════════════════════════════════" + echo "" +if ! command -v just >/dev/null 2>&1; then + echo "Installing just..." + cargo install just 2>/dev/null || echo "Install just from https://just.systems" +fi + echo "" + echo "Heal complete. Run 'just doctor' to verify." + +# Guided tour of the project structure and key concepts +tour: + #!/usr/bin/env bash + echo "═══════════════════════════════════════════════════" + echo " A2Ml Validate Action — Guided Tour" + echo "═══════════════════════════════════════════════════" + echo "" + echo '**GitHub Action to validate A2ML manifest files in your repository.**' + echo "" + echo "Key directories:" + echo " src/ Source code" + echo " docs/ Documentation" + echo " tests/ Test suite" + echo " .github/workflows/ CI/CD workflows" + echo " .machine_readable/ Machine-readable metadata" + echo " container/ Container configuration" + echo " examples/ Usage examples" + echo "" + echo "Quick commands:" + echo " just doctor Check toolchain health" + echo " just heal Fix missing tools" + echo " just help-me Common workflows" + echo " just default List all recipes" + echo "" + echo "Read more: README.adoc, EXPLAINME.adoc" + +# Show help for common workflows +help-me: + #!/usr/bin/env bash + echo "═══════════════════════════════════════════════════" + echo " A2Ml Validate Action — Common Workflows" + echo "═══════════════════════════════════════════════════" + echo "" +echo "FIRST TIME SETUP:" +echo " just doctor Check toolchain" +echo " just heal Fix missing tools" +echo "" +echo "PRE-COMMIT:" +echo " just assail Run panic-attacker scan" +echo "" +echo "LEARN:" +echo " just tour Guided project tour" +echo " just default List all recipes" + + +# 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)" 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/README.adoc b/.machine_readable/contractiles/README.adoc index d40fcd1..2191594 100644 --- a/.machine_readable/contractiles/README.adoc +++ b/.machine_readable/contractiles/README.adoc @@ -1,3 +1,5 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Contractiles Template Set :toc: :sectnums: @@ -16,4 +18,4 @@ This directory contains the generalized contractiles templates. Copy the `.machi * `must/Mustfile` - required invariants and validations. * `trust/Trustfile.hs` - cryptographic verification steps. * `dust/Dustfile` - rollback and recovery semantics. -* `lust/Intentfile` - future intent and roadmap direction. +* `intend/Intentfile` - future intent and roadmap direction. 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/dust/Dustfile.a2ml b/.machine_readable/contractiles/dust/Dustfile.a2ml deleted file mode 100644 index be38a8c..0000000 --- a/.machine_readable/contractiles/dust/Dustfile.a2ml +++ /dev/null @@ -1,44 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Dustfile — Cleanup and hygiene contract -# Author: Jonathan D.A. Jewell - -@abstract: -What should be cleaned up or removed from this repository. -These are housekeeping items, not blockers. -@end - -## Stale Files - -### no-stale-snapshots -- description: No dated status/completion files in root -- run: "! ls *-STATUS-*.md *-COMPLETION-*.md *-COMPLETE.md *-VERIFIED-*.md 2>/dev/null | head -1 | grep -q ." -- severity: info - -### no-ai-djot -- description: AI.djot is superseded by 0-AI-MANIFEST.a2ml -- run: test ! -f AI.djot -- severity: warning - -### no-next-steps -- description: NEXT_STEPS.md superseded by ROADMAP -- run: test ! -f NEXT_STEPS.md -- severity: info - -## Build Artifacts - -### no-tracked-artifacts -- description: No build artifacts tracked in git -- run: "! git ls-files lib/bs/ lib/ocaml/ target/release/ _build/ 2>/dev/null | head -1 | grep -q ." -- severity: warning - -## Format Duplicates - -### no-duplicate-contributing -- description: Only one CONTRIBUTING format (keep .md) -- run: "! (test -f CONTRIBUTING.md && test -f CONTRIBUTING.adoc)" -- severity: warning - -### no-duplicate-readme -- description: Only one README format -- run: "! (test -f README.md && test -f README.adoc && [ $(wc -l < README.md) -gt 5 ])" -- severity: warning diff --git a/.machine_readable/contractiles/lust/Intentfile.a2ml b/.machine_readable/contractiles/lust/Intentfile.a2ml deleted file mode 100644 index f75d38e..0000000 --- a/.machine_readable/contractiles/lust/Intentfile.a2ml +++ /dev/null @@ -1,37 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Intentfile — Design intent and aspirations -# Author: Jonathan D.A. Jewell - -@abstract: -What this repository INTENDS to become. Aspirational goals and -design philosophy — not current state, but target state. -@end - -## Architecture Intent - -### formal-verification -- description: All critical code paths should have formal proofs -- target: Idris2 dependent types for ABI, Coq/Lean for algorithms -- status: aspiration - -### reproducible-builds -- description: Builds should be bit-for-bit reproducible -- target: Guix + Nix + Containerfile -- status: aspiration - -### zero-dangerous-patterns -- description: No believe_me, sorry, Admitted, unsafeCoerce in any code -- target: All proofs completed, no escape hatches -- status: in-progress - -## Quality Intent - -### comprehensive-testing -- description: 80%+ code coverage with meaningful tests -- target: Unit + integration + conformance + property-based -- status: aspiration - -### documentation-complete -- description: Every public API documented, every directory has README -- target: Full API reference + architecture guide -- status: in-progress diff --git a/.machine_readable/contractiles/must/Mustfile.a2ml b/.machine_readable/contractiles/must/Mustfile.a2ml deleted file mode 100644 index 215c510..0000000 --- a/.machine_readable/contractiles/must/Mustfile.a2ml +++ /dev/null @@ -1,69 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Mustfile — Physical state contract -# Author: Jonathan D.A. Jewell - -@abstract: -What MUST be true about this repository's files and configuration. -These are hard requirements — CI fails 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 or README.md must exist -- run: test -f README.adoc || test -f README.md -- 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 - -### contributing -- description: CONTRIBUTING.md must exist (GitHub community health) -- run: test -f CONTRIBUTING.md -- severity: warning - -### editorconfig -- description: .editorconfig must exist -- run: test -f .editorconfig -- severity: warning - -## SPDX Compliance - -### spdx-headers -- description: All source files must have SPDX-License-Identifier -- run: "! find src/ -name '*.rs' -o -name '*.res' -o -name '*.idr' -o -name '*.zig' 2>/dev/null | head -20 | xargs grep -L 'SPDX-License-Identifier' 2>/dev/null | head -1 | grep -q ." -- severity: warning - -### no-agpl -- description: No AGPL-3.0 references in dotfiles -- run: "! grep -r 'AGPL-3.0' .gitignore .gitattributes .editorconfig 2>/dev/null | head -1 | grep -q ." -- severity: critical - -## Dangerous Patterns - -### no-believe-me -- description: No believe_me in Idris2 code -- run: "! grep -r 'believe_me' --include='*.idr' . 2>/dev/null | grep -v node_modules | head -1 | grep -q ." -- severity: critical - -### no-sorry -- description: No sorry in Lean code -- run: "! grep -r 'sorry' --include='*.lean' . 2>/dev/null | grep -v node_modules | head -1 | grep -q ." -- severity: critical - -### no-admitted -- description: No Admitted in Coq code -- run: "! grep -r 'Admitted' --include='*.v' . 2>/dev/null | grep -v node_modules | head -1 | grep -q ." -- severity: critical diff --git a/.machine_readable/contractiles/k9/README.adoc b/.machine_readable/contractiles/self-validating/README.adoc similarity index 88% rename from .machine_readable/contractiles/k9/README.adoc rename to .machine_readable/contractiles/self-validating/README.adoc index eeb1229..9e259b1 100644 --- a/.machine_readable/contractiles/k9/README.adoc +++ b/.machine_readable/contractiles/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 @@ -71,13 +72,13 @@ Choose the appropriate security level for your use case: [source,bash] ---- # Kennel: Pure configuration -cp .machine_readable/contractiles/k9/examples/project-metadata.k9.ncl config/metadata.k9.ncl +cp .machine_readable/contractiles/self-validating/examples/project-metadata.k9.ncl config/metadata.k9.ncl # Yard: Validated configuration -cp .machine_readable/contractiles/k9/examples/ci-config.k9.ncl .github/ci.k9.ncl +cp .machine_readable/contractiles/self-validating/examples/ci-config.k9.ncl .github/ci.k9.ncl # Hunt: Full automation -cp .machine_readable/contractiles/k9/examples/setup-repo.k9.ncl scripts/setup.k9.ncl +cp .machine_readable/contractiles/self-validating/examples/setup-repo.k9.ncl scripts/setup.k9.ncl ---- === 2. Validate Components @@ -130,7 +131,7 @@ K9 contractiles integrate with other RSR standards: ⚠️ **Never run as root unless required** + ⚠️ **Sandbox external components** -**See:** https://github.com/hyperpolymath/standards/blob/main/k9-svc/docs/SECURITY-BEST-PRACTICES.adoc +**See:** https://github.com/hyperpolymath/standards/blob/main/self-validating/docs/SECURITY-BEST-PRACTICES.adoc == Template Files @@ -160,9 +161,9 @@ git clone https://github.com/hyperpolymath/standards.git == Learn More -- **K9-SVC Specification:** https://github.com/hyperpolymath/standards/blob/main/k9-svc/SPEC.adoc -- **K9 User Guide:** https://github.com/hyperpolymath/standards/blob/main/k9-svc/GUIDE.adoc -- **Security Documentation:** https://github.com/hyperpolymath/standards/blob/main/k9-svc/docs/SECURITY-FAQ.adoc +- **K9-SVC Specification:** https://github.com/hyperpolymath/standards/blob/main/self-validating/SPEC.adoc +- **K9 User Guide:** https://github.com/hyperpolymath/standards/blob/main/self-validating/GUIDE.adoc +- **Security Documentation:** https://github.com/hyperpolymath/standards/blob/main/self-validating/docs/SECURITY-FAQ.adoc - **IANA Media Type:** `application/vnd.k9+nickel` == Contributing diff --git a/.machine_readable/contractiles/k9/examples/ci-config.k9.ncl b/.machine_readable/contractiles/self-validating/examples/ci-config.k9.ncl similarity index 100% rename from .machine_readable/contractiles/k9/examples/ci-config.k9.ncl rename to .machine_readable/contractiles/self-validating/examples/ci-config.k9.ncl diff --git a/.machine_readable/contractiles/k9/examples/project-metadata.k9.ncl b/.machine_readable/contractiles/self-validating/examples/project-metadata.k9.ncl similarity index 100% rename from .machine_readable/contractiles/k9/examples/project-metadata.k9.ncl rename to .machine_readable/contractiles/self-validating/examples/project-metadata.k9.ncl diff --git a/.machine_readable/contractiles/k9/examples/setup-repo.k9.ncl b/.machine_readable/contractiles/self-validating/examples/setup-repo.k9.ncl similarity index 98% rename from .machine_readable/contractiles/k9/examples/setup-repo.k9.ncl rename to .machine_readable/contractiles/self-validating/examples/setup-repo.k9.ncl index d1fc8bb..c05a160 100644 --- a/.machine_readable/contractiles/k9/examples/setup-repo.k9.ncl +++ b/.machine_readable/contractiles/self-validating/examples/setup-repo.k9.ncl @@ -95,7 +95,7 @@ K9! commands = [ "mkdir -p src/ docs/ tests/ scripts/", "mkdir -p .github/workflows/", - "mkdir -p .machine_readable/contractiles/k9/", + "mkdir -p .machine_readable/contractiles/self-validating/", "echo '✓ Directory structure created'", ], }, diff --git a/.machine_readable/contractiles/k9/template-hunt.k9.ncl b/.machine_readable/contractiles/self-validating/template-hunt.k9.ncl similarity index 100% rename from .machine_readable/contractiles/k9/template-hunt.k9.ncl rename to .machine_readable/contractiles/self-validating/template-hunt.k9.ncl diff --git a/.machine_readable/contractiles/k9/template-kennel.k9.ncl b/.machine_readable/contractiles/self-validating/template-kennel.k9.ncl similarity index 100% rename from .machine_readable/contractiles/k9/template-kennel.k9.ncl rename to .machine_readable/contractiles/self-validating/template-kennel.k9.ncl diff --git a/.machine_readable/contractiles/k9/template-yard.k9.ncl b/.machine_readable/contractiles/self-validating/template-yard.k9.ncl similarity index 100% rename from .machine_readable/contractiles/k9/template-yard.k9.ncl rename to .machine_readable/contractiles/self-validating/template-yard.k9.ncl diff --git a/.machine_readable/contractiles/trust/Trustfile.a2ml b/.machine_readable/contractiles/trust/Trustfile.a2ml deleted file mode 100644 index f2a4f95..0000000 --- a/.machine_readable/contractiles/trust/Trustfile.a2ml +++ /dev/null @@ -1,50 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Trustfile — Integrity and provenance verification -# Author: Jonathan D.A. Jewell - -@abstract: -Integrity invariants for this repository. These verify that the repo -has not been tampered with, secrets are not leaked, and provenance -is traceable. -@end - -## 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 - -## 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/policies/README.adoc b/.machine_readable/policies/README.adoc index b7e25f5..045e5af 100644 --- a/.machine_readable/policies/README.adoc +++ b/.machine_readable/policies/README.adoc @@ -1 +1,3 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = policies Registry diff --git a/.machine_readable/scripts/forge/README.adoc b/.machine_readable/scripts/forge/README.adoc index 31adef6..a43f1d2 100644 --- a/.machine_readable/scripts/forge/README.adoc +++ b/.machine_readable/scripts/forge/README.adoc @@ -1 +1,3 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Forge Scripts diff --git a/.machine_readable/scripts/lifecycle/README.adoc b/.machine_readable/scripts/lifecycle/README.adoc index 8d262b1..481283e 100644 --- a/.machine_readable/scripts/lifecycle/README.adoc +++ b/.machine_readable/scripts/lifecycle/README.adoc @@ -1 +1,3 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Lifecycle Scripts diff --git a/.machine_readable/scripts/verification/README.adoc b/.machine_readable/scripts/verification/README.adoc index 277b4aa..19fcf01 100644 --- a/.machine_readable/scripts/verification/README.adoc +++ b/.machine_readable/scripts/verification/README.adoc @@ -1 +1,3 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Verification Scripts diff --git a/0-AI-MANIFEST.a2ml b/0-AI-MANIFEST.a2ml index 6f34620..3841f46 100644 --- a/0-AI-MANIFEST.a2ml +++ b/0-AI-MANIFEST.a2ml @@ -50,7 +50,7 @@ Bot-specific instructions for your automated agents. ### Contractiles: `.machine_readable/contractiles/` ONLY -Policy enforcement contracts (k9, dust, lust, must, trust). +Policy enforcement contracts (k9, dust, intend, must, trust). ### AI Configuration & Guides: `.machine_readable/ai/` ONLY diff --git a/CHANGELOG.md b/CHANGELOG.md index 8109476..66fa7a0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,7 @@ + # Changelog All notable changes to this project will be documented in this file. diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 1f1548c..9020def 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -1,4 +1,7 @@ - + # Contributor Covenant Code of Conduct ## Our Pledge diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a7e0669..3016867 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,4 +1,7 @@ - + # Contributing Thank you for your interest in contributing! We follow a "Dual-Track" architecture where human-readable documentation lives in the root and machine-readable policies live in `.machine_readable/`. diff --git a/EXPLAINME.adoc b/EXPLAINME.adoc index 669bfd0..2b8eeb5 100644 --- a/EXPLAINME.adoc +++ b/EXPLAINME.adoc @@ -1,4 +1,5 @@ // SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = a2ml-validate-action — Show Me The Receipts :toc: :icons: font 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/MAINTAINERS.adoc b/MAINTAINERS.adoc new file mode 100644 index 0000000..9910dd8 --- /dev/null +++ b/MAINTAINERS.adoc @@ -0,0 +1,65 @@ +// SPDX-License-Identifier: MPL-2.0 +// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell += Maintainers +:toc: preamble + +== Current Maintainers + +[cols="2,3,2",options="header"] +|=== +| Name | Role | Contact + +| Jonathan D.A. Jewell | Sole Maintainer | https://github.com/hyperpolymath[@hyperpolymath] +|=== + +== Maintainer Responsibilities + +As the sole maintainer, all responsibilities apply to @hyperpolymath: + +* Reviewing and merging pull requests +* Triaging issues and feature requests +* Ensuring code quality and security standards +* Managing releases and versioning +* Upholding the project's Code of Conduct +* Maintaining documentation and examples +* Responding to security vulnerabilities + +== Contribution Process + +This is a sole-maintainer project. All contributions are welcome via: + +1. **Issues**: Report bugs, request features, ask questions +2. **Pull Requests**: Submit improvements for review +3. **Discussions**: Engage in community discussions + +All contributions will be reviewed by the maintainer. + +== Decision Making + +* Routine decisions (bug fixes, minor improvements): Made by maintainer +* Significant changes: Discussed in issues before implementation +* Breaking changes: Announced in advance with migration path + +== Becoming a Maintainer + +This project currently has a single maintainer. If you're interested in becoming a co-maintainer: + +1. Demonstrate consistent, high-quality contributions +2. Show understanding of project goals and standards +3. Participate constructively in discussions +4. Express interest to the current maintainer + +Co-maintainers may be added at the discretion of the current maintainer. + +== Contact + +For questions about project governance: + +* Open a GitHub issue in this repository +* Contact: https://github.com/hyperpolymath + +== See Also + +* link:GOVERNANCE.adoc[Governance Model] +* link:CODE_OF_CONDUCT.md[Code of Conduct] +* link:CONTRIBUTING.adoc[Contributing Guide] diff --git a/PROOF-NEEDS.md b/PROOF-NEEDS.md index 8950320..566ed20 100644 --- a/PROOF-NEEDS.md +++ b/PROOF-NEEDS.md @@ -1,3 +1,7 @@ + # PROOF-NEEDS.md ## Template ABI Cleanup (2026-03-29) diff --git a/QUICKSTART-DEV.adoc b/QUICKSTART-DEV.adoc index c0e28c0..543570e 100644 --- a/QUICKSTART-DEV.adoc +++ b/QUICKSTART-DEV.adoc @@ -1,3 +1,5 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = A2Ml Validate Action — Developer Quickstart :toc: preamble diff --git a/QUICKSTART-MAINTAINER.adoc b/QUICKSTART-MAINTAINER.adoc index 432d638..733eb28 100644 --- a/QUICKSTART-MAINTAINER.adoc +++ b/QUICKSTART-MAINTAINER.adoc @@ -1,3 +1,5 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = A2Ml Validate Action — Maintainer Quickstart :toc: preamble diff --git a/QUICKSTART-USER.adoc b/QUICKSTART-USER.adoc index 713115d..7276a60 100644 --- a/QUICKSTART-USER.adoc +++ b/QUICKSTART-USER.adoc @@ -1,3 +1,5 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = A2Ml Validate Action — User Quickstart :toc: preamble diff --git a/README.adoc b/README.adoc index f0cd48e..0eeecfd 100644 --- a/README.adoc +++ b/README.adoc @@ -1,4 +1,8 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = a2ml-validate-action +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/a2ml-validate-action"] + :toc: preamble :icons: font diff --git a/ROADMAP.adoc b/ROADMAP.adoc index 46a5657..8788d99 100644 --- a/ROADMAP.adoc +++ b/ROADMAP.adoc @@ -1,4 +1,5 @@ // SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = A2ml Validate Action Roadmap == Current Status diff --git a/SECURITY.md b/SECURITY.md index 1a29117..88df5ba 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,4 +1,7 @@ - + # Security Policy ## Reporting a Vulnerability diff --git a/TEST-NEEDS.md b/TEST-NEEDS.md index c4da123..9440284 100644 --- a/TEST-NEEDS.md +++ b/TEST-NEEDS.md @@ -1,3 +1,7 @@ + # TEST-NEEDS.md — a2ml-validate-action ## CRG Grade: C — ACHIEVED 2026-04-04 diff --git a/TOPOLOGY.md b/TOPOLOGY.md index 1cec016..dfbf406 100644 --- a/TOPOLOGY.md +++ b/TOPOLOGY.md @@ -1,4 +1,7 @@ - + # TOPOLOGY.md — a2ml-validate-action diff --git a/container/README.adoc b/container/README.adoc index ed903f3..5751b66 100644 --- a/container/README.adoc +++ b/container/README.adoc @@ -1,5 +1,5 @@ // SPDX-License-Identifier: MPL-2.0 -// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +// Copyright (c) Jonathan D.A. Jewell = a2ml-validate-action Container Templates :toc: left :toclevels: 3 diff --git a/contractiles/intend/Intentfile.a2ml b/contractiles/intend/Intentfile.a2ml deleted file mode 100644 index 4937e3b..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 A2Ml Validate Action. -@end - -## Purpose - -A2Ml Validate Action — **GitHub Action to validate A2ML manifest files in your repository.** - -## 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.a2ml b/contractiles/must/Mustfile.a2ml deleted file mode 100644 index 39ebbb6..0000000 --- a/contractiles/must/Mustfile.a2ml +++ /dev/null @@ -1,42 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Mustfile (A2ML Canonical) -# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) - -@abstract: -Physical State contract for A2Ml Validate Action. Baseline UX Manifesto invariants -that MUST hold at all times. -@end - -@requires: -- section: Core-Files -- section: Banned -@end - -## Core-Files - -### license-present -- description: LICENSE file must exist -- run: test -f LICENSE -- severity: critical - -### readme-present -- description: README must exist -- run: test -f README.adoc || test -f README.md -- severity: critical - -## Banned - -### no-hardcoded-paths -- description: No hardcoded developer paths -- run: "! grep -rn '$HOME\|$ECLIPSE_DIR' --include='*.rs' --include='*.res' --include='*.ex' --include='*.gleam' --include='*.zig' --include='*.sh' . 2>/dev/null | grep -v '.git/' | grep -v 'ux-rollout.jl' | head -1" -- severity: critical - -### no-dockerfiles -- description: No Dockerfiles (use Containerfile) -- run: test ! -f Dockerfile -- severity: warning - -### no-makefiles -- description: No Makefiles (use Justfile) -- run: test ! -f Makefile -- severity: warning diff --git a/contractiles/trust/Trustfile.a2ml b/contractiles/trust/Trustfile.a2ml deleted file mode 100644 index 7fafe08..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 A2Ml Validate Action. -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/docs/QUICKSTART.adoc b/docs/QUICKSTART.adoc index b20b3d0..013bf34 100644 --- a/docs/QUICKSTART.adoc +++ b/docs/QUICKSTART.adoc @@ -1,3 +1,5 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Quickstart :toc: preamble diff --git a/docs/README.adoc b/docs/README.adoc index df45be7..adf6a02 100644 --- a/docs/README.adoc +++ b/docs/README.adoc @@ -1,3 +1,5 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Documentation Layout Primary tracks: diff --git a/docs/RSR_OUTLINE.adoc b/docs/RSR_OUTLINE.adoc index e07a65e..455934f 100644 --- a/docs/RSR_OUTLINE.adoc +++ b/docs/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"] @@ -169,7 +171,7 @@ project/ │ └── contractiles/ # Policy enforcement contracts │ ├── k9/ # Security levels (Kennel/Yard/Hunt) │ ├── dust/Dustfile # Recovery and rollback -│ ├── lust/Intentfile # Future intent declarations +│ ├── intend/Intentfile # Future intent declarations │ ├── must/Mustfile # Invariant checks │ └── trust/Trustfile.hs # Cryptographic verification ├── docs/ # Documentation diff --git a/docs/STATE-VISUALIZER.adoc b/docs/STATE-VISUALIZER.adoc index 422fcd5..77c0248 100644 --- a/docs/STATE-VISUALIZER.adoc +++ b/docs/STATE-VISUALIZER.adoc @@ -1,3 +1,5 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Project State Visualizer [source] ---- diff --git a/docs/architecture/THREAT-MODEL.adoc b/docs/architecture/THREAT-MODEL.adoc index 5b8caf2..c841c30 100644 --- a/docs/architecture/THREAT-MODEL.adoc +++ b/docs/architecture/THREAT-MODEL.adoc @@ -1,3 +1,5 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Threat Model diff --git a/docs/attribution/CITATIONS.adoc b/docs/attribution/CITATIONS.adoc index 3255714..2ad82b0 100644 --- a/docs/attribution/CITATIONS.adoc +++ b/docs/attribution/CITATIONS.adoc @@ -1,3 +1,5 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = a2ml-validate-action - Citation Guide :toc: diff --git a/docs/attribution/CODEOWNERS.adoc b/docs/attribution/CODEOWNERS.adoc index 3714055..668df01 100644 --- a/docs/attribution/CODEOWNERS.adoc +++ b/docs/attribution/CODEOWNERS.adoc @@ -1,3 +1,5 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Code Ownership :icons: font diff --git a/docs/attribution/MAINTAINERS.adoc b/docs/attribution/MAINTAINERS.adoc index a1c6544..becaa3e 100644 --- a/docs/attribution/MAINTAINERS.adoc +++ b/docs/attribution/MAINTAINERS.adoc @@ -1,4 +1,5 @@ // SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Maintainers :toc: preamble diff --git a/docs/attribution/README.adoc b/docs/attribution/README.adoc index b095612..2e50721 100644 --- a/docs/attribution/README.adoc +++ b/docs/attribution/README.adoc @@ -1 +1,3 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = attribution Unit diff --git a/docs/decisions/0000-template.adoc b/docs/decisions/0000-template.adoc index b1a561f..825ea4a 100644 --- a/docs/decisions/0000-template.adoc +++ b/docs/decisions/0000-template.adoc @@ -1,3 +1,5 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Architecture Decision Record: 0000-template diff --git a/docs/decisions/0001-adopt-rsr-standard.adoc b/docs/decisions/0001-adopt-rsr-standard.adoc index 7e54838..7a56065 100644 --- a/docs/decisions/0001-adopt-rsr-standard.adoc +++ b/docs/decisions/0001-adopt-rsr-standard.adoc @@ -1,3 +1,5 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Architecture Decision Record: 0001-adopt-rsr-standard @@ -40,7 +42,7 @@ The RSR template provides: - **AI manifest** (`0-AI-MANIFEST.a2ml`) as a universal entry point for all AI agents - **Bot directives** in `.machine_readable/bot_directives/` for bot orchestration integration -- **Contractiles** in `.machine_readable/contractiles/` (k9, dust, lust, must, trust) for +- **Contractiles** in `.machine_readable/contractiles/` (k9, dust, intend, must, trust) for policy enforcement - **Standardized workflows** (16+ GitHub Actions workflows, all SHA-pinned) - **Justfile automation** with standard recipes for common tasks diff --git a/docs/decisions/README.adoc b/docs/decisions/README.adoc index 153a5e7..af174f5 100644 --- a/docs/decisions/README.adoc +++ b/docs/decisions/README.adoc @@ -1 +1,3 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = decisions Unit diff --git a/docs/developer/ABI-FFI-README.adoc b/docs/developer/ABI-FFI-README.adoc index 59b32dd..000f1cc 100644 --- a/docs/developer/ABI-FFI-README.adoc +++ b/docs/developer/ABI-FFI-README.adoc @@ -1,3 +1,5 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = ABI/FFI Standards {{~ Aditionally delete this line and fill out the template below ~}} diff --git a/docs/developer/README.adoc b/docs/developer/README.adoc index 1d00529..2b328b4 100644 --- a/docs/developer/README.adoc +++ b/docs/developer/README.adoc @@ -1 +1,3 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = developer Unit diff --git a/docs/governance/CRG-CRITERIA.adoc b/docs/governance/CRG-CRITERIA.adoc index f8264e6..926df5a 100644 --- a/docs/governance/CRG-CRITERIA.adoc +++ b/docs/governance/CRG-CRITERIA.adoc @@ -1,3 +1,5 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Component Readiness Grades (CRG) Criteria :toc: preamble :icons: font diff --git a/docs/governance/MAINTENANCE-CHECKLIST.adoc b/docs/governance/MAINTENANCE-CHECKLIST.adoc index 0b40654..f331f25 100644 --- a/docs/governance/MAINTENANCE-CHECKLIST.adoc +++ b/docs/governance/MAINTENANCE-CHECKLIST.adoc @@ -1,3 +1,5 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Maintenance Checklist # Maintenance Checklist (Cross-Repo) @@ -91,7 +93,7 @@ Run this pass at the end of a corrective/adaptive/perfective cycle: - [ ] Keep machine-readable canonical structure under `.machine_readable/`: - state/meta/ecosystem files (`*.a2ml` or repo standard) - `anchors/ANCHOR.a2ml` - - `contractiles/` (`must`, `trust`, `lust`, and related) + - `contractiles/` (`must`, `trust`, `intend`, and related) - `ai/` for AI guidance files - `bot_directives/` for bot control files - [ ] Keep contractiles/invariants present and wired: diff --git a/docs/governance/README.adoc b/docs/governance/README.adoc index 114ee94..48cac0d 100644 --- a/docs/governance/README.adoc +++ b/docs/governance/README.adoc @@ -1 +1,3 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Governance Pillar (TSDM) diff --git a/docs/governance/SOFTWARE-DEVELOPMENT-APPROACH.adoc b/docs/governance/SOFTWARE-DEVELOPMENT-APPROACH.adoc index e8805c6..2bfa0ff 100644 --- a/docs/governance/SOFTWARE-DEVELOPMENT-APPROACH.adoc +++ b/docs/governance/SOFTWARE-DEVELOPMENT-APPROACH.adoc @@ -1,3 +1,5 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Software Development Approach (General) :toc: left :toclevels: 2 diff --git a/docs/governance/TSDM.adoc b/docs/governance/TSDM.adoc index cbd582c..6bf4ee8 100644 --- a/docs/governance/TSDM.adoc +++ b/docs/governance/TSDM.adoc @@ -1,3 +1,5 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Triaxial Software Development Methodology (TSDM) :toc: preamble :icons: font diff --git a/docs/governance/audit/README.adoc b/docs/governance/audit/README.adoc index fac3740..02aff13 100644 --- a/docs/governance/audit/README.adoc +++ b/docs/governance/audit/README.adoc @@ -1 +1,3 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Audit Axis diff --git a/docs/governance/audit/compliance/README.adoc b/docs/governance/audit/compliance/README.adoc index 876954f..9948dbc 100644 --- a/docs/governance/audit/compliance/README.adoc +++ b/docs/governance/audit/compliance/README.adoc @@ -1 +1,3 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Compliance Unit diff --git a/docs/governance/audit/effects/README.adoc b/docs/governance/audit/effects/README.adoc index 3634799..e5620ee 100644 --- a/docs/governance/audit/effects/README.adoc +++ b/docs/governance/audit/effects/README.adoc @@ -1 +1,3 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Effects Unit diff --git a/docs/governance/audit/systems/README.adoc b/docs/governance/audit/systems/README.adoc index 8d179b4..00a67de 100644 --- a/docs/governance/audit/systems/README.adoc +++ b/docs/governance/audit/systems/README.adoc @@ -1 +1,3 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Systems Unit diff --git a/docs/governance/maintenance/README.adoc b/docs/governance/maintenance/README.adoc index 0ed2f1b..7083a83 100644 --- a/docs/governance/maintenance/README.adoc +++ b/docs/governance/maintenance/README.adoc @@ -1 +1,3 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Maintenance Axis diff --git a/docs/governance/maintenance/adaptive/README.adoc b/docs/governance/maintenance/adaptive/README.adoc index 7b60992..72d0381 100644 --- a/docs/governance/maintenance/adaptive/README.adoc +++ b/docs/governance/maintenance/adaptive/README.adoc @@ -1 +1,3 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Adaptive Unit diff --git a/docs/governance/maintenance/corrective/README.adoc b/docs/governance/maintenance/corrective/README.adoc index ed904a8..9a0ed5d 100644 --- a/docs/governance/maintenance/corrective/README.adoc +++ b/docs/governance/maintenance/corrective/README.adoc @@ -1 +1,3 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Corrective Unit diff --git a/docs/governance/maintenance/perfective/README.adoc b/docs/governance/maintenance/perfective/README.adoc index 8759d74..12e3d14 100644 --- a/docs/governance/maintenance/perfective/README.adoc +++ b/docs/governance/maintenance/perfective/README.adoc @@ -1 +1,3 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Perfective Unit diff --git a/docs/governance/planning/README.adoc b/docs/governance/planning/README.adoc index 62aa375..2694fe9 100644 --- a/docs/governance/planning/README.adoc +++ b/docs/governance/planning/README.adoc @@ -1 +1,3 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Planning Axis diff --git a/docs/governance/planning/could/README.adoc b/docs/governance/planning/could/README.adoc index ad5a6b8..acc41ce 100644 --- a/docs/governance/planning/could/README.adoc +++ b/docs/governance/planning/could/README.adoc @@ -1 +1,3 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Could Unit diff --git a/docs/governance/planning/must/README.adoc b/docs/governance/planning/must/README.adoc index 47eb46d..5759550 100644 --- a/docs/governance/planning/must/README.adoc +++ b/docs/governance/planning/must/README.adoc @@ -1 +1,3 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Must Unit diff --git a/docs/governance/planning/should/README.adoc b/docs/governance/planning/should/README.adoc index 605489c..a00f585 100644 --- a/docs/governance/planning/should/README.adoc +++ b/docs/governance/planning/should/README.adoc @@ -1 +1,3 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Should Unit diff --git a/docs/practice/AI-CONVENTIONS.adoc b/docs/practice/AI-CONVENTIONS.adoc index 787b9d8..5e8e785 100644 --- a/docs/practice/AI-CONVENTIONS.adoc +++ b/docs/practice/AI-CONVENTIONS.adoc @@ -1,3 +1,5 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = AI Conventions diff --git a/docs/practice/README.adoc b/docs/practice/README.adoc index ae3326b..caceb5c 100644 --- a/docs/practice/README.adoc +++ b/docs/practice/README.adoc @@ -1 +1,3 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = practice Unit diff --git a/docs/practice/STATE-VISUALIZER-GUIDE.adoc b/docs/practice/STATE-VISUALIZER-GUIDE.adoc index c2490ca..6e97d92 100644 --- a/docs/practice/STATE-VISUALIZER-GUIDE.adoc +++ b/docs/practice/STATE-VISUALIZER-GUIDE.adoc @@ -1,4 +1,5 @@ // SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = TOPOLOGY.md — Generation Guide Jonathan D.A. Jewell (hyperpolymath) :toc: diff --git a/docs/reports/README.adoc b/docs/reports/README.adoc index 0c06c31..e91d79e 100644 --- a/docs/reports/README.adoc +++ b/docs/reports/README.adoc @@ -1 +1,3 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = reports Unit diff --git a/docs/reports/compliance/README.adoc b/docs/reports/compliance/README.adoc index c38c66a..1f6b885 100644 --- a/docs/reports/compliance/README.adoc +++ b/docs/reports/compliance/README.adoc @@ -1 +1,3 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Compliance Reports diff --git a/docs/reports/maintenance/README.adoc b/docs/reports/maintenance/README.adoc index f13abf7..82f845e 100644 --- a/docs/reports/maintenance/README.adoc +++ b/docs/reports/maintenance/README.adoc @@ -1 +1,3 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Maintenance Reports diff --git a/docs/reports/performance/README.adoc b/docs/reports/performance/README.adoc index 037767d..6473ed3 100644 --- a/docs/reports/performance/README.adoc +++ b/docs/reports/performance/README.adoc @@ -1 +1,3 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Performance Reports diff --git a/docs/reports/quality/README.adoc b/docs/reports/quality/README.adoc index d1be848..dbdb3ba 100644 --- a/docs/reports/quality/README.adoc +++ b/docs/reports/quality/README.adoc @@ -1 +1,3 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Quality Reports diff --git a/docs/reports/security/README.adoc b/docs/reports/security/README.adoc index 9a78a8b..76656cc 100644 --- a/docs/reports/security/README.adoc +++ b/docs/reports/security/README.adoc @@ -1 +1,3 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Security Reports diff --git a/docs/standards/README.adoc b/docs/standards/README.adoc index 34a94c4..41f7a31 100644 --- a/docs/standards/README.adoc +++ b/docs/standards/README.adoc @@ -1 +1,3 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Standards Unit diff --git a/docs/templates/contractiles/README.adoc b/docs/templates/contractiles/README.adoc index 121da7a..c544de6 100644 --- a/docs/templates/contractiles/README.adoc +++ b/docs/templates/contractiles/README.adoc @@ -1,4 +1,5 @@ // SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Contractile Templates Blank templates for projects that want to replace the hyperpolymath diff --git a/docs/templates/contractiles/lust/Intentfile.a2ml b/docs/templates/contractiles/intend/Intentfile.a2ml similarity index 79% rename from docs/templates/contractiles/lust/Intentfile.a2ml rename to docs/templates/contractiles/intend/Intentfile.a2ml index e313a7d..98d8956 100644 --- a/docs/templates/contractiles/lust/Intentfile.a2ml +++ b/docs/templates/contractiles/intend/Intentfile.a2ml @@ -3,7 +3,7 @@ # Replace this with your project's contractile. # See .machine_readable/contractiles/ for a working example. # -# Copy this file to .machine_readable/contractiles/lust/Intentfile.a2ml +# Copy this file to .machine_readable/contractiles/intend/Intentfile.a2ml # and fill in your project-specific checks. @abstract: diff --git a/docs/theory/README.adoc b/docs/theory/README.adoc index c0ddf28..b2658b1 100644 --- a/docs/theory/README.adoc +++ b/docs/theory/README.adoc @@ -1 +1,3 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = theory Unit diff --git a/docs/theory/computing/README.adoc b/docs/theory/computing/README.adoc index 4d0db25..aec951f 100644 --- a/docs/theory/computing/README.adoc +++ b/docs/theory/computing/README.adoc @@ -1 +1,3 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Computing Theory diff --git a/docs/theory/formalisms/README.adoc b/docs/theory/formalisms/README.adoc index 5d064c3..288a410 100644 --- a/docs/theory/formalisms/README.adoc +++ b/docs/theory/formalisms/README.adoc @@ -1 +1,3 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Formalisms Theory diff --git a/docs/theory/mathematics/README.adoc b/docs/theory/mathematics/README.adoc index 356236f..c9b223d 100644 --- a/docs/theory/mathematics/README.adoc +++ b/docs/theory/mathematics/README.adoc @@ -1 +1,3 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Mathematics Theory diff --git a/docs/theory/ontologies/README.adoc b/docs/theory/ontologies/README.adoc index 6d16ecf..9267ab0 100644 --- a/docs/theory/ontologies/README.adoc +++ b/docs/theory/ontologies/README.adoc @@ -1 +1,3 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Ontologies Theory diff --git a/docs/theory/other/README.adoc b/docs/theory/other/README.adoc index 1861d6d..0ec8432 100644 --- a/docs/theory/other/README.adoc +++ b/docs/theory/other/README.adoc @@ -1 +1,3 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Other Theory diff --git a/docs/theory/socio-technical/README.adoc b/docs/theory/socio-technical/README.adoc index 9ab4ee0..5c3c819 100644 --- a/docs/theory/socio-technical/README.adoc +++ b/docs/theory/socio-technical/README.adoc @@ -1 +1,3 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Socio technical Theory diff --git a/docs/whitepapers/README.adoc b/docs/whitepapers/README.adoc index 88e83c5..1ee0309 100644 --- a/docs/whitepapers/README.adoc +++ b/docs/whitepapers/README.adoc @@ -1 +1,3 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = whitepapers Unit diff --git a/docs/whitepapers/academic/README.adoc b/docs/whitepapers/academic/README.adoc index 16c3f45..d6dc7a0 100644 --- a/docs/whitepapers/academic/README.adoc +++ b/docs/whitepapers/academic/README.adoc @@ -1 +1,3 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Academic Logic diff --git a/docs/whitepapers/industry/README.adoc b/docs/whitepapers/industry/README.adoc index 7bc7fcd..2f795b7 100644 --- a/docs/whitepapers/industry/README.adoc +++ b/docs/whitepapers/industry/README.adoc @@ -1 +1,3 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Industry Logic diff --git a/docs/whitepapers/outreach/README.adoc b/docs/whitepapers/outreach/README.adoc index 8141463..f3ea4da 100644 --- a/docs/whitepapers/outreach/README.adoc +++ b/docs/whitepapers/outreach/README.adoc @@ -1,3 +1,5 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Outreach & Education :toc: preamble :icons: font diff --git a/docs/wikis/README.adoc b/docs/wikis/README.adoc index 71b60d1..4d493b4 100644 --- a/docs/wikis/README.adoc +++ b/docs/wikis/README.adoc @@ -1,3 +1,5 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Project Wikis :toc: preamble :icons: font diff --git a/examples/README.adoc b/examples/README.adoc index b9cdb48..40bc850 100644 --- a/examples/README.adoc +++ b/examples/README.adoc @@ -1 +1,3 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = examples Pillar diff --git a/features/README.adoc b/features/README.adoc index 3899280..4922891 100644 --- a/features/README.adoc +++ b/features/README.adoc @@ -1 +1,3 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Project Features diff --git a/features/boj-server/README.adoc b/features/boj-server/README.adoc index 0039c37..0ef0376 100644 --- a/features/boj-server/README.adoc +++ b/features/boj-server/README.adoc @@ -1,3 +1,5 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = BoJ Server Integration :icons: font diff --git a/features/panic-attacker/README.adoc b/features/panic-attacker/README.adoc index 72d56a4..de0bd9b 100644 --- a/features/panic-attacker/README.adoc +++ b/features/panic-attacker/README.adoc @@ -1,3 +1,5 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Panic Attacker Feature :icons: font diff --git a/features/ssg/README.adoc b/features/ssg/README.adoc index e15687b..a6ef262 100644 --- a/features/ssg/README.adoc +++ b/features/ssg/README.adoc @@ -1 +1,3 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Ssg Feature diff --git a/flake.nix b/flake.nix deleted file mode 100644 index f6c1adc..0000000 --- a/flake.nix +++ /dev/null @@ -1,170 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -# -# Nix flake for a2ml-validate-action -# -# NOTE: guix.scm is the PRIMARY development environment. This flake is provided -# as a FALLBACK for contributors who use Nix instead of Guix. The .envrc checks -# for Guix first, then falls back to Nix. -# -# Usage: -# nix develop # Enter development shell -# nix build # Build the project -# nix flake check # Run checks -# nix flake show # Show flake outputs -# -# With direnv (.envrc already configured): -# direnv allow # Auto-enters shell on cd -# -# TODO: Replace a2ml-validate-action and with actual values. - -{ - description = "a2ml-validate-action — RSR-compliant project"; - - inputs = { - nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable"; - flake-utils.url = "github:numtide/flake-utils"; - }; - - outputs = { self, nixpkgs, flake-utils }: - flake-utils.lib.eachSystem [ "x86_64-linux" "aarch64-linux" ] (system: - let - pkgs = import nixpkgs { inherit system; }; - - # Common development tools present in every RSR project. - commonTools = with pkgs; [ - git - just - nickel - curl - bash - coreutils - ]; - - # --------------------------------------------------------------- - # Language-specific packages: uncomment the stacks you need. - # --------------------------------------------------------------- - # - # Rust: - # rustc cargo clippy rustfmt rust-analyzer - # - # Elixir: - # elixir erlang - # - # Gleam: - # gleam erlang - # - # Zig: - # zig zls - # - # Haskell: - # ghc cabal-install haskell-language-server - # - # Idris2: - # idris2 - # - # OCaml: - # ocaml dune_3 ocaml-lsp - # - # ReScript (via Deno): - # deno - # - # Julia: - # julia - # - # Ada/SPARK: - # gnat gprbuild - # - # --------------------------------------------------------------- - languageTools = with pkgs; [ - # TODO: Uncomment or add packages for your stack. - # Example for a Rust project: - # rustc - # cargo - # clippy - # rustfmt - # rust-analyzer - ]; - - in - { - # --------------------------------------------------------------- - # Development shell — `nix develop` - # --------------------------------------------------------------- - devShells.default = pkgs.mkShell { - name = "a2ml-validate-action-dev"; - - buildInputs = commonTools ++ languageTools; - - # Environment variables available inside the shell. - env = { - PROJECT_NAME = "a2ml-validate-action"; - RSR_TIER = "infrastructure"; - }; - - shellHook = '' - echo "" - echo " a2ml-validate-action — development shell" - echo " Nix: $(nix --version 2>/dev/null || echo 'unknown')" - echo " Just: $(just --version 2>/dev/null || echo 'not found')" - echo "" - echo " Run 'just' to see available recipes." - echo "" - - # Source .envrc manually when direnv is not managing the shell. - # This keeps project env vars (PROJECT_NAME, DATABASE_URL, etc.) - # consistent whether you enter via 'nix develop' or 'direnv allow'. - if [ -z "''${DIRENV_IN_ENVRC:-}" ] && [ -f .envrc ]; then - # Only source the non-nix parts to avoid recursion. - export PROJECT_NAME="a2ml-validate-action" - export RSR_TIER="infrastructure" - if [ -f .env ]; then - set -a - . .env - set +a - fi - fi - ''; - }; - - # --------------------------------------------------------------- - # Package — `nix build` - # --------------------------------------------------------------- - packages.default = pkgs.stdenv.mkDerivation { - pname = "a2ml-validate-action"; - version = "0.1.0"; - - src = self; - - # TODO: Replace with real build instructions. - # Examples: - # - # Rust (use rustPlatform.buildRustPackage instead of stdenv): - # packages.default = pkgs.rustPlatform.buildRustPackage { ... }; - # - # Elixir (use mixRelease): - # packages.default = pkgs.beamPackages.mixRelease { ... }; - # - # Zig: - # buildPhase = "zig build -Doptimize=ReleaseSafe"; - - buildPhase = '' - echo "TODO: Add build commands for a2ml-validate-action" - ''; - - installPhase = '' - mkdir -p $out/share/doc - cp README.adoc $out/share/doc/ 2>/dev/null || true - ''; - - meta = with pkgs.lib; { - description = ""; - homepage = "https://github.com/hyperpolymath/a2ml-validate-action"; - license = licenses.mpl20; # MPL-2.0 extends MPL-2.0 - maintainers = []; - platforms = [ "x86_64-linux" "aarch64-linux" ]; - }; - }; - } - ); -} diff --git a/llm-warmup-dev.md b/llm-warmup-dev.md index 3eb00e8..a96bdbf 100644 --- a/llm-warmup-dev.md +++ b/llm-warmup-dev.md @@ -1,3 +1,7 @@ + # LLM Warmup — a2ml-validate-action (Developer) ## What is a2ml-validate-action? diff --git a/llm-warmup-user.md b/llm-warmup-user.md index 24a4350..b9b4fb1 100644 --- a/llm-warmup-user.md +++ b/llm-warmup-user.md @@ -1,3 +1,7 @@ + # LLM Warmup — a2ml-validate-action (User) ## What is a2ml-validate-action? diff --git a/src/README.adoc b/src/README.adoc index 5529f66..d8c8116 100644 --- a/src/README.adoc +++ b/src/README.adoc @@ -1 +1,3 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = src Pillar diff --git a/src/aspects/README.adoc b/src/aspects/README.adoc index 6456f96..9b7b80f 100644 --- a/src/aspects/README.adoc +++ b/src/aspects/README.adoc @@ -1 +1,3 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Aspects Pillar diff --git a/src/aspects/integrity/README.adoc b/src/aspects/integrity/README.adoc index f15d829..17a09db 100644 --- a/src/aspects/integrity/README.adoc +++ b/src/aspects/integrity/README.adoc @@ -1 +1,3 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Integrity Aspect diff --git a/src/aspects/observability/README.adoc b/src/aspects/observability/README.adoc index 7852ee6..df2ca36 100644 --- a/src/aspects/observability/README.adoc +++ b/src/aspects/observability/README.adoc @@ -1 +1,3 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Observability Aspect diff --git a/src/aspects/security/README.adoc b/src/aspects/security/README.adoc index 3c3536e..11ad21b 100644 --- a/src/aspects/security/README.adoc +++ b/src/aspects/security/README.adoc @@ -1 +1,3 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Security Aspect diff --git a/src/contracts/README.adoc b/src/contracts/README.adoc index 9cfa209..20dd4ca 100644 --- a/src/contracts/README.adoc +++ b/src/contracts/README.adoc @@ -1 +1,3 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Contracts Unit diff --git a/src/definitions/README.adoc b/src/definitions/README.adoc index 9548349..5a9912f 100644 --- a/src/definitions/README.adoc +++ b/src/definitions/README.adoc @@ -1 +1,3 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Definitions Unit diff --git a/src/errors/README.adoc b/src/errors/README.adoc index 460fc1e..eff7b29 100644 --- a/src/errors/README.adoc +++ b/src/errors/README.adoc @@ -1 +1,3 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Errors Unit diff --git a/src/interface/README.adoc b/src/interface/README.adoc index 8faf0aa..727b9e7 100644 --- a/src/interface/README.adoc +++ b/src/interface/README.adoc @@ -1 +1,3 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = interface Unit diff --git a/src/interface/abi/README.adoc b/src/interface/abi/README.adoc index 2330304..46743d7 100644 --- a/src/interface/abi/README.adoc +++ b/src/interface/abi/README.adoc @@ -1 +1,3 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = abi Logic diff --git a/src/interface/ffi/README.adoc b/src/interface/ffi/README.adoc index 8fe57d3..b402d64 100644 --- a/src/interface/ffi/README.adoc +++ b/src/interface/ffi/README.adoc @@ -1 +1,3 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = ffi Logic diff --git a/src/interface/ffi/build.zig b/src/interface/ffi/build.zig index 4a2e049..c02617f 100644 --- a/src/interface/ffi/build.zig +++ b/src/interface/ffi/build.zig @@ -1,5 +1,6 @@ -// {{PROJECT}} FFI Build Configuration // SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell +// {{PROJECT}} FFI Build Configuration const std = @import("std"); diff --git a/src/interface/ffi/src/README.adoc b/src/interface/ffi/src/README.adoc index a5c0c6d..4228438 100644 --- a/src/interface/ffi/src/README.adoc +++ b/src/interface/ffi/src/README.adoc @@ -1 +1,3 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Src Logic diff --git a/src/interface/ffi/src/main.zig b/src/interface/ffi/src/main.zig index 6b233bc..f1b2633 100644 --- a/src/interface/ffi/src/main.zig +++ b/src/interface/ffi/src/main.zig @@ -1,9 +1,10 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell // {{PROJECT}} 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/src/interface/ffi/test/README.adoc b/src/interface/ffi/test/README.adoc index f6f38bf..cdbb47d 100644 --- a/src/interface/ffi/test/README.adoc +++ b/src/interface/ffi/test/README.adoc @@ -1 +1,3 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Test Logic diff --git a/src/interface/ffi/test/integration_test.zig b/src/interface/ffi/test/integration_test.zig index 0341994..e481508 100644 --- a/src/interface/ffi/test/integration_test.zig +++ b/src/interface/ffi/test/integration_test.zig @@ -1,5 +1,6 @@ -// {{PROJECT}} Integration Tests // SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell +// {{PROJECT}} Integration Tests // // These tests verify that the Zig FFI correctly implements the Idris2 ABI diff --git a/src/interface/generated/README.adoc b/src/interface/generated/README.adoc index 3691b06..93daef2 100644 --- a/src/interface/generated/README.adoc +++ b/src/interface/generated/README.adoc @@ -1 +1,3 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = generated Logic diff --git a/src/interface/generated/abi/README.adoc b/src/interface/generated/abi/README.adoc index aff61a9..0e29b69 100644 --- a/src/interface/generated/abi/README.adoc +++ b/src/interface/generated/abi/README.adoc @@ -1 +1,3 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Abi Logic diff --git a/validate-a2ml.sh b/validate-a2ml.sh index b2c3e82..f3f0366 100755 --- a/validate-a2ml.sh +++ b/validate-a2ml.sh @@ -175,7 +175,7 @@ validate_a2ml() { # Canonical structured A2ML tree. Everything under a `.machine_readable/` # directory is a typed agent-readable doc (CLADE, ANCHOR, STATE, - # ECOSYSTEM, agent_instructions/{debt,coverage,methodology}, ai/AI, + # ECOSYSTEM, bot_directives/{debt,coverage,methodology}, ai/AI, # policies/*, integrations/*, …). Per the RSR convention these carry # identity structurally — owning repo + path + filename — not via an # in-file `name`/`agent-id`. This generalises the `.machine_readable/6a2/` diff --git a/verification/README.adoc b/verification/README.adoc index f07e7f3..efa7fb2 100644 --- a/verification/README.adoc +++ b/verification/README.adoc @@ -1 +1,3 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Verification Pillar diff --git a/verification/benchmarks/README.adoc b/verification/benchmarks/README.adoc index 5db7648..beb83cd 100644 --- a/verification/benchmarks/README.adoc +++ b/verification/benchmarks/README.adoc @@ -1 +1,3 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Benchmarks Unit diff --git a/verification/coverage/README.adoc b/verification/coverage/README.adoc index 2566956..c10a6ac 100644 --- a/verification/coverage/README.adoc +++ b/verification/coverage/README.adoc @@ -1 +1,3 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Coverage Unit diff --git a/verification/fuzzing/README.adoc b/verification/fuzzing/README.adoc index edeb179..b07ea68 100644 --- a/verification/fuzzing/README.adoc +++ b/verification/fuzzing/README.adoc @@ -1 +1,3 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Fuzzing Unit diff --git a/verification/proofs/README.adoc b/verification/proofs/README.adoc index 1ae324d..bc50bdf 100644 --- a/verification/proofs/README.adoc +++ b/verification/proofs/README.adoc @@ -1 +1,3 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Proofs Unit diff --git a/verification/safety_case/README.adoc b/verification/safety_case/README.adoc index 47c8e36..ffb53bd 100644 --- a/verification/safety_case/README.adoc +++ b/verification/safety_case/README.adoc @@ -1 +1,3 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Safety case Unit diff --git a/verification/simulations/README.adoc b/verification/simulations/README.adoc index 8e1b13a..42e184c 100644 --- a/verification/simulations/README.adoc +++ b/verification/simulations/README.adoc @@ -1 +1,3 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Simulations Unit diff --git a/verification/tests/README.adoc b/verification/tests/README.adoc index 344bf86..3930981 100644 --- a/verification/tests/README.adoc +++ b/verification/tests/README.adoc @@ -1 +1,3 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Tests Unit diff --git a/verification/traceability/README.adoc b/verification/traceability/README.adoc index ff23dd7..e6e54bc 100644 --- a/verification/traceability/README.adoc +++ b/verification/traceability/README.adoc @@ -1 +1,3 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Traceability Unit