From 4db6777b89c48db0dcad1dface972c7699280756 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Thu, 30 Apr 2026 16:21:25 +0100 Subject: [PATCH] chore(meta+grades): three doc-drift fixes against canonical rules 1. .meta/REQUIRED-FILES: .scm -> .a2ml for 6a2 metadata files. The 'Mandatory SCM Files' table listed META.scm/STATE.scm/etc., but the canonical extension is .a2ml. .scm is reserved for Guix-related files only (guix.scm, .guix-channel). Confirmed by user 2026-04-30 and consistent with this repo's own .machine_readable/6a2/*.a2ml. 2. .meta/REQUIRED-FILES.md -> .adoc. Per the hyperpolymath convention (AsciiDoc by default, Markdown only for files GitHub's community-health rules special-case by name), internal documentation goes in .adoc. 3. 'all 17 RSR workflows' / '19 CI workflows' -> reference the canonical machine-readable @required_workflows rule. The actual list lives in hypatia-rules/rsr-self-compliance.a2ml and currently names 4 workflows (hypatia-scan, mirror, scorecard, rsr-antipattern). Several prose docs claimed 17 or 19. Replacing the hard count with a reference to the rule keeps the prose durable. Affects: immaculate-guide/IMMACULATE-GUIDE.adoc (lines 130, 267) toolchain-readiness-grades/TOOLCHAIN-READINESS-GRADES.adoc (228, 443) toolchain-readiness-grades/TOOLCHAIN-READINESS-GRADES.a2ml (line 56) toolchain-readiness-grades/SELF-ASSESSMENT.adoc (line 74) component-readiness-grades/SELF-ASSESSMENT.adoc (line 32) Co-Authored-By: Claude Opus 4.7 (1M context) --- .meta/REQUIRED-FILES.adoc | 73 +++++++++++++++++++ .meta/REQUIRED-FILES.md | 53 -------------- .../SELF-ASSESSMENT.adoc | 2 +- immaculate-guide/IMMACULATE-GUIDE.adoc | 4 +- .../SELF-ASSESSMENT.adoc | 2 +- .../TOOLCHAIN-READINESS-GRADES.a2ml | 2 +- .../TOOLCHAIN-READINESS-GRADES.adoc | 4 +- 7 files changed, 80 insertions(+), 60 deletions(-) create mode 100644 .meta/REQUIRED-FILES.adoc delete mode 100644 .meta/REQUIRED-FILES.md diff --git a/.meta/REQUIRED-FILES.adoc b/.meta/REQUIRED-FILES.adoc new file mode 100644 index 00000000..6373bd01 --- /dev/null +++ b/.meta/REQUIRED-FILES.adoc @@ -0,0 +1,73 @@ +// SPDX-License-Identifier: PMPL-1.0-or-later += Required Repository Files + +The following files *MUST* be present and kept up-to-date in every repository: + +== Mandatory Dotfiles + +[cols="2,3"] +|=== +| File | Purpose + +| `.gitignore` | Exclude build artifacts, secrets, and temp files +| `.gitattributes` | Enforce LF line endings and diff settings +| `.editorconfig` | Consistent editor settings across IDEs +| `.tool-versions` | asdf version pinning for reproducible builds +|=== + +== Mandatory A2ML Files + +[NOTE] +==== +These files use the `.a2ml` extension. Earlier versions of this doc +listed them as `.scm`; that was stale drift. `.scm` is reserved exclusively +for Guix-related files (`guix.scm`, `.guix-channel`). All 6a2 metadata +files use `.a2ml`. +==== + +[cols="2,3"] +|=== +| File | Purpose + +| `META.a2ml` | Architecture decisions, development practices +| `STATE.a2ml` | Project state, phase, milestones +| `ECOSYSTEM.a2ml` | Ecosystem positioning, related projects +| `PLAYBOOK.a2ml` | Executable plans, procedures +| `AGENTIC.a2ml` | AI agent operational gating +| `NEUROSYM.a2ml` | Symbolic semantics, proof obligations +|=== + +== Build System + +[cols="2,3"] +|=== +| File | Purpose + +| `justfile` | Task runner (replaces Makefile) +| `Mustfile` | Deployment state contract +|=== + +*IMPORTANT*: Makefiles are FORBIDDEN. Use `just` for all tasks. + +== Validation + +These files are checked by: + +* CI workflow validation +* Pre-commit hooks (when configured) +* Repository standardization scripts + +== Updates + +When updating these files: + +. Use templates from `rsr-template-repo` as reference +. Ensure SPDX license header is present +. Test changes locally before pushing +. Keep language-specific sections relevant to the repo + +== See Also + +* link:https://github.com/hyperpolymath/rhodium-standard-repositories[RSR (Rhodium Standard Repositories)] +* link:https://github.com/hyperpolymath/mustfile[Mustfile Specification] +* link:https://github.com/hyperpolymath/standards/tree/main/meta-a2ml[A2ML Format Family] diff --git a/.meta/REQUIRED-FILES.md b/.meta/REQUIRED-FILES.md deleted file mode 100644 index a1552763..00000000 --- a/.meta/REQUIRED-FILES.md +++ /dev/null @@ -1,53 +0,0 @@ -# Required Repository Files - -The following files **MUST** be present and kept up-to-date in every repository: - -## Mandatory Dotfiles - -| File | Purpose | -|------|---------| -| `.gitignore` | Exclude build artifacts, secrets, and temp files | -| `.gitattributes` | Enforce LF line endings and diff settings | -| `.editorconfig` | Consistent editor settings across IDEs | -| `.tool-versions` | asdf version pinning for reproducible builds | - -## Mandatory SCM Files - -| File | Purpose | -|------|---------| -| `META.scm` | Architecture decisions, development practices | -| `STATE.scm` | Project state, phase, milestones | -| `ECOSYSTEM.scm` | Ecosystem positioning, related projects | -| `PLAYBOOK.scm` | Executable plans, procedures | -| `AGENTIC.scm` | AI agent operational gating | -| `NEUROSYM.scm` | Symbolic semantics, proof obligations | - -## Build System - -| File | Purpose | -|------|---------| -| `justfile` | Task runner (replaces Makefile) | -| `Mustfile` | Deployment state contract | - -**IMPORTANT**: Makefiles are FORBIDDEN. Use `just` for all tasks. - -## Validation - -These files are checked by: -- CI workflow validation -- Pre-commit hooks (when configured) -- Repository standardization scripts - -## Updates - -When updating these files: -1. Use templates from `rsr-template-repo` as reference -2. Ensure SPDX license header is present -3. Test changes locally before pushing -4. Keep language-specific sections relevant to the repo - -## See Also - -- [RSR (Rhodium Standard Repositories)](https://github.com/hyperpolymath/rhodium-standard-repositories) -- [Mustfile Specification](https://github.com/hyperpolymath/mustfile) -- [A2ML Format Family](https://github.com/hyperpolymath/standards/tree/main/meta-a2ml) diff --git a/component-readiness-grades/SELF-ASSESSMENT.adoc b/component-readiness-grades/SELF-ASSESSMENT.adoc index 90823f5b..df6b1dd6 100644 --- a/component-readiness-grades/SELF-ASSESSMENT.adoc +++ b/component-readiness-grades/SELF-ASSESSMENT.adoc @@ -29,7 +29,7 @@ Assessed: 2026-04-04 |**D (RSR-Compliant)** |PASSED -|RSR scaffolding complete: LICENSE, SECURITY.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md, MAINTAINERS.adoc, 19 CI workflows, .machine_readable/, 0-AI-MANIFEST.a2ml, Justfile/Mustfile +|RSR scaffolding complete: LICENSE, SECURITY.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md, MAINTAINERS.adoc, RSR-required CI workflows (per `hypatia-rules/rsr-self-compliance.a2ml @required_workflows`) + adopted optional set, .machine_readable/, 0-AI-MANIFEST.a2ml, Justfile/Mustfile |**C (Self-Validated)** |PASSED diff --git a/immaculate-guide/IMMACULATE-GUIDE.adoc b/immaculate-guide/IMMACULATE-GUIDE.adoc index d901ff3a..03719686 100644 --- a/immaculate-guide/IMMACULATE-GUIDE.adoc +++ b/immaculate-guide/IMMACULATE-GUIDE.adoc @@ -127,7 +127,7 @@ fi === rsr-template-repo as Canonical Start Every new repository MUST start from `rsr-template-repo`, not from scratch. -This ensures the 17 required workflows, the `.machine_readable/` directory, +This ensures the RSR-required workflows (per `hypatia-rules/rsr-self-compliance.a2ml @required_workflows` — currently 4 mandated, plus the broader adoptable set), the `.machine_readable/` directory, and the `justfile` scaffold are present from day one. [source,bash] @@ -264,7 +264,7 @@ before every merge._ === The Hyperpolymath CI Stack -Every repo uses the 17 required workflows from `rsr-template-repo`. +Every repo uses the RSR workflows from `rsr-template-repo` — 4 mandated by `hypatia-rules/rsr-self-compliance.a2ml @required_workflows` (`hypatia-scan.yml`, `mirror.yml`, `scorecard.yml`, `rsr-antipattern.yml`), plus the broader optional adoptable set. The three that act as truth validators are: [source,bash] diff --git a/toolchain-readiness-grades/SELF-ASSESSMENT.adoc b/toolchain-readiness-grades/SELF-ASSESSMENT.adoc index b182ce5c..d584c0e7 100644 --- a/toolchain-readiness-grades/SELF-ASSESSMENT.adoc +++ b/toolchain-readiness-grades/SELF-ASSESSMENT.adoc @@ -71,7 +71,7 @@ The next non-trivial promotion. Requires: is now at `templates/CANONICAL-PROOF-SUITE.adoc` (v1.0, 15 entries). . *2 fully-proven programs* per §6.2, each cross-validated by at least one qualifying prover from `templates/QUALIFYING-PROVERS.adoc`. -. *RSR-FULL* — all 17 RSR workflows present, SHA-pinned, and currently +. *RSR-FULL* — all RSR-required workflows (per `hypatia-rules/rsr-self-compliance.a2ml @required_workflows`) plus the broader adopted set present, SHA-pinned, and currently green. Standards repo is RSR-compliant; need to verify the same for the host repo of the audited component. . *Banned constructs ZERO* — verified by `panic-attack assail` clean diff --git a/toolchain-readiness-grades/TOOLCHAIN-READINESS-GRADES.a2ml b/toolchain-readiness-grades/TOOLCHAIN-READINESS-GRADES.a2ml index e8c6b0f2..69c427f6 100644 --- a/toolchain-readiness-grades/TOOLCHAIN-READINESS-GRADES.a2ml +++ b/toolchain-readiness-grades/TOOLCHAIN-READINESS-GRADES.a2ml @@ -53,7 +53,7 @@ (stability-posture "not-yet-releasable") (ordinal 3) (description "All Must + Should + Canonical Proof Suite. RSR-FULL. panic-attack zero across all severities. Fuzzing harness exists. 2 fully-proven programs.") - (evidence-required "all E + canonical M/S/E proof suite passing + RSR-FULL all 17 workflows green + panic-attack zero all severities + fuzz harness exists + 2 fully-proven programs each by >=1 qualifying prover") + (evidence-required "all E + canonical M/S/E proof suite passing + RSR-FULL all required workflows green (per hypatia-rules/rsr-self-compliance.a2ml @required_workflows) + panic-attack zero all severities + fuzz harness exists + 2 fully-proven programs each by >=1 qualifying prover") (minimum-for #f)) (grade (code C) diff --git a/toolchain-readiness-grades/TOOLCHAIN-READINESS-GRADES.adoc b/toolchain-readiness-grades/TOOLCHAIN-READINESS-GRADES.adoc index d05a52cc..cb346ede 100644 --- a/toolchain-readiness-grades/TOOLCHAIN-READINESS-GRADES.adoc +++ b/toolchain-readiness-grades/TOOLCHAIN-READINESS-GRADES.adoc @@ -225,7 +225,7 @@ NOTE: D is *not* the alpha gate. Alpha begins at C. D is the [horizontal] Tier gate:: All *Must* AND all *Should* rows PASSED. -Repository discipline:: RSR-FULLY-compliant — all 17 RSR workflows present, +Repository discipline:: RSR-FULLY-compliant — all RSR-required workflows (per `hypatia-rules/rsr-self-compliance.a2ml @required_workflows`) plus the broader adopted set present, SHA-pinned, and *currently green*. (Promoted from B to D because a toolchain component without RSR-full is just an unaudited binary in disguise.) All grade-E requirements carried forward. @@ -440,7 +440,7 @@ estate standard at the time of assessment. Specifically and without exception: [horizontal] -RSR:: All 17 RSR workflows present, SHA-pinned, and *green for at least +RSR:: All RSR-required workflows (per `hypatia-rules/rsr-self-compliance.a2ml @required_workflows`) plus the broader adopted set present, SHA-pinned, and *green for at least 90 consecutive days*. Zero workflow flakes in that window. Branch protection:: per `feedback_branch_protection.md` — PR-required, signatures-required, linear history,