docs: de-conflate Tangle from KRL; drop two dead Jekyll Pages workflows - #78
Merged
Conversation
Tangle, KRL and QuandleDB are three separate projects that share a subject matter. Documentation here presented Tangle as the substrate of a KRL compilation stack, which is not true in either direction. README.adoc * Retitled from "Tangle / KRL — Topological Programming Language" to "Tangle — a general language for knot mathematics". Removed "Tangle (via KRL — Knot Resolution Language) is ..." from the opening sentence and the "Tangle/KRL" framing from the status and summary sections. * Removed the architecture ladder KRL -> TangleIR -> Tangle core -> QuandleDB + Skein.jl. `TangleIR` appears in NO source file in this repository (0 hits across .rs, .zig and .lean) and in NO source file in the KRL implementation. It existed only in prose, in both repositories. * Removed the "== KRL — Knot Resolution Language" section, which restated KRL's four operations as though KRL were this project's surface language. Replaced with a "Relationship to KRL and QuandleDB" section stating the three projects' actual boundaries. The relationship is left intact — what is removed is a claimed architectural dependency that does not exist. * Strengthened the formal-core section with a result rather than a claim: the repository's own oracle, `cd proofs && lean Tangle.lean`, was executed on 2026-07-21 and exits 0. The proofs are self-contained (Tangle.lean has no import lines, so no Mathlib) and contain 0 `sorry` and 0 `axiom` across 2,128 lines, with progress, preservation, determinism, type_safety, infer_sound, infer_complete and infer_iff_hasType all carrying real proof terms. "Builds" and "proved" coincide here, which is not automatic. * Added an explicit note that only the Lean proofs are CI-gated: the OCaml compiler, the Rust components and the Zig components are built by no workflow. AFFIRMATION.adoc * Appended an erratum rather than editing the text. An affirmation is a dated claim about a past state; amending it in place would falsify a record. * Corrects the "maintainer-confirmed" stack KRL -> TangleIR -> VerisimCore -> Skein/QuandleDB, and flags that the quotable one-line characterisation should not be quoted while it describes Tangle as "the ... TangleIR of the KRL stack". * Discharges one of the affirmation's own acknowledged gaps. It recorded "OCaml + Lean not run (absent)" and concluded "structure + the repo's proof records are confirmed, not a fresh green build". The Lean half of that gap is now closed, with the command and exit code recorded. READINESS.md — grade C -> D * Grade C means self-validated in the home context, and the D -> C trigger is "dogfood it hard in the home context". The assessment cited exactly one piece of dogfooding evidence: "Used internally as host for the KRL DSL". That is false, so C is unsupported. * "CI: Clean" was also false — main was failing Governance and both Jekyll Pages workflows. * The 8 OCaml test suites under compiler/test/ are real but are run by no workflow, so their passing state is unverified by this repo's own CI. * Recorded the verified Lean result as the evidence that does hold, and named the cheapest uplift: add a workflow that runs `dune build && dune test`. dialects/README.md * Removed KRL from the dialect table. It was listed as a dialect that had "graduated" to its own repo; it was never a Tangle dialect. * Replaced the dead absolute path /var/mnt/eclipse/repos/krl with the GitHub URL. * Dropped "wire through to TangleIR" from the maturation pattern, and noted that no dialect has yet made that journey, so there is no precedent. * Softened the multi-DSL-host claim: the sketches set out what such a host would cover, but nothing is implemented and nothing is built on Tangle, so they do not yet evidence it. Workflows * Deleted .github/workflows/jekyll.yml and .github/workflows/jekyll-gh-pages.yml. Both are GitHub's sample Jekyll workflows; this repository has no _config.yml and no Gemfile, so there is no Jekyll site to build and both fail on every push to main. pages.yml (Ddraig SSG, landed in #73) is the real one, and three workflows were competing for the same Pages deployment. NOTE: pages.yml will still fail at the deploy step. Its build succeeds and certifies a11y, but GitHub Pages is not enabled for this repository — /repos/hyperpolymath/tangle/pages returns 404, which surfaces as "HttpError: Not Found / Creating Pages deployment failed". That is a repository setting, not a code change, and is left for the owner.
…tandards pins Both Governance failures on this branch are the same two faults found and fixed in krl (#56), so the same remedy applies here. Workflow security linter * pages.yml carried no SPDX header. Every other workflow in the repo has one; this was the only omission. Added. * pages.yml used floating tags where every other workflow pins by SHA: actions/checkout@v7 -> 3d3c42e5... # v7 actions/upload-pages-artifact@v5 -> fc324d35... # v5 actions/deploy-pages@v5 -> cd2ce8fc... # v5 Kept on the same major versions, so this changes pinning only, not behaviour. Check Workflow Staleness * governance-reusable.yml, hypatia-scan-reusable.yml and scorecard-reusable.yml were pinned at d7c22711e830 — 63 commits / 24 days behind standards HEAD, outside the gate's recency window. Refreshed to f9dca6ded2cad8ab54044c1cb0489b558ae2682b (full 40-char SHA). Not touched: mirror-reusable.yml (d135b05) and secret-scanner-reusable.yml (c65436e). Neither was flagged, and the secret-scanner pin should not move independently of the gitleaks allowlist work. Verified: all workflows carry an SPDX header; no unpinned third-party actions remain; actionlint 0 errors.
Refreshing hypatia-scan-reusable.yml to standards HEAD turned the run into a
startup_failure — zero jobs, no log. The newer reusable declares
permissions:
contents: read
security-events: write
because it uploads SARIF, while the caller granted security-events: read. A
called workflow cannot escalate beyond its caller's grant, so GitHub rejects
the whole run at parse time rather than failing a job.
This is the failure mode where refreshing a pin BREAKS a caller that was
previously fine: the old pin needed only read. Checked the other two bumped
reusables the same way — governance-reusable and scorecard-reusable both
declare only contents: read, which the callers already grant, so no change
was needed there.
hyperpolymath
marked this pull request as ready for review
July 21, 2026 17:13
hyperpolymath
added a commit
that referenced
this pull request
Jul 29, 2026
Closes both acceptance criteria of #56 — though the second was already satisfied, and the first was mis-scoped. ## Criterion 1 — template residue The issue recorded *"5 `{{PLACEHOLDER}}` files + 8 `rsr-template-repo` references"*. Re-measured: **8** files matched `{{...}}` and **21** lines matched the template name — but most were **meta-references**: files *describing* the debt, not carrying it. Three would have been damaged by a naive search-and-replace: | File | Why it must not be touched | |---|---| | `src/rust/src/eval.rs` | `"...add{{}} block"` is a Rust `format!` **escape** — `{{}}` renders as a literal `{}`, naming the `add{}` language construct. Working code. | | `methodology.a2ml` | The token appears inside `reject-if-contains` — the rule that *forbids* it. | | `AFFIRMATION.adoc`, `docs/identity-fabric/` | Prose recording the debt. | **The genuine residue, now cleared:** `{{DEPS}}`, `{{BUILD_OUTPUT_PATH}}`, `{{PACKAGE_NAME}}`, `{{LANG_STACK}}`, `{{BUILD_CMD}}`, `{{TEST_CMD}}`, `{{MUST_INVARIANTS}}`, `{{PROJECT_UNIQUE_STRENGTH}}` — plus four contractiles and the citation guide whose **subject was still the template**. `Intentfile` asserted *"This repository is the canonical template for Rhodium Standard Repository compliance"*; `CITATIONS.adoc` credited *"Polymath, Hyper"* for *"RSR-template-repo"* in all five citation formats. ## A worse class, found while fixing it All three QUICKSTARTs documented commands that **do not exist** — `just build`, `just test`, `just lint`, `just panic-scan`, `just setup-dev`, `just build-release`, `just install`, `just run`, `just heal`, `just setup`, `just uninstall`, `just stapeln-run` — asserted an `$XDG_CONFIG_HOME/tangle/config.toml` the compiler never reads, and carried a *"Multi-Instance Deployment"* section for what is a single stateless binary. Documentation that fails when followed is worse than none. Every command now shown is verified to exist, and the worked example shows the **real** output (8 `assertion passed` lines, exit 0) rather than the template's invented `Tangle started successfully.` ## Criterion 2 — already satisfied by #78 `README.adoc` carries the correction and `AFFIRMATION.adoc` has *"Erratum — 2026-07-21 / Correction 1 — the stack does not exist"*. Worth noting: the criterion as worded — *"does the simplified diagram supersede, or re-state, the nuance?"* — presupposed the stack was real. **Both options were wrong.** `KRL → TangleIR → …` describes a dependency that never existed (`TangleIR` appears in no source file in either repo). It was withdrawn, not reconciled. ## Making the rule real `methodology.a2ml` has always declared `reject-if-contains = [..., "rsr-template-repo"]` — and **nothing enforced it**, which is precisely how the contractiles stayed mis-instantiated. Adds `scripts/check-rsr-instantiation.sh` (plus `just rsr-check` and a CI step), using an explicit allowlist so meta-references and the Rust escape aren't false-positived. **Verified adversarially:** | Attack | Caught | |---|---| | Reintroduce a `{{PLACEHOLDER}}` | ✅ | | Claim to be `rsr-template-repo` | ✅ | | Document a phantom `just` recipe | ✅ | | Rust `format!` escape `add{{}}` | ✅ correctly **ignored** | It earned itself immediately: on first run it flagged `QUICKSTART-USER.adoc`, a file I had not inspected, with six phantom recipes. ## Also `AFFIRMATION.adoc` gains a dated **Erratum — 2026-07-29** (Corrections 3–5) recording the residue clearance, that the OCaml compiler is no longer unbuilt (#87/#89 — the previous erratum's closing line said it was), and that `==` is no longer list equality (#50/#87). All gates pass locally: build, corpus, rsr-check, `must-check`, `trust-verify`. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
This was referenced Jul 29, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The tangle half of a coordinated two-repo de-conflation pass. The krl half is hyperpolymath/krl#53 (merged) and hyperpolymath/krl#54.
The three projects are separate
Tangle is a general language for knot mathematics — topological, algebraic, geometric, logical. QuandleDB is a knot database. KRL is QuandleDB's resolution language, developed jointly with it. They share a subject matter, not an architecture.
Documentation here presented Tangle as the substrate of a KRL compilation stack. That is false in both directions, and the connecting layer does not exist:
The relationship between the projects is left intact. What is removed is a claimed architectural dependency that was never built.
README.adoc
KRL → TangleIR → Tangle core → QuandleDB + Skein.jlladder.== KRL — Knot Resolution Languagesection, which restated KRL's four operations as though KRL were this project's surface language.The formal core is real — and now verified
I ran the repository's own documented oracle:
lean Tangle.lean(pinnedleanprover/lean4:v4.14.0)sorrycountaxiomcountimportlinesprogress,preservation,determinism,type_safety,infer_sound,infer_complete,infer_iff_hasTypeThis is worth stating precisely: an
axiomstub compiles cleanly while proving nothing, so "the Lean build is green" and "the theorems are proved" are different claims in general. Here they coincide, and that was checked rather than assumed. This is Tangle's strongest asset and the README now leads with it.AFFIRMATION.adoc — erratum, not edit
An affirmation is a dated claim about a past state (
102499d, 2026-06-19); amending it in place would falsify a record. So the original text is untouched and an erratum is appended. It corrects the "maintainer-confirmed"KRL → TangleIR → VerisimCore → Skein/QuandleDBstack, and flags that the quotable one-line characterisation shouldn't be quoted while it calls Tangle "the … TangleIR of the KRL stack".It also discharges one of the affirmation's own acknowledged gaps — it recorded "OCaml + Lean not run (absent)" and concluded "structure + the repo's proof records are confirmed, not a fresh green build." The Lean half is now closed, with command and exit code recorded.
READINESS.md — Grade C → D
Grade C means self-validated in the home context; the
D → Ctrigger is "dogfood it hard in the home context." The assessment cited exactly one piece of dogfooding evidence:That is false — KRL is not built on Tangle. With it withdrawn, C is unsupported. Two further corrections:
mainwas failing Governance and both Jekyll workflows.compiler/test/, but no workflow invokesduneorcargo test.The cheapest available uplift is named explicitly: add a workflow running
dune build && dune test. Eight suites already exist and nothing executes them.dialects/README.md
/var/mnt/eclipse/repos/krl(another machine) with the GitHub URL.Workflows — two deleted
jekyll.ymlandjekyll-gh-pages.ymlare GitHub's sample Jekyll workflows. This repo has no_config.ymland noGemfile— there is no Jekyll site to build, so both fail on every push.pages.yml(Ddraig SSG, #73) is the real one; three workflows were competing for the same Pages deployment.pages.ymlwill still fail at the deploy step after this PR. Its build succeeds and certifies a11y, but:which surfaces as
HttpError: Not Found / Creating Pages deployment failed. The same is true ofhyperpolymath/krl. Pages needs enabling with source = GitHub Actions on both. That publishes a public site, so I've left it to you rather than doing it.Verified on this branch
actionlint0 errors ·asciidoctorrendersREADME.adocandAFFIRMATION.adocclean ·lean Tangle.leanexit 0