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
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