From 31495866cc4b77f420262b3fb45bf988e110c214 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 21 Jun 2026 22:34:01 +0000 Subject: [PATCH] =?UTF-8?q?chore:=20close-out=20hygiene=20=E2=80=94=20SPDX?= =?UTF-8?q?=20fix,=20fill=20template=20placeholders,=20refresh=206a2=20sta?= =?UTF-8?q?te?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - SPDX: PMPL-1.0-or-later -> MPL-2.0 in governance.yml, hypatia-scan.yml, scorecard.yml (matches repo policy + the no-pmpl contractile rule). - Fill unfilled {{...}} template placeholders with real values: anchors/ANCHOR.a2ml, flake.nix (+enable Rust/Idris2/Zig dev shell), guix.scm, .guix-channel. - Refresh .machine_readable/6a2: STATE (date, PRs #34/#35/#36, blockers), PLAYBOOK (document branch-cleanup workflow + proxy-blocks-deletes), NEUROSYM (record upstream standards@5a93d9d Hypatia pin breakage). - QUICKSTART-DEV.adoc: fill placeholders and correct non-existent recipe names (setup-dev/panic-scan/llm-context -> real recipes). Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01Y2MWTAqX2x7goVJzjFB4j5 --- .github/workflows/governance.yml | 2 +- .github/workflows/hypatia-scan.yml | 2 +- .github/workflows/scorecard.yml | 2 +- .guix-channel | 10 +-- .machine_readable/6a2/NEUROSYM.a2ml | 13 +++- .machine_readable/6a2/PLAYBOOK.a2ml | 15 ++++- .machine_readable/6a2/STATE.a2ml | 29 ++++++--- .machine_readable/anchors/ANCHOR.a2ml | 10 +-- QUICKSTART-DEV.adoc | 91 ++++++++++++++------------- flake.nix | 41 ++++++------ guix.scm | 10 +-- 11 files changed, 136 insertions(+), 89 deletions(-) diff --git a/.github/workflows/governance.yml b/.github/workflows/governance.yml index 8161ec2..32b7e0d 100644 --- a/.github/workflows/governance.yml +++ b/.github/workflows/governance.yml @@ -1,4 +1,4 @@ -# SPDX-License-Identifier: PMPL-1.0-or-later +# SPDX-License-Identifier: MPL-2.0 name: Governance on: diff --git a/.github/workflows/hypatia-scan.yml b/.github/workflows/hypatia-scan.yml index e715848..aa8bde7 100644 --- a/.github/workflows/hypatia-scan.yml +++ b/.github/workflows/hypatia-scan.yml @@ -1,4 +1,4 @@ -# SPDX-License-Identifier: PMPL-1.0-or-later +# SPDX-License-Identifier: MPL-2.0 name: Hypatia Security Scan on: diff --git a/.github/workflows/scorecard.yml b/.github/workflows/scorecard.yml index 47acbb5..5484457 100644 --- a/.github/workflows/scorecard.yml +++ b/.github/workflows/scorecard.yml @@ -1,4 +1,4 @@ -# SPDX-License-Identifier: PMPL-1.0-or-later +# SPDX-License-Identifier: MPL-2.0 name: OSSF Scorecard on: diff --git a/.guix-channel b/.guix-channel index f9bdf68..f2847de 100644 --- a/.guix-channel +++ b/.guix-channel @@ -1,20 +1,20 @@ ;; SPDX-License-Identifier: MPL-2.0 -;; Copyright (c) {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}> +;; Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) ;; -;; Guix channel definition for {{PROJECT_NAME}} +;; Guix channel definition for wokelangiser ;; ;; To use this channel, add to ~/.config/guix/channels.scm: ;; ;; (channel -;; (name '{{PROJECT_NAME}}) -;; (url "https://github.com/{{OWNER}}/{{PROJECT_NAME}}") +;; (name 'wokelangiser) +;; (url "https://github.com/hyperpolymath/wokelangiser") ;; (branch "main")) ;; ;; Then: guix pull (channel (version 0) - (url "https://github.com/{{OWNER}}/{{PROJECT_NAME}}") + (url "https://github.com/hyperpolymath/wokelangiser") (dependencies (channel (name 'guix) diff --git a/.machine_readable/6a2/NEUROSYM.a2ml b/.machine_readable/6a2/NEUROSYM.a2ml index b01546e..d643325 100644 --- a/.machine_readable/6a2/NEUROSYM.a2ml +++ b/.machine_readable/6a2/NEUROSYM.a2ml @@ -6,7 +6,7 @@ [metadata] version = "0.1.0" -last-updated = "2026-03-21" +last-updated = "2026-06-21" [hypatia-config] scan-enabled = true @@ -30,3 +30,14 @@ rules = [ # Neural pattern detection settings confidence-threshold = 0.85 # model = "hypatia-v2" + +[known-issues] +# The standards-reusable Hypatia scan currently fails at action-resolution: +# hypatia-scan.yml pins hyperpolymath/standards@5a93d9d57cc04de4002d6d0ecd336fc7a8698910, +# whose hypatia-scan-reusable.yml references an unresolvable +# actions/cache@d4373f267a887d77f9eb0683a479ec60b1fe5b2b. +# The repo's other Hypatia job ("Hypatia neurosymbolic scan") still passes, so +# analysis coverage is retained. Fix: repair the pin upstream in +# hyperpolymath/standards, then bump the consumer pins. +hypatia-scan-status = "failing-upstream-pin" +affected-workflows = ["hypatia-scan.yml", "governance.yml", "scorecard.yml"] diff --git a/.machine_readable/6a2/PLAYBOOK.a2ml b/.machine_readable/6a2/PLAYBOOK.a2ml index 4d14233..74c3ce6 100644 --- a/.machine_readable/6a2/PLAYBOOK.a2ml +++ b/.machine_readable/6a2/PLAYBOOK.a2ml @@ -6,7 +6,7 @@ [metadata] version = "0.1.0" -last-updated = "2026-03-21" +last-updated = "2026-06-21" [deployment] method = "ci-triggered" @@ -40,3 +40,16 @@ artifacts = ["wokelangiser (CLI)", "libwokelangiser.so (FFI)"] # just perms-audit # ABI-FFI consistency check: # Compare struct sizes: ConsentRecord=24B, AccessibilityRecord=32B, I18nRecord=24B + +[branch-cleanup] +# The development git proxy returns HTTP 403 on `git push --delete`, so stale +# branches cannot be removed from a clone. Delete them server-side instead via +# the reusable workflow, which calls the GitHub REST API with GITHUB_TOKEN on the +# runner (bypassing the proxy): +# Actions -> "Branch Cleanup" -> Run workflow +# branches = "claude/foo claude/bar" (space-separated) +# dry_run = true (preview first; set false to actually delete) +workflow = ".github/workflows/branch-cleanup.yml" +trigger = "workflow_dispatch" +dry-run-default = true +protected = ["main", "cicd/codeql-cron-monthly", "estate-standardization-20260607"] diff --git a/.machine_readable/6a2/STATE.a2ml b/.machine_readable/6a2/STATE.a2ml index 52fab96..7ff99e5 100644 --- a/.machine_readable/6a2/STATE.a2ml +++ b/.machine_readable/6a2/STATE.a2ml @@ -5,9 +5,9 @@ [metadata] project = "wokelangiser" version = "0.1.0" -last-updated = "2026-03-21" +last-updated = "2026-06-21" status = "active" -session = "converted from scheme — 2026-04-11" +session = "RSR/security hardening + branch-cleanup automation — 2026-06-21" [project-context] name = "Wokelangiser" @@ -20,21 +20,34 @@ maturity = "experimental" # experimental | alpha | beta | production | lts [route-to-mvp] milestones = [ - # No milestones recorded + "Implement src/codegen/* target emission (consent / accessibility / i18n) — currently stubbed", + "First end-to-end example: manifest -> validated -> generated wrapper", + "Begin Idris2 formal proofs for domain-specific invariants", + "Repair upstream hyperpolymath/standards@5a93d9d CI pin (see blockers)", ] [blockers-and-issues] issues = [ - "Phase 1 complete — no blockers. Phase 2 requires domain logic implementation.", + "CI: Hypatia, OSSF Scorecard and Rust CI fail because hyperpolymath/standards@5a93d9d pins an unresolvable actions/cache@d4373f... SHA; needs an upstream fix plus a consumer pin bump.", + "Codegen (src/codegen/*) is stubbed — the `generate` pipeline is not yet functional end-to-end.", ] [critical-next-actions] actions = [ - "Implement core domain logic in src/core/", + "Implement core codegen in src/codegen/ (consent.rs, accessibility.rs, i18n.rs)", "Write first end-to-end example with real input", - "Begin Idris2 formal proofs for domain-specific invariants", + "Bump standards pin once hyperpolymath/standards repairs actions/cache", +] + +[recent-changes] +# 2026-06-21 session +changes = [ + "#34 merged: CodeQL Rust SAST added; scorecard-enforcer de-published; setup.sh `just` installer hardened (pinned + SHA256).", + "#35 merged: cleared Hypatia secret false-positives (.envrc / .envrc.example / setup.sh).", + "#36 merged: added reusable .github/workflows/branch-cleanup.yml (server-side ref deletion via gh/GITHUB_TOKEN).", + "Pruned 9 stale claude/* branches via the new workflow.", ] [maintenance-status] -last-run-utc = "2026-03-21T00:00:00Z" -last-result = "unknown" # unknown | pass | warn | fail +last-run-utc = "2026-06-21T00:00:00Z" +last-result = "warn" # green except upstream standards-pin CI failures diff --git a/.machine_readable/anchors/ANCHOR.a2ml b/.machine_readable/anchors/ANCHOR.a2ml index 93d3537..3f76e6e 100644 --- a/.machine_readable/anchors/ANCHOR.a2ml +++ b/.machine_readable/anchors/ANCHOR.a2ml @@ -5,7 +5,7 @@ [metadata] version = "1.0.0" -last-updated = "{{CURRENT_DATE}}" +last-updated = "2026-06-21" [anchor] schema = "hyperpolymath.anchor/1" @@ -19,10 +19,10 @@ purpose = [ ] [identity] -project = "{{PROJECT_NAME}}" -kind = "{{PROJECT_KIND}}" # language | library | service | tool -one-sentence = "{{PROJECT_PURPOSE}}" -domain = "{{PROJECT_DOMAIN}}" +project = "wokelangiser" +kind = "tool" # language | library | service | tool +one-sentence = "Add consent patterns, accessibility annotations, i18n hooks, and cultural sensitivity markers to existing code via WokeLang" +domain = "code-generation, compliance, accessibility" [semantic-authority] policy = "canonical" diff --git a/QUICKSTART-DEV.adoc b/QUICKSTART-DEV.adoc index 5e289b3..22b1999 100644 --- a/QUICKSTART-DEV.adoc +++ b/QUICKSTART-DEV.adoc @@ -1,13 +1,15 @@ // SPDX-License-Identifier: CC-BY-SA-4.0 -// Template: QUICKSTART-DEV.adoc — clone → build → test → PR -// Replace wokelangiser, {{BUILD_CMD}}, {{TEST_CMD}}, {{LANG_STACK}} with actuals +// QUICKSTART-DEV.adoc — clone -> build -> test -> PR = wokelangiser — Quick Start for Developers :toc: :toclevels: 2 == Tech Stack -{{LANG_STACK}} +* **Rust** — CLI host and codegen (`src/main.rs`, `src/codegen/`, `src/manifest/`) +* **Idris2** — formal ABI proofs (`src/interface/abi/*.idr`) +* **Zig** — C-ABI FFI bridge (`src/interface/ffi/`) +* **Just** — task runner; **Guix/Nix** — reproducible dev environment == Set Up Development Environment @@ -15,7 +17,7 @@ [source,bash] ---- -guix shell +guix shell -D -f guix.scm ---- === Option B: Nix (fallback) @@ -31,21 +33,25 @@ nix develop ---- git clone https://github.com/hyperpolymath/wokelangiser.git cd wokelangiser -just setup-dev +just doctor # check required tools (just, git, cargo, ...) ---- +You will need a Rust toolchain (`cargo`) and — for the ABI/FFI layers — `idris2` and `zig`. + == Build [source,bash] ---- -{{BUILD_CMD}} +just build # cargo build --release ---- == Test [source,bash] ---- -{{TEST_CMD}} +just test # cargo test +# FFI tests: +cd src/interface/ffi && zig build test ---- == Project Structure @@ -53,59 +59,60 @@ just setup-dev [source] ---- wokelangiser/ -├── src/ # Source code -├── src/abi/ # Idris2 ABI definitions (if applicable) -├── ffi/zig/ # Zig FFI bridge (if applicable) -├── tests/ # Test suite -├── docs/ # Documentation -├── .machine_readable/ # Checkpoint files (STATE, META, ECOSYSTEM) -├── Justfile # Task runner recipes -├── guix.scm # Guix environment -├── flake.nix # Nix environment (fallback) -└── 0-AI-MANIFEST.a2ml # AI agent entry point +├── src/main.rs # Rust CLI entry (init/validate/generate/build/run/info) +├── src/manifest/ # wokelangiser.toml parser +├── src/codegen/ # target-language emission (WIP — stubs) +├── src/interface/abi/ # Idris2 ABI proofs (Types/Layout/Foreign) +├── src/interface/ffi/ # Zig C-ABI bridge + tests +├── docs/ # Human documentation (canonical) +├── .machine_readable/ # Machine docs: 6a2/, contractiles/, anchors/ +├── Justfile # Task runner recipes +├── guix.scm / flake.nix # Dev environments (Guix primary, Nix fallback) +└── 0-AI-MANIFEST.a2ml # AI agent entry point ---- == Key Recipes [source,bash] ---- -just build # Build the project -just test # Run tests -just doctor # Self-diagnostic -just lint # Lint and format -just panic-scan # Security scan via panic-attacker -just tour # Guided tour of the codebase +just # build + test (default) +just build # release build +just test # run tests +just lint # clippy (-D warnings) +just fmt # format +just quality # fmt-check + lint + test +just validate ARGS # validate a manifest +just generate ARGS # run the codegen pipeline (WIP) +just doctor # self-diagnostic +just assail # panic-attacker security scan +just tour # guided tour ---- +Run `just --list` to see every recipe. + == Before Submitting a PR [source,bash] ---- -just lint # Format and lint -just test # All tests pass -just panic-scan # No new security issues +just quality # fmt-check + lint + test must pass +just assail # no new security findings (if panic-attack installed) ---- -== Contractile Invariants - -Read `.machine_readable/MUST.contractile` before making changes. -Key invariants that must never be violated: - -{{MUST_INVARIANTS}} +Branch from `main`, use Conventional-Commits-style messages, then open a PR — see +link:CONTRIBUTING.md[CONTRIBUTING.md]. -== LLM/AI Agent Development +== Contractile Invariants -If using an AI assistant, load the warmup context first: +Before changing code, read the contractiles under `.machine_readable/contractiles/` +— especially `must/Mustfile.a2ml` (critical invariants: no banned licences, no +unsafe FFI, tests must pass). The matching CI gate is the Governance workflow. -[source,bash] ----- -just llm-context # Outputs role-appropriate context ----- +== LLM / AI Agent Development -Or read `0-AI-MANIFEST.a2ml` and `.claude/CLAUDE.md` directly. +If using an AI assistant, load context first by reading `0-AI-MANIFEST.a2ml` +(repo entry point) and `.claude/CLAUDE.md` (language and policy rules). == Get Help -* **Architecture**: link:EXPLAINME.adoc[EXPLAINME.adoc] -* **Wiki**: https://github.com/hyperpolymath/wokelangiser/wiki -* **Report issue**: `just help-me` +* **Architecture**: link:EXPLAINME.adoc[EXPLAINME.adoc] and link:docs/developer/ABI-FFI-README.adoc[docs/developer/ABI-FFI-README.adoc] +* **Report an issue**: `just help-me`, or https://github.com/hyperpolymath/wokelangiser/issues diff --git a/flake.nix b/flake.nix index df7a0a5..1050d8d 100644 --- a/flake.nix +++ b/flake.nix @@ -1,7 +1,7 @@ # SPDX-License-Identifier: MPL-2.0 -# Copyright (c) {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}> +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) # -# Nix flake for {{PROJECT_NAME}} +# Nix flake for wokelangiser # # 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 @@ -16,10 +16,10 @@ # With direnv (.envrc already configured): # direnv allow # Auto-enters shell on cd # -# TODO: Replace {{PROJECT_NAME}} and {{PROJECT_DESCRIPTION}} with actual values. +# Identity, description, and dev-shell toolchain below are filled for wokelangiser. { - description = "{{PROJECT_NAME}} — RSR-compliant project"; + description = "wokelangiser — RSR-compliant project"; inputs = { nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable"; @@ -77,13 +77,16 @@ # # --------------------------------------------------------------- languageTools = with pkgs; [ - # TODO: Uncomment or add packages for your stack. - # Example for a Rust project: - # rustc - # cargo - # clippy - # rustfmt - # rust-analyzer + # Rust (CLI + codegen) + rustc + cargo + clippy + rustfmt + rust-analyzer + # Idris2 (ABI proofs) + idris2 + # Zig (FFI bridge) + zig ]; in @@ -92,19 +95,19 @@ # Development shell — `nix develop` # --------------------------------------------------------------- devShells.default = pkgs.mkShell { - name = "{{PROJECT_NAME}}-dev"; + name = "wokelangiser-dev"; buildInputs = commonTools ++ languageTools; # Environment variables available inside the shell. env = { - PROJECT_NAME = "{{PROJECT_NAME}}"; + PROJECT_NAME = "wokelangiser"; RSR_TIER = "infrastructure"; }; shellHook = '' echo "" - echo " {{PROJECT_NAME}} — development shell" + echo " wokelangiser — development shell" echo " Nix: $(nix --version 2>/dev/null || echo 'unknown')" echo " Just: $(just --version 2>/dev/null || echo 'not found')" echo "" @@ -116,7 +119,7 @@ # consistent whether you enter via 'nix develop' or 'direnv allow'. if [ -z "''${DIRENV_IN_ENVRC:-}" ] && [ -f .envrc ]; then # Only source the non-nix parts to avoid recursion. - export PROJECT_NAME="{{PROJECT_NAME}}" + export PROJECT_NAME="wokelangiser" export RSR_TIER="infrastructure" if [ -f .env ]; then set -a @@ -131,7 +134,7 @@ # Package — `nix build` # --------------------------------------------------------------- packages.default = pkgs.stdenv.mkDerivation { - pname = "{{PROJECT_NAME}}"; + pname = "wokelangiser"; version = "0.1.0"; src = self; @@ -149,7 +152,7 @@ # buildPhase = "zig build -Doptimize=ReleaseSafe"; buildPhase = '' - echo "TODO: Add build commands for {{PROJECT_NAME}}" + echo "TODO: Add build commands for wokelangiser" ''; installPhase = '' @@ -158,8 +161,8 @@ ''; meta = with pkgs.lib; { - description = "{{PROJECT_DESCRIPTION}}"; - homepage = "https://github.com/{{OWNER}}/{{PROJECT_NAME}}"; + description = "Add consent patterns, accessibility annotations, i18n hooks, and cultural sensitivity markers to existing code via WokeLang"; + homepage = "https://github.com/hyperpolymath/wokelangiser"; license = licenses.mpl20; # MPL-2.0 extends MPL-2.0 maintainers = []; platforms = [ "x86_64-linux" "aarch64-linux" ]; diff --git a/guix.scm b/guix.scm index cdf73ef..4a63c50 100644 --- a/guix.scm +++ b/guix.scm @@ -1,13 +1,13 @@ ;; SPDX-License-Identifier: MPL-2.0 ;; Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) ;; -;; Guix package definition for {{PROJECT_NAME}} +;; Guix package definition for wokelangiser ;; ;; Usage: ;; guix shell -D -f guix.scm # Enter development shell ;; guix build -f guix.scm # Build package ;; -;; TODO: Replace {{PROJECT_NAME}} and customize inputs for your language/stack. +;; TODO: customize build phases and inputs for the Rust/Idris2/Zig stack. ;; See: https://guix.gnu.org/manual/en/html_node/Defining-Packages.html (use-modules (guix packages) @@ -18,7 +18,7 @@ (gnu packages base)) (package - (name "{{PROJECT_NAME}}") + (name "wokelangiser") (version "0.1.0") (source (local-file "." "source" #:recursive? #t @@ -63,8 +63,8 @@ (list ;; TODO: Add runtime dependencies )) - (home-page "https://github.com/hyperpolymath/{{PROJECT_NAME}}") - (synopsis "{{PROJECT_PURPOSE}}") + (home-page "https://github.com/hyperpolymath/wokelangiser") + (synopsis "Add consent patterns, accessibility, i18n hooks, and cultural sensitivity markers via WokeLang") (description "RSR-compliant project. See README.adoc for details.") (license (list ;; MPL-2.0 extends MPL-2.0