Skip to content

feat(standards): add ARG + FRG language-maturation framework - #226

Closed
hyperpolymath wants to merge 1 commit into
mainfrom
arg-frg-framework-landing
Closed

hyperpolymath wants to merge 1 commit into
mainfrom
arg-frg-framework-landing

Conversation

@hyperpolymath

Copy link
Copy Markdown
Owner

Summary

Adds two sibling-tier standards to the existing TRG/CRG family, completing the four-axis language-maturation grading framework.

  • ARG (Adoption Readiness Grades) at adoption-readiness-grades/ — real-world adoption readiness: community, ergonomics, tooling polish, docs, deployment story
  • FRG (Foundations Readiness Grades) at foundations-readiness-grades/ — foundational research surfaces: mechanised proofs, papers, verification harnesses, formal artefacts

Estate grade vocabulary X | F | E | D | C | B | A with worst-of aggregation.

Cross-axis rule: ARG <= TRG always; ARG-A requires FRG >= B.

Includes audit findings doc AUDIT-FINDINGS-2026-05-28.adoc with §7 prover-CI hygiene addendum and §7.5 calibration lessons (~67% sub-agent false-positive rate on the 2026-05-28 sweep).

What's in each subtree

adoption-readiness-grades/ (ARG):

  • ADOPTION-READINESS-GRADES.adoc — normative spec
  • ADOPTION-READINESS-GRADES.a2ml — machine-readable counterpart
  • README.adoc — entry point
  • SELF-ASSESSMENT.adoc — self-grade for the standards repo
  • AUDIT-FINDINGS-2026-05-28.adoc — 2026-05-28 audit
  • templates/ARG-PROFILE-TEMPLATE.adoc — per-language profile template

foundations-readiness-grades/ (FRG): same shape, no audit doc.

Follow-ups (separate PRs)

  • affinescript: per-language ARG/FRG profile
  • ephapax: per-language ARG/FRG profile
  • my-lang: per-language ARG/FRG profile
  • nextgen-languages: dashboard + tracker wiring (TOOLING-STATUS.adoc + language-status-tracker.jl)

Test plan

  • CI passes
  • .adoc + .a2ml render cleanly
  • No SPDX-header lint complaints

🤖 Generated with Claude Code

Adds two sibling-tier standards to the existing TRG/CRG family:

- adoption-readiness-grades/ — ARG: real-world adoption readiness
  (community, ergonomics, tooling polish, docs, deployment story)
- foundations-readiness-grades/ — FRG: foundational research surfaces
  (mechanised proofs, papers, verification harnesses, formal artefacts)

Estate grade vocabulary X | F | E | D | C | B | A with worst-of aggregation.
Cross-axis rule: ARG <= TRG always; ARG-A requires FRG >= B.

Includes audit findings doc AUDIT-FINDINGS-2026-05-28.adoc with §7 prover-CI
hygiene addendum and §7.5 calibration lessons (~67% sub-agent false-positive
rate on the 2026-05-28 sweep).

Per-language profiles to land separately in affinescript / ephapax / my-lang.
Dashboard wiring to land separately in nextgen-languages.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@hyperpolymath
hyperpolymath enabled auto-merge (squash) May 28, 2026 10:06
@github-actions

Copy link
Copy Markdown
Contributor

🔍 Hypatia Security Scan

Findings: 196 issues detected

Severity Count
🔴 Critical 65
🟠 High 39
🟡 Medium 92

⚠️ Action Required: Critical security issues found!

View findings
[
  {
    "reason": "Issue in affinescript-verify.yml",
    "type": "unknown",
    "file": "affinescript-verify.yml",
    "action": "flag",
    "rule_module": "workflow_audit",
    "severity": "medium"
  },
  {
    "reason": "Issue in boj-build.yml",
    "type": "unknown",
    "file": "boj-build.yml",
    "action": "flag",
    "rule_module": "workflow_audit",
    "severity": "medium"
  },
  {
    "reason": "Issue in casket-pages.yml",
    "type": "unknown",
    "file": "casket-pages.yml",
    "action": "flag",
    "rule_module": "workflow_audit",
    "severity": "medium"
  },
  {
    "reason": "Issue in casket-pages.yml",
    "type": "unknown",
    "file": "casket-pages.yml",
    "action": "flag",
    "rule_module": "workflow_audit",
    "severity": "medium"
  },
  {
    "reason": "Issue in changelog-reusable.yml",
    "type": "unknown",
    "file": "changelog-reusable.yml",
    "action": "flag",
    "rule_module": "workflow_audit",
    "severity": "medium"
  },
  {
    "reason": "Issue in codeql-reusable.yml",
    "type": "unknown",
    "file": "codeql-reusable.yml",
    "action": "flag",
    "rule_module": "workflow_audit",
    "severity": "medium"
  },
  {
    "reason": "Issue in codeql.yml",
    "type": "unknown",
    "file": "codeql.yml",
    "action": "flag",
    "rule_module": "workflow_audit",
    "severity": "medium"
  },
  {
    "reason": "Issue in deno-ci-reusable.yml",
    "type": "unknown",
    "file": "deno-ci-reusable.yml",
    "action": "flag",
    "rule_module": "workflow_audit",
    "severity": "medium"
  },
  {
    "reason": "Issue in doc-format.yml",
    "type": "unknown",
    "file": "doc-format.yml",
    "action": "flag",
    "rule_module": "workflow_audit",
    "severity": "medium"
  },
  {
    "reason": "Issue in echidna-verify.yml",
    "type": "unknown",
    "file": "echidna-verify.yml",
    "action": "flag",
    "rule_module": "workflow_audit",
    "severity": "medium"
  }
]

Powered by Hypatia Neurosymbolic CI/CD Intelligence

hyperpolymath added a commit to hyperpolymath/ephapax that referenced this pull request May 28, 2026
## Summary

Adds the per-language Adoption + Foundations Readiness Grade profiles
for Ephapax, scored against the framework being introduced in
hyperpolymath/standards#226 (ARG + FRG companion spec).

- `spec/ARG-PROFILE.adoc` — adoption readiness profile
- `spec/FRG-PROFILE.adoc` — foundations readiness profile

**Grade**:
- **ARG-E**: research artefact, narrow adopter base, working compiler
- **FRG-D**: active mechanised-proof line in `formal/`, multi-layer
redesign (L1 regions / L2 modality / L3 echo / L4 dyadic),
counterexample-verified preservation invariants

Cross-axis: this is the inverse of the AffineScript shape
(research-strong / adoption-narrow vs. adoption-pragmatic /
research-light), and is consistent with Ephapax's positioning as a
foundational vehicle.

## Test plan

- [ ] CI passes
- [ ] `.adoc` renders cleanly
- [ ] No SPDX-header lint complaints

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
hyperpolymath added a commit to hyperpolymath/nextgen-languages that referenced this pull request May 28, 2026
## Summary

Extends the language status dashboard with ARG (Adoption Readiness
Grades) + FRG (Foundations Readiness Grades) wiring, implementing the
dashboard side of the framework being introduced in
hyperpolymath/standards#226.

- **TOOLING-STATUS.adoc** — adds a Language Grades Matrix section
- **language-status-tracker.jl** — adds `LanguageGrades` struct + grade
extraction

Reads per-language `ARG-PROFILE.adoc` + `FRG-PROFILE.adoc` from each
tracked language repo (where present) and surfaces the `X | F | E | D |
C | B | A` grade across all four maturity axes (ARG / TRG / FRG / CRG)
plus RSR.

Companion per-language profile PRs:
- affinescript: ARG-D + FRG-E
- ephapax: ARG-E + FRG-D
- my-lang: ARG-D-leaning-E + FRG-X

## Test plan

- [ ] CI passes
- [ ] `.adoc` renders cleanly
- [ ] `language-status-tracker.jl` parses/runs cleanly
- [ ] No SPDX-header lint complaints

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
hyperpolymath added a commit that referenced this pull request May 28, 2026
## Summary

Fills a gap in the existing TRG/CRG standards: both standards permit
per-language profiles (TRG §1.1, CRG §4.6) that tighten the baseline,
but neither shipped a profile template.

- **`toolchain-readiness-grades/templates/TRG-PROFILE-TEMPLATE.adoc`** —
mirrors the per-component breakdown from TRG §3 (F1-F7 front-end, M1-M5
middle-end, B1-B6 back-end, T1-T9 tool surface), each with its own grade
column and evidence column
- **`component-readiness-grades/templates/CRG-PROFILE-TEMPLATE.adoc`** —
mirrors the released-component shape from CRG §3; one row per released
artefact, plus a grade-clause rationale table per CRG §4

Both templates use the same outer structure as the ARG/FRG templates
introduced in #226 (metadata header, axes recap, language-specific
tightening, honest-gaps, path-to-next-grade, demotion risk, iteration
history, review cycle, VeriSimDB attestation footer).

## Follow-ups (separate PRs)

Per-language TRG + CRG profiles to land in:

- `affinescript`
- `ephapax`
- `my-lang`
- `typed-wasm` (compilation target treated as a language-shaped artefact
— has grammar, AST, semantics, type system, runtime)

## Test plan

- [ ] CI passes
- [ ] `.adoc` renders cleanly
- [ ] No SPDX-header lint complaints

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
auto-merge was automatically disabled May 28, 2026 11:27

Pull request was closed

@hyperpolymath
hyperpolymath deleted the arg-frg-framework-landing branch May 28, 2026 11:27
hyperpolymath added a commit that referenced this pull request Sep 22, 2026
…it past #946 (#962)

## What this fixes

The lock gate is staged from a **third pin**.

There are not two pins in this system, there are three:

1. the caller's `uses: hyperpolymath/standards/...@<sha>` ref,
2. `actions.lock`'s record of that ref, and
3. **a SHA hardcoded inside `governance-reusable.yml`** for its own
   `actions/checkout` of the lock-gate tooling.

Bumping a caller cannot reach the third one. A *called* reusable
workflow has no
reliable context exposing its own commit (`github.workflow_sha` resolves
to the
**caller's**), which is what forces the hardcode in the first place.

`standards#946` fixed `scripts/update-actions-lock.sh` so advisory
findings stop
counting toward the blocking tally — and did not bump pin 3. So every
caller
kept being judged by the **pre-#946** verifier, including

[`metadatastician/burble#226`](metadatastician/burble#226),
which had bumped its own pin *specifically to pick that fix up* and
still went
red on `governance / Actions lockfile verify`.

Measured, not inferred: the failing job logs `HEAD is now at 4f7f02c`,
and the
two wrappers disagree on the same tree —

| wrapper staged from | `--verify-local` rc | `grep -c
is_advisory_category` |
|---|---|---|
| `4f7f02ca` (what CI ran) | **1** | 0 |
| `e977cc67` (post-#946) | **0** | present |

## Why no existing control caught it

The pin's **shape** was already guarded, correctly:
`tests/test_governance_reusable_shape.sh:63-64` asserts `ref:
[0-9a-f]{40}` and
refuses `ref: main`, scoped to the `actions-lock-verify` job.

Its **currency** was guarded by nothing. A perfectly well-formed 40-hex
SHA can
point at stale tooling, and this one did for the whole life of #946.

That is the guard/consumer trap in its plainest form: **the guard asks
"is this
40 hex characters?", the consumer needs "does this contain today's
verifier?"**

The file already carried a `⚠ BUMP THIS whenever ... changes` comment. A
comment
is not a gate, and this PR is the difference.

Separately, `scripts/tests/governance-reusable-contract-test.sh` bound
its
checkout assertions only to the step named `Checkout the pinned
Standards policy
helpers` — the **dupkey** step. The lock gate is a *different* step,
`Checkout standards for the lock gate`, and the two share the nouns
"checkout",
"pinned" and "standards", so a name-match guard written for one proves
nothing
about the other. It now names the lock-gate step too.

## The predicate, and why it is not the obvious one

The obvious assertion — *the pin contains the working tree's helpers* —
**deadlocks**. A PR that edits a helper would have to pin to its own
merge
commit, which does not exist yet. Unsatisfiable-in-PR is the same
failure class
as a required check that can never report.

So the assertion is:

> the pinned commit must already contain everything on the **compare**
ref,
> path-scoped to the step's own `sparse-checkout:` list.

- **`pull_request`** → compare is the PR's base SHA. A PR that edits a
helper
**passes** (its edit is not on base yet). A PR opened while `main` is
*already*
stale is **forced to bump**, and can, because the needed commit exists.
- **`push` to `main`** → compare is `HEAD`. Red exactly when a helper
change has
just landed and the bump is owed; healed by the very next PR, which the
  `pull_request` run will not let through unbumped.

Under this predicate, **#954 would have been forced to bump after #946
landed**,
and burble#226 would have gone green on its first attempt.

The pin is therefore **one change behind by construction**. That is
inherent, it
is acceptable, and the comment at the pin now says so rather than asking
a human
to remember.

Comparison is **path-scoped**, so a rebase or any unrelated commit
cannot fail
it — only a real divergence in the staged tooling can.

**Scope is read out of the step's own `sparse-checkout:` list, never
hardcoded**,
so adding a file to what the gate stages automatically extends what the
guard
protects. A hardcoded list here would itself be a guard asking a
different
question than its consumer.

## Verification

`scripts/tests/check-lock-gate-pin-freshness-test.sh` — **10 controls**,
each
against a throwaway git repo with real commits, fully offline:

| control | asserts |
|---|---|
| stale pin is refused | rc=1, names `scripts/update-actions-lock.sh` |
| stale report is path-scoped | never names the unrelated file that also
changed |
| fresh pin is accepted | rc=0 |
| unrelated divergence does not fail it | a rebase must not redden the
gate |
| `ref: main` is refused | pinning is the point |
| abbreviated sha is refused | 40-hex only |
| **renamed step fails loudly** | rc=1 — the exact way the contract test
lost its subject |
| **unresolvable pin fails, not skips** | a skip is indistinguishable
from a pass |
| missing `ref:` is refused | would follow the default branch |
| empty staged scope is refused | nothing to compare is not a free pass
|

**Meta-mutant.** Removing the path scoping from the guard
(`git diff --name-only $pin $compare -- $paths` → without `-- $paths`)
kills
**exactly the two controls that assert it**, 8 passed / 2 failed.
Restored, 10/10.

**Contract-test mutants.** `ref: main` → `FAIL: the lock gate is not
staged from
an immutable 40-hex commit`. Renaming the step → `FAIL: governance
workflow has
no step named 'Checkout standards for the lock gate'`. Both rc=1.

Full suite: **all 51 test files pass** on this branch.

The guard **fails the job**. It is not `continue-on-error` and it is not
a
`::warning::`, which cannot fail a job.

## Notes

- `self-test.yml` gains `fetch-depth: 0`. The guard compares two commits
and
**fails rather than skips** on an unresolvable pin, so the history is a
requirement, not an optimisation. This is a `with:` change only — no
`uses:`
  ref moves, so `actions.lock` is untouched.
- The new Self Test step passes the base SHA through `env:`, not by
interpolating an expression into the `run:` body. The repo's own
injection
  scanner (`tests/test_tag_ruleset_canon.sh`) still passes.
- `grep -A N` cannot delimit the step block: it is 19 lines today, so
any fixed
`N` is either short of the `ref:` or long enough to capture the **next**
step's
`ref:` and assert against the wrong pin. Both the guard and the contract
test
  take the range from `- name:` to `- name:` with awk.

## ⚠ This does not turn burble#226 green on its own

`metadatastician/burble#226` pins standards at `e977cc67`, and **that**
copy of
`governance-reusable.yml` still carries `4f7f02ca` at the lock-gate
step. Pin 3
travels with the pinned YAML.

Sequence: **merge this → take the resulting SHA → re-bump burble#226 to
it**
(all 9 sites plus `actions.lock`, transitive `uses:` list re-extracted
against a
positive control) → then #226 can go green.

## Out of scope, filed separately

The **dupkey** pin `317101e0` is also stale — 45 files differ under
`scripts/`
versus `main`. Its `sparse-checkout` is the whole `scripts` directory,
so the
same predicate applied verbatim would be permanently red and useless; it
needs a
scope narrowed to what that step actually executes. Per the stopping
rule that is
an issue with acceptance criteria, not scope for this PR.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

https://claude.ai/code/session_01X3hgXxWm6umMgZkjYyHnnm

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant