docs: make AsciiDoc canonical for CONTRIBUTING/GOVERNANCE/MAINTAINERS

[hyperpolymath]

Closes #68. Advances #63 (owner action below) and #79 (skeleton only; stays open).

What

• CONTRIBUTING: the .md was un-instantiated template rot — opened mid-code-fence, raw {{MAIN_BRANCH}} token, a repository tree with five nonexistent directories, ended mid-block. Real content rewritten into CONTRIBUTING.adoc (actual tree, docs/TOOLCHAIN.adoc + .tool-versions toolchain, proof-gate discipline); .md deleted; README link updated.
• GOVERNANCE / MAINTAINERS: inverse situation — the .adoc twins are the rich repo-specific docs; the generic stubs (GOVERNANCE.md, bare MAINTAINERS) deleted.
• Docs: developer / maintainer / end-user learning paths (beyond setup + basic run) #79 skeleton: docs/learning-paths/README.adoc seeds the end-user/developer/maintainer outline.

Owner action — .claude/CLAUDE.md replacement (#63)

The file is agent-edit-blocked (self-modification guardrail). Please replace its contents with the text below, which fixes: the six .scm references (now .machine_readable/6a2/*.a2ml), the phantom guix.scm/deno.json claims, and the foreign language-policy table (AffineScript/Deno/Tauri — a different project's stack).

## Machine-Readable Artefacts

Structured project metadata lives in `.machine_readable/6a2/` (A2ML format):

- `STATE.a2ml`     - Current project state and progress
- `META.a2ml`      - Architecture decisions and development practices
- `ECOSYSTEM.a2ml` - Position in the ecosystem and related projects
- `AGENTIC.a2ml`   - AI agent interaction patterns
- `NEUROSYM.a2ml`  - Neurosymbolic integration config
- `PLAYBOOK.a2ml`  - Operational runbook
- `0-AI-MANIFEST.a2ml` - Manifest

Contractiles live in `.machine_readable/contractiles/`.

---

# CLAUDE.md - AI Assistant Instructions

## This Repo's Stack (all pinned in .tool-versions)

| Language/Tool | Use Case |
|---------------|----------|
| **OCaml 5.1.1 + dune** | The Oblíbený compiler (lib/, bin/, test/) |
| **Idris2 0.7.0** | ABI proof layer (src/abi/, oblibeny-abi.ipkg) |
| **Zig 0.13** | Crypto FFI + obli-pkg (ffi/zig/); 0.14+ breaks callconv(.C) |
| **just** | Task runner — all operations go through the justfile |
| **Bash/POSIX shell** | Scripts, kept minimal |
| **Guile Scheme** | Root spec files (ANCHOR*.scm, SPEC*.scm, AUTHORITY*.scm) |

Do not introduce Node/npm/TypeScript/Python/Go — this repo has no JS/Python
surface and the estate bans them as replacements-available.

## The Proof Gate (non-negotiable)

- CI (`ci.yml`) builds the OCaml language, runs the conformance suite,
  type-checks (= proves) the Idris2 ABI layer, compile-checks the Zig FFI,
  and rejects soundness escape hatches (`believe_me`, `postulate`,
  `assert_total`, `partial`, `idris_crash`, holes) in `src/abi/Crypto.idr`
  and `src/abi/Packages`.
- Local mirror: `just ci` + `just proofs`. Never weaken a proof to make
  a change pass.

## Packaging

- Containers: `Containerfile.bootstrap` / `Containerfile.minimal` /
  `Containerfile.liboqs` (podman-first).
- `flake.nix` is legacy (estate ruling: Guix-only; a `guix.scm` migration
  is an open follow-up).

## Security Requirements

- No MD5/SHA1 for security (use SHA256+)
- HTTPS only (no HTTP URLs)
- No hardcoded secrets
- SHA-pinned dependencies (actions included)
- SPDX license headers on all files

Suggested follow-up issue rather than folding in here: "packaging: replace flake.nix with guix.scm" (Nix-retired estate ruling).

Note: CONTRIBUTING.adoc links docs/TOOLCHAIN.adoc, which lands in PR #108 — merge that first (they're ordered #108 → #109 → #110 → this).

🤖 Generated with Claude Code

[gitar-bot]

Note

Automatic reviews are paused because your trial's included automatic processing has been used for this period. Upgrade now, or comment "Gitar review" to run a review anytime.
Learn more

Code Review ✅ Approved 1 resolved / 1 findings

Standardizes documentation by making AsciiDoc canonical for CONTRIBUTING, GOVERNANCE, and MAINTAINERS. Consider ensuring referenced files like docs/TOOLCHAIN.adoc and GOVERNANCE.adoc exist to prevent broken links.

Auto-approved and auto-merge armed: No blocking issues found.
Please see Auto-approve Docs for details on setting custom approval criteria. — merges when pipeline and required approvals pass.

✅ 1 resolved

✅ Quality: CONTRIBUTING.adoc links docs/TOOLCHAIN.adoc which does not yet exist

📄 CONTRIBUTING.adoc:19-21 📄 CONTRIBUTING.adoc:41-42
CONTRIBUTING.adoc uses link:docs/TOOLCHAIN.adoc[...], but that file is absent from the current branch (it is slated for PR #108). If this merges before #108, the link renders as a dangling cross-reference. Ensure #108 lands first, or gate the merge order as the PR description notes.

Options

Display: compact → Showing less information.

Comment with these commands to change the behavior for this request:

Compact

gitar display:verbose

---

Important

Your trial ends in 6 days — upgrade now to keep code review, CI analysis, auto-apply, custom automations, and more.

_{Was this helpful? React with 👍 / 👎 | Gitar}

[gitar-bot]

⚠️ Gitar auto-approved this PR but could not enable auto-merge: auto-merge is disabled for this repository — enable "Allow auto-merge" in the repository settings.

[gitar-bot]

Gitar has auto-approved this PR and enabled auto-merge (configure)

✅ All code review findings resolved.

_{Configure merge blocking}