Skip to content

docs: land the 8 files #81 was auto-closed without delivering (4 mechanical, 4 need owner rulings) #204

Description

@hyperpolymath

Successor to #81, which was auto-closed by the merge of #185 (a Closes #81
reference, one second after mergedAt) rather than by anyone deciding it was
done. Several of its items genuinely are done. Eight files are not, and closing
the issue removed the only record of them.

Verified absent from origin/main (14df4227, 2026-07-28)

File Kind
ARCHITECTURE.adoc mechanical — an index, not new prose
FAQ.adoc mechanical
SECURITY-ADVISORIES.adoc mechanical
.well-known/humans.txt mechanical
GOVERNANCE.adoc needs owner decisions
CODEOWNERS-POLICY.adoc needs owner decisions — and exposes a live violation
.well-known/security.txt needs one owner decision — and arms a gate
.well-known/ai.txt needs an owner licence ruling

Two corrections to #81's framing, both worth having on record:

  • .well-known/ already exists — it holds void.rdf and void.ttl (VoID
    dataset descriptors, unrelated). The three text files go alongside them.
  • MAINTAINERS.adoc already exists at root. Anything claiming to add a
    MAINTAINERS file is adding a duplicate in the wrong format — and one such
    file did in fact appear in an unpushed local sweep commit, which is part of why
    this needed re-measuring rather than trusting the issue text.

Already done (so scope stays honest)

EXPLAINME.adoc, CHANGELOG.adoc (single, no dual-CHANGELOG violation),
.github/FUNDING.yml, and the crate-doc item closed by #185.

What each mechanical file should contain

  • ARCHITECTURE.adoc — an index pointing at what already exists
    (docs/architecture/abi-ffi.md, docs/architecture/topology.md,
    docs/vcl-architecture.adoc, docs/VCL-SPEC.adoc, the deployment/drift/
    normalisation docs), not a re-telling. Note the architecture decision
    records are already written: .machine_readable/6a2/META.a2ml carries
    AD-001…AD-007 as decision/rationale/source triples. Transcribe them as a table
    and cite the a2ml as canonical. Narrative source is .claude/CLAUDE.md, which
    is tracked and public — contrary to Docs max-out vs standards — 8 missing files + 2 violations (Silver→Gold) #81's assumption that it was private.
  • FAQ.adoc — answers already exist, scattered: EXPLAINME.adoc,
    README's "How It Compares", docs/vcl-vs-sql.adoc, KNOWN-ISSUES.adoc,
    docs/business/pr/faq.adoc. Harvest, don't re-answer.
  • SECURITY-ADVISORIES.adoc — model on standards/SECURITY-ADVISORIES.adoc
    (Closed / Deferred-with-reason, per-advisory exposure, explicit re-evaluate
    trigger). Nine advisories are closed; one is openGHSA-4w2j-m93h-cj5j
    quinn-proto, high, remote memory exhaustion, 2 alert instances. State plainly
    that there are no researcher credits yet rather than omitting the section.
  • .well-known/humans.txt — team from MAINTAINERS.adoc; stack from the
    README structure plus .claude/CLAUDE.md's language policy.

Owner decisions blocking the other four

  1. GOVERNANCE.adoc — TPCF perimeter: does verisimdb sit at P1 (Trusted
    Core) or P3? Given formal/*.v Coq proofs and the SPARK/ZKP work, P1 is
    arguable, but it is a ruling, not a derivation. Also: succession/bus-factor
    clause, and whether the template's 72h / 1-week discussion windows are real
    commitments here. Should reference the existing MAINTAINERS.adoc, not
    restate it. Note the governance gate checks only README/LICENSE/CONTRIBUTING,
    so nothing forces this file's content — it is policy-driven.
  2. CODEOWNERS-POLICY.adoc — writing this while .github/CODEOWNERS stays
    as-is would be self-contradictory. It currently has * @hyperpolymath and
    /.github/ @hyperpolymath plus further self-ping path lines — precisely the
    two shapes the estate policy's Rule 1 bans for solo-owned repos, and a known
    contributor to notification flooding. Either fix CODEOWNERS in the same
    change (recommended) or write down an explicit exemption.
  3. .well-known/security.txt — the only open field is Expires:. Be aware
    this arms a gate: the governance wellknown job currently only warns
    that the file is missing, but once it exists it hard-errors on a missing or
    past Expires. So adding this file schedules a future red. Suggest
    2027-07-31, plus a renewal reminder and an inline comment so the next
    maintainer knows the eventual failure is by design.
  4. .well-known/ai.txt — the available estate model cites a Palimpsest/MIT
    stance, but verisimdb is MPL-2.0 code + CC-BY-SA-4.0 prose, and
    META.a2ml AD-006 records "MPL-2.0 across the workspace (no AGPL)". Ruling
    needed: adopt Palimpsest conditional-training terms, or a plain
    MPL/CC-BY-SA attribution stance? Do not copy the model file unexamined.

Constraints for whoever writes these

  • Never write the string VeriSim Query Language. tests/doc-consonance-gate.sh
    fails the build on it in any *.adoc/*.md/*.a2ml. Write VeriSim
    Consonance Language (VCL)
    .
  • House style: // SPDX-License-Identifier: CC-BY-SA-4.0 + copyright, = Title,
    :toc: left. REUSE.toml already globs **/*.adoc → CC-BY-SA-4.0 and
    .well-known/** → MPL-2.0, so the .txt files take MPL-2.0 — don't fight it.
  • reuse lint must stay compliant (776/776 on main today, +8 with these).

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationDocs, prose, diagrams, READMEs, ADRs

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions