docs(#204,#113,#86) + security(#203): the seven open issues, re-measured — estate docs, a link gate that can be proved to fail, and a shell removed from VCLTGate

[arena-ai-coding-agent]

Summary

Worked from a measured census of the seven open issues rather than their issue bodies — see ULTRAPLAN-2026-09-27.adoc. The headline finding is that most of the blocking work in #113 and #203 was already done on main and nobody closed the issues: all five of #113's REUSE items and all three of #203's P1 items were already resolved. This PR re-measures that, lands the work that genuinely remained, and adds a gate so the documentation cannot silently rot again.

Four commits, grouped by nature of change:

Commit	Scope
5524c3f	security(#203) — remove the shell from the VCLTGate invocation path
ff22d14	docs(#204,#113,#86) — add the missing estate documents; correct docs that contradicted the implementation
d997490	ci(#204) — fail-closed relative-link gate plus a positive control that proves it can fail
689a704	docs(#204,#113) — CONTRIBUTING.adoc, which had drifted further than README.adoc

What changed

Security — VCLTGate no longer shells out (#203)

invoke_gate/2 ran the gate binary through sh -c "<path> < <tmp>". Because a shell redirection takes a filename rather than a stream, the payload had to be written to an exclusively-created 0o600 temp file first, which pulled in write_secure_payload!/2 (collision retries, :crypto.strong_rand_bytes, chmod-before-write), shell_quote/1, and an after File.rm/1 — roughly 45 lines of security-sensitive machinery whose only job was to work around a shell feature we did not need.

System.cmd/3's :input writes the payload straight to the child's stdin, so all of that is deleted. path becomes argv[0] and is never a shell word.

The removed code was not buggy — shell_quote/1 was a sound POSIX single-quote escape and neither the statement nor the schema ever reached the shell. But "correct quoting" has to be re-verified on every edit to this function, whereas "no shell" cannot regress.

The test was rewritten rather than adapted. It asserted an unpredictable vcltgate_*.json at mode 600 — properties of the deleted mechanism. It now asserts the underlying guarantee: that shell metacharacters (' ; | & backtick $(...) > newline tab) in the statement and schema arrive on stdin byte-for-byte, so if any part of the invocation ever passed through a shell again, at least one would be consumed, expanded or split.

Also corrected the quinn-proto note in Cargo.toml, which still described an open transitive chain and said we were "waiting for burn 0.21 stable". burn was removed in 0.2.0 — the chain is gone and there is nothing to wait for. It contradicted deny.toml and would have sent the next maintainer to wait on an unneeded release.

A link gate that can be proved to fail (#204)

A gate that passes on a tree with zero broken links is indistinguishable from a gate that does nothing. So this lands as a pair:

• scripts/check-doc-links.sh — resolves every relative link: target in *.adoc (and [text](target) in *.md) against the working tree.
• scripts/doc-links-allowlist.txt — exemptions with a required reason. Currently empty: nothing is exempt. A separate file means silencing a link is a visible, reviewable diff rather than an inline comment nobody reads.
• tests/doc-links-gate.sh — positive control, modelled on the existing assail-classifications-gate.sh pattern so it is idiomatic here. Asserts four things: the real tree resolves, a planted broken link is rejected, the rejection names the planted target and its resolved path, and a resolving sibling in the same file is not flagged.

Current state: 364 relative links resolve across 101 documents, 0 exempt.

Wired into doc-consonance.yml (renamed Documentation Gates). No new actions, so actions.lock needs no change — which matters, because SHA-pinning workflows sits inside the P1 carve-out of the TPCF perimeter and is not this branch's to touch.

Documents added (#204, #86)

standards' check-docs-presence.sh blocks only on README/LICENSE and warns on CONTRIBUTING, so the absence of these was invisible to CI:

• ARCHITECTURE.adoc — an architecture index, not a duplicate of docs/architecture/: component map, the AD-001…AD-007 register transcribed from .machine_readable/6a2/META.a2ml (which stays canonical), and a "read this next, by question" table.
• FAQ.adoc — short answers with pointers, harvested from existing documents rather than re-answered, so it cannot become a second source of truth.
• SECURITY-ADVISORIES.adoc — advisory triage log modelled on standards' 3-practice version: closed / deferred-with-reason, per-advisory exposure table, explicit re-evaluate trigger on each deferral.
• .well-known/{humans,security,ai}.txt — RFC 9116 contact and Expires: 2027-09-27T00:00:00Z pointing at the GitHub private-advisory URL. ai.txt follows standards' live www/.well-known/ai.txt (MPL-2.0/CC-BY-SA-4.0), not templates/' MIT+Palimpsest variant, whose licence does not match this repo.
• docs/architecture/snifs-bridge.adoc — the SNIFs verisim WASM bridge — single boundary for BEAM-side cross-language access #86 scope analysis, written against measured upstream constraints: no WASI, no filesystem, no sockets, wasm32-freestanding, only i32/i64/f32/f64 and bytes cross the boundary.
• GOVERNANCE.adoc — amended to v2.0.0 for the TPCF perimeter: P3 Community Sandbox with a P1 carve-out for signing keys and the proof core.

Documentation that contradicted the implementation

Every correction below was measured against 681d635 on 2026-09-27, not asserted:

• docs/VCL-SPEC.adoc — the implementation table named src/vql/VQL{Parser,Types,Bidir,Error,Explain}.res, files that do not exist. Residue from two completed migrations (vql→vcl, ReScript→AffineScript; zero .res files remain, 32 .affine do). Counts had drifted hard: vcl_executor.ex documented at 1162 lines, actually 2310. Six unlisted src/vcl/ modules added.
• docs/vcl-vs-sql.adoc — claimed VCL is read-only, contradicting statement = query | mutation ; in the normative grammar and three implemented mutation parsers. VCL-SPEC.adoc had already logged this as known inconsistency Theorem-alignment RDF schema for cross-prover porting (Phase 3 landing target) #3. Also: "6-core" → eight-modality (the same paragraph already enumerated eight stores); GROUP BY / ORDER BY / aggregates / HAVING listed as unsupported although the grammar defines all four; and the six PROOF types listed were not the grammar's six.
• AUDIT.adoc — claimed "all 25 catalogued issues are resolved", an overclaim in the one document whose job is to be the honest audit trail. Actually 31 catalogued, 28 resolved, 3 open, each now named. Also named STATE.scm/META.scm/ECOSYSTEM.scm, which have never existed here.
• README.adoc — structure block rewritten against the real tree; test counts corrected from "510+"/"160+" to the measured 694 Rust (437 #[test] + 257 #[tokio::test]) and 680 Elixir; KNOWN-ISSUES summary claimed "25/25 resolved".
• CONTRIBUTING.adoc — claimed "14 workspace members" where Cargo.toml declares 18; omitted verisim-provenance, verisim-spatial, verisim-nif; described verisim-tensor as Burn-backed; called the octad a "6-modal entity"; listed a root contractiles/ that does not exist. Its language table accepted ReScript while the adjacent "Not Accepted" list told contributors to use AffineScript.
• docs/INDEX.adoc — added eight root documents that existed but were never indexed; removed the v-api-gateway/ row (no such directory).
• .machine_readable/6a2/STATE.a2ml — named ReScript and Burn, both gone.
• debugger/Cargo.toml — repository pointed at hyperpolymath/verisimdb-debugger, which is a 404. The crate lives in-tree.
• Removed TEST_CI_VERIFY.adoc — a scratch artefact saying "delete after verification", renamed .md→.adoc instead of deleted. No inbound references.

Two divergences flagged, not resolved

Both need an owner decision, because resolving either would silently pick a winner in a decision that is not a documentation edit.

1. Two copies of the normative grammar are committed — spec/grammar.ebnf and docs/vcl-grammar.ebnf, byte-identical in substance. Two normative grammars is a drift hazard. Both now carry a notice naming spec/ canonical (it has the @taxonomy tag and is the copy README, EXPLAINME, 0-AI-MANIFEST.a2ml and spec/system-specs.adoc cite) and requiring any edit to land in both. Consolidating means deleting a normative artefact — your call. Also fixed a stale "VQL" comment in spec/.

2. docs/vcl-vs-vcl-dt.adoc proof types — names CONSISTENCY/FRESHNESS/AUTHORIZATION, which are not grammar terminals, and omits the grammar's CITATION/ACCESS/CUSTOM. A WARNING block now states the mismatch at the point of divergence; its six subsections were not rewritten, because either direction decides whether the grammar is right (and those were never implemented) or the page describes an intended v-next proof set (and the grammar is behind).

VCL-SPEC.adoc's known-inconsistencies list is updated to record #1 and #3 as closed in the source documents and #2 as open pending that decision.

Verification

Gates that ran here, on the final committed tree:

Gate	Result
reuse lint (REUSE 3.3)	809 / 809 green
tests/doc-consonance-gate.sh	PASS
scripts/check-doc-links.sh	PASS — 364 links / 101 docs, 0 exempt
tests/doc-links-gate.sh (positive control)	PASS, 4/4
tests/assail-classifications-gate.sh	PASS, 12 keys resolve + control fires
.githooks/validate-a2ml.sh	32/32, 0 errors, 0 warnings
bash -n on touched scripts	PASS

The one pre-existing validate-a2ml.sh warning (6a2/0-AI-MANIFEST.a2ml missing an SPDX header) was fixed, not suppressed.

A gate defect worth your attention

doc-consonance-gate.sh runs git grep, which searches the index, not the working tree. Every document added by this branch was untracked while being written, so that gate reported PASS throughout — and then failed the moment the files were committed, on FAQ.adoc and on the ULTRAPLAN. Two earlier PASS results were therefore measured against a tree that excluded the very files being added.

A gate blind to new files is silent precisely when new prose appears, which is when it is most needed. This was caught only because the sweep was re-run after committing. scripts/check-doc-links.sh does not share the defect — it walks the filesystem.

Both failures were resolved differently, on purpose. The ULTRAPLAN quoted the misnomer in a results table describing the gate in the gate's own words — that added nothing, so it was reworded. FAQ.adoc quotes it to explain that the name is Consonance and not Query; naming the thing being retired is the substance of that answer, which is the exact case the gate's ALLOW list exists for, so FAQ.adoc was added to it with the reasoning inline. That exemption is file-scoped, not line-scoped — a pre-existing coarseness in the gate's design — and a positive control confirms it is still narrow: a misnomer planted in a non-exempt file is caught.

Changing the gate's traversal is a gate-semantics decision, so it is recorded as a follow-up rather than done here.

Not verified — please read before merging

No rustc, cargo, erl, elixir, mix or coqc is installable in the environment this branch was written in. rustup.rs, static.crates.io, index.crates.io, forge.rust-lang.org, hex.pm, repo.hex.pm, erlang.org, opam.ocaml.org and the Debian/LLVM mirrors are all unreachable, and apt-get update is both permission-denied and unreachable.

Consequences:

• The vclt_gate.ex change in 5524c3f is written but not compiled. mix test and mix format --check-formatted have not run. It is the only change here whose correctness rests on reading the System.cmd/3 documentation (:input since Elixir 1.13; mix.exs requires ~> 1.17) rather than on a gate that executed. The payload keys the test asserts (schema_version, statement, schema) were checked by reading run_gate/3, and check/2 exists via def check(statement, schema \\ %{}) — but CI is the first real compiler of this file. If you would rather not carry an uncompiled change, reverting that one file leaves the rest of the branch standing on its own.
• The workflow YAML was inspected, not machine-validated — no yaml module was importable and PyPI was blocked at the time. It adds no new action, so actions.lock is unaffected.
• No Rust or Coq source is changed. The Cargo.toml / debugger/Cargo.toml edits are comments and metadata only, and are not compiled here.

Per-issue status

Deliberately no auto-closing keywords — the calls below are recommendations, and #79/#84/#78 in particular should stay open.

Issue	Status	Recommendation
#204 docs: the 8 files	All eight written; link gate landed with positive control; doc drift corrected repo-wide	Close
#203 security: panic-attack sweep	All 3 P1 items were already resolved on main (re-verified); flake.nix finding gone and guix.scm now exists; vclt_gate hardened; 2 Critical HardcodedSecret suppressions re-verified as example-/minioadmin placeholders	Close after CI compiles the Elixir change
#113 checkpoint 2026-06-05	All five REUSE items were already resolved; TEST_CI_VERIFY.adoc deleted; .scm→.a2ml drift fixed	Keep open — the estate-canonical .machine_readable/ subdirs (ai, compliance, configs, integrations, policies, scripts) are still absent and this PR does not create them
#86 cross-language bridge	Design doc with a scope verdict, no code	Keep open — see below
#79 test expansion	Re-measured only; blocked by the missing toolchain	Keep open
#84 staged rename	Not addressed, though doc references now use the new names	Keep open
#78 DB-theory gaps	Not addressed	Keep open

On #86: the verdict is that routing the API gateway or the stores through WASM is impossible, not merely unwritten. SNIFs guests are wasm32-freestanding with no WASI, no filesystem and no sockets, so anything needing I/O cannot be a guest. The viable surface is pure-compute kernels only — drift scoring, plan costing, vector distance (best-measured upstream: sum_f32 p50 15 µs), octad checksum — reached as a fourth VERISIM_TRANSPORT value. One thing needs checking before any of it is built: Cargo.toml sets panic = "abort", lto = true and codegen-units = 1, and their interaction with the bounds/overflow checks that make a Rust guest safe is unverified. Upstream's own critical invariant is that -OReleaseSafe is mandatory because ReleaseFast silently produces wrong answers.

On #79: the counts above are measured from source, not from a test run. rust-core/verisim-nif remains the worst-density crate at 0 tests / 135 LOC — but it is an honest stub returning {:error, :not_implemented}, and writing tests for a stub that intentionally does nothing would manufacture coverage rather than add it.

[coderabbitai]

Important

Review skipped

Bot user detected.

To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Advanced

Run ID: 996e4a0a-0807-47a9-8d2f-b53f8385a715

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[arena-ai-coding-agent]

The failing checks on this PR are not caused by this PR

Every workflow on this PR reports startup_failure with 0 jobs created. That includes workflows this branch never touches — rust-ci.yml, elixir-ci.yml, reuse.yml, secret-scanner.yml, dogfood-gate.yml, build-validation.yml, codeql.yml, cflite_pr.yml, bridge-gate.yml, trust-ci, spark-theatre-gate.yml.

The only files this branch changes under .github/ are:

 .github/SUPPORT.md                   |  4 ++--
 .github/workflows/doc-consonance.yml | 19 ++++++++++++++++++-

Evidence that GitHub Actions is broken repo-wide, not on this branch

1. The last successful run anywhere in this repository was 2026-09-27T01:54:54Z — about 10.5 hours before this PR, all six of them on main from the dependabot exqlite bump (Secret Scanner, Mirror to Git Forges, SPARK Theatre Gate, Dogfood Gate, Doc Consonance Gate, Build Validation).
2. Since then, every run — on main and on this branch, push and pull_request alike — is startup_failure or failure. Of the last 30 runs repo-wide: 16 startup_failure, 8 failure, 6 success, and all 6 successes are that single 01:54 batch.
3. REUSE Compliance fails identically here and succeeded on main at 01:54. This branch does not modify reuse.yml at all, so its failure cannot originate from this diff.
4. total_count of jobs is 0 for these runs. A workflow-file problem in one file fails that one workflow; 0 jobs across ~20 unrelated workflows points at the runner/billing layer, most commonly an Actions spending limit or a transient Actions outage.
5. main was already partially broken at 01:54 — rust-ci, CodeQL, hypatia-scan, governance, Lock Sync Gate and scorecard were startup_failure/failure there too. Only some workflows were healthy, and now none are.

The one workflow file this branch does edit parses cleanly

I could not machine-validate YAML while writing this branch (no yaml module importable, PyPI blocked at the time), and said so in the PR description. PyPI became reachable afterwards, so that gap is now closed — all 25 workflow files parse, including the edited one:

OK   .github/workflows/doc-consonance.yml    name='Documentation Gates'  jobs=1
OK   .github/workflows/reuse.yml             name='REUSE Compliance'     jobs=1
OK   .github/workflows/rust-ci.yml           name='rust-ci'              jobs=10
OK   .github/workflows/elixir-ci.yml         name='elixir-ci'            jobs=4
...
0 workflow file(s) with YAML syntax errors

GitHub also read the rename — the run is displayed as "Documentation Gates", the new name: — which confirms it parsed far enough to load the file.

What this means for review

Nothing on this branch has actually been executed by CI. In particular the Elixir change in 5524c3f (vclt_gate.ex) is still unverified by any compiler, and the two new gate scripts in d997490 have not run in CI either. They were verified locally:

Gate	Local result
reuse lint (REUSE 3.3)	809 / 809 green
tests/doc-consonance-gate.sh	PASS
scripts/check-doc-links.sh	PASS — 364 links / 101 docs, 0 exempt
tests/doc-links-gate.sh (positive control)	PASS, 4/4
tests/assail-classifications-gate.sh	PASS, 12 keys resolve + control fires
.githooks/validate-a2ml.sh	32/32, 0 errors, 0 warnings
bash -n on touched scripts	PASS
all 25 workflow YAML files	parse cleanly

Suggested next step: re-run the workflows once Actions is healthy again (gh run rerun or a trivial push), and treat elixir-ci as the real gate on 5524c3f — mix test and mix format --check-formatted have not run against it yet. If you would rather not merge an uncompiled change, reverting that single file leaves the rest of the branch standing on its own.