RSR audit remediation (workstreams B–F): docs, contractile hole-fix, .adoc conversions, wikis, bot fleet, JNI-bridge tests

.devcontainer/devcontainer.json

@@ -0,0 +1,67 @@
+// SPDX-License-Identifier: MPL-2.0
+// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+//
+// Dev Container configuration for neurophone.
+// Works with: VS Code Dev Containers, GitHub Codespaces, Gitpod.
+// Container runtime: Podman (recommended) or any OCI-compliant runtime.
+//
+// neurophone has no Containerfile (it is a plain Rust workspace), so this
+// devcontainer builds from a base image plus the standard toolchain features
+// rather than a repo-local Dockerfile.
+{
+  "name": "neurophone",
+
+  "image": "mcr.microsoft.com/devcontainers/base:ubuntu-24.04",
+
+  "features": {
+    "ghcr.io/devcontainers/features/rust:1": {},
+    "ghcr.io/devcontainers/features/git:1": {
+      "ppa": false,
+      "version": "latest"
+    },
+    "ghcr.io/jdx/devcontainer-features/just:1": {},
+    "ghcr.io/nickel-lang/devcontainer-feature:0": {}
+  },
+
+  // Warm the dependency cache; tolerant of offline / restricted-egress builds.
+  "postCreateCommand": "cargo fetch || true",
+
+  "containerEnv": {
+    "EDITOR": "code --wait",
+    "LANG": "C.UTF-8"
+  },
+
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "EditorConfig.EditorConfig",
+        "eamodio.gitlens",
+        "rust-lang.rust-analyzer",
+        "streetsidesoftware.code-spell-checker",
+        "timonwong.shellcheck",
+        "tamasfe.even-better-toml",
+        "skellock.just",
+        "redhat.vscode-yaml",
+        "asciidoctor.asciidoctor-vscode",
+        "usernamehw.errorlens"
+      ],
+      "settings": {
+        "editor.formatOnSave": true,
+        "editor.insertSpaces": true,
+        "editor.tabSize": 4,
+        "files.trimTrailingWhitespace": true,
+        "files.insertFinalNewline": true,
+        "files.trimFinalNewlines": true
+      }
+    },
+    "codespaces": {
+      "openFiles": [
+        "README.adoc"
+      ]
+    }
+  },
+
+  "forwardPorts": [],
+
+  "shutdownAction": "stopContainer"
+}

.github/pull_request_template.md

@@ -0,0 +1,48 @@
+<!--
+SPDX-License-Identifier: CC-BY-SA-4.0
+Copyright (c) Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
+-->
+## Summary
+
+<!-- Briefly describe what this PR does and why. Link to related issues with "Closes #N". -->
+
+## Changes
+
+<!-- List the key changes introduced by this PR. -->
+
+-
+
+## RSR Quality Checklist
+
+<!-- Check all that apply. PRs that fail required checks will not be merged. -->
+
+### Required
+
+- [ ] Tests pass (`just test` / `cargo test`)
+- [ ] Code is formatted (`just fmt` / `cargo fmt --check`)
+- [ ] Linter is clean (`cargo clippy --all-targets -- -D warnings`)
+- [ ] No banned language patterns (no TypeScript, no npm/bun, no Go/Python)
+- [ ] No `unsafe` blocks without `// SAFETY:` comments (`esn`/`lsm` use `deny`, all others `forbid`)
+- [ ] No proof escape hatches (`believe_me`, `unsafeCoerce`, `Obj.magic`, `Admitted`, `sorry`, `assert_total`)
+- [ ] SPDX license headers present on all new/modified source files
+- [ ] No secrets, credentials, or `.env` files included
+
+### As Applicable
+
+- [ ] `.machine_readable/6a2/STATE.a2ml` updated (if project state changed)
+- [ ] `.machine_readable/6a2/ECOSYSTEM.a2ml` updated (if integrations changed)
+- [ ] `.machine_readable/6a2/META.a2ml` updated (if architectural decisions changed)
+- [ ] `proofs/README.adoc` obligation table updated (if a proof obligation changed state)
+- [ ] Documentation updated for user-facing changes
+- [ ] `TOPOLOGY.adoc` updated (if architecture changed)
+- [ ] `CHANGELOG` or release notes updated
+- [ ] New dependencies reviewed for license compatibility (MPL-2.0)
+- [ ] JNI surface changes validated (`crates/neurophone-android` host-testable + lifecycle typestate preserved)
+
+## Testing
+
+<!-- Describe how you tested these changes. Record the actual command output, not a claim. -->
+
+## Screenshots
+
+<!-- If applicable, add screenshots or terminal output demonstrating the change. -->

.machine_readable/bot_directives/README.a2ml

@@ -0,0 +1,26 @@
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+#
+# README.a2ml — index of per-bot directives for neurophone.
+#
+# This directory holds fleet-specific directives (one file per bot). It is
+# distinct from `.machine_readable/agent_instructions/`, which holds session
+# methodology (how any agent works), and from `AGENTIC.a2ml`, which holds
+# permissions/gating. See agent_instructions/README.adoc §"Relationship to
+# Other Files".
+
+project = "neurophone"
+schema_version = "1.0.0"
+
+[bot-directives]
+notes = "Repo-specific per-bot constraints for neurophone (the estate gitbot fleet)."
+version = "1.0.0"
+
+[fleet]
+# The standard hyperpolymath bot fleet, each with a repo-local directive file.
+echidnabot  = "formal verification + fuzzing — keeps proofs/ honest"
+finishbot   = "task completion — no unfinished stubs; behavioural coverage before close"
+glambot     = "documentation — .adoc format, SPDX headers, no licence edits"
+rhodibot    = "git operations — no force-push, SHA-pin actions, always sign"
+seambot     = "integration — verify the JNI seam and crate boundaries end-to-end"
+sustainabot = "dependency updates — pinned, no npm/bun/yarn, guard the rand 0.9 trap"

.machine_readable/bot_directives/echidnabot.a2ml

@@ -0,0 +1,57 @@
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+#
+# echidnabot.a2ml — Directives for echidnabot in neurophone.
+#
+# echidnabot is the estate's proof-verification and fuzzing bot. In neurophone
+# its job is to keep the proof corpus (proofs/) honest and to exercise the
+# operational paths with fuzzers — never to weaken a proof or a test to make a
+# gate pass.
+
+project = "neurophone"
+schema_version = "1.0.0"
+
+[identity]
+bot = "echidnabot"
+role = "formal-verification-and-fuzzing"
+scope = "verify the proof corpus; run fuzzers; draft new proof/test obligations"
+
+[constraints]
+# Hard rules — echidnabot MUST NOT cross these.
+allow = [
+  "analysis",
+  "fuzzing",
+  "proof checks (TLC / Lean / Dafny / proptest / trybuild)",
+  "drafting new proof and test obligations as priority items",
+]
+deny = [
+  "introducing any proof escape hatch (believe_me, assert_total, Admitted, sorry, unsafeCoerce, Obj.magic)",
+  "weakening, skipping, or deleting an existing test or proof",
+  "editing crate source to make a proof pass (fix the proof, not the claim)",
+  "editing licence text or SPDX headers (owner-manual only)",
+  "relaxing the obligation-state ledger in proofs/README.adoc to overclaim",
+]
+
+[targets]
+# What echidnabot watches. Changes here should trigger a proof/fuzz re-check.
+watch = [
+  "crates/",
+  "proofs/",
+  "fuzz/",
+  ".clusterfuzzlite/",
+  "TEST-NEEDS.adoc",
+  ".machine_readable/MUST.contractile",
+]
+
+[obligations]
+# The canonical obligation map lives in proofs/README.adoc and issue #84.
+# echidnabot reads that table as the single source of truth for what is
+# *checked*, *property*-discharged, or honestly *open*, and never reports a
+# state stronger than the table records.
+source_of_truth = "proofs/README.adoc"
+epic = "https://github.com/hyperpolymath/neurophone/issues/84"
+
+[cadence]
+# First status line on wake must acknowledge the honesty contract.
+ack = "ACK: neurophone proof-corpus honesty contract loaded (no escape hatches; no overclaim)."
+on_new_unproven_seam = "draft a proof obligation as a priority item; do not defer silently"

.machine_readable/bot_directives/finishbot.a2ml

@@ -0,0 +1,27 @@
+# SPDX-License-Identifier: MPL-2.0
+# finishbot.a2ml — Directives for finishbot in neurophone
+
+project = "neurophone"
+schema_version = "1.0.0"
+
+[identity]
+bot = "finishbot"
+role = "task-completion"
+
+[constraints]
+# No stubs left unfinished — wire everything before closing a task (wire-first).
+# Build success != completion — do not close a task lacking behavioural test coverage.
+# Update .machine_readable/6a2/STATE.a2ml when tasks complete; record residual blockers.
+# A proof obligation is "done" only when proofs/README.adoc marks it checked or
+#   property-discharged — never on the strength of a plan or a stubbed spec.
+# Emit an honest end-of-session summary; never overclaim (the AFFIRMATION ethos).
+
+[targets]
+watch = [
+  ".machine_readable/6a2/STATE.a2ml",
+  "READINESS.md",
+  "TEST-NEEDS.adoc",
+  "proofs/README.adoc",
+  "HANDOVER.adoc",
+  "CHANGELOG.md",
+]

.machine_readable/bot_directives/glambot.a2ml

@@ -0,0 +1,33 @@
+# SPDX-License-Identifier: MPL-2.0
+# glambot.a2ml — Directives for glambot in neurophone
+
+project = "neurophone"
+schema_version = "1.0.0"
+
+[identity]
+bot = "glambot"
+role = "documentation"
+
+[constraints]
+# All prose docs use .adoc (AsciiDoc) — not .md except the GitHub-required set
+#   (SECURITY.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md, CHANGELOG.md).
+# SPDX-License-Identifier header required on every doc file (docs are CC-BY-SA-4.0).
+# Do not remove or truncate EXPLAINME.adoc or AFFIRMATION.adoc.
+# Do not add emojis unless the user explicitly requests them.
+# NEVER edit licence text or SPDX identifiers, or PALIMPSEST.adoc / citation /
+#   governance-philosophy docs — licensing is owner-manual only (flag, do not edit).
+# Docs must not outrun the proofs/tests: keep claims within the proofs/README.adoc ledger.
+
+[targets]
+watch = [
+  "README.adoc",
+  "EXPLAINME.adoc",
+  "AFFIRMATION.adoc",
+  "RSR-PHILOSOPHY.adoc",
+  "AUDIT.adoc",
+  "docs/",
+  "docs/wikis/",
+  "QUICKSTART-USER.adoc",
+  "QUICKSTART-DEV.adoc",
+  "QUICKSTART-MAINTAINER.adoc",
+]

.machine_readable/bot_directives/rhodibot.a2ml

@@ -0,0 +1,29 @@
+# SPDX-License-Identifier: MPL-2.0
+# rhodibot.a2ml — Directives for rhodibot in neurophone
+
+project = "neurophone"
+schema_version = "1.0.0"
+
+[identity]
+bot = "rhodibot"
+role = "git-operations"
+
+[constraints]
+# Never force-push to main or any protected branch (squabble, don't bypass).
+# Never push to non-origin remotes (GitHub is the source of truth).
+# SHA-pin all actions/* references before committing workflow changes (MUST).
+# Do not amend published commits — create new commits instead.
+# Always sign commits where the environment supports it; unsigned commits in the
+#   managed execution environment are non-blocking (platform-mediated signing).
+# Never put a model identifier in commit messages, PR titles/bodies, or code.
+
+[targets]
+watch = [
+  ".github/workflows/",
+  ".github/dependabot.yml",
+  "Justfile",
+  "contractile.just",
+  "Mustfile",
+  ".gitignore",
+  ".gitattributes",
+]

.machine_readable/bot_directives/seambot.a2ml

@@ -0,0 +1,30 @@
+# SPDX-License-Identifier: MPL-2.0
+# seambot.a2ml — Directives for seambot in neurophone
+
+project = "neurophone"
+schema_version = "1.0.0"
+
+[identity]
+bot = "seambot"
+role = "integration"
+
+[constraints]
+# Verify integration seams end-to-end whenever two components complete together.
+# The JNI seam (crates/neurophone-android <-> neurophone-core) must keep its
+#   host-testable bridge logic and its create->initialized->down lifecycle
+#   typestate (reset consumes the core via shutdown(self)) — see #110 / #93.
+# No ABI change without a matching proof update — MUST.contractile obligation.
+# The sole outbound-network seam is claude-client; the conative-gating GO/NO-GO
+#   egress veto (egress_gate.rs, #103) must remain wired at that choke point.
+# Neural->symbolic seam (core<->bridge Array1<f32>, bridge<->llm NeuralOutput)
+#   must preserve dimension/soundness invariants covered by the proptest suites.
+
+[targets]
+watch = [
+  "crates/neurophone-android/",
+  "crates/claude-client/src/egress_gate.rs",
+  "crates/bridge/",
+  "crates/",
+  "proofs/",
+  "docs/migrations/JNI-SURFACE-AUDIT.adoc",
+]

.machine_readable/bot_directives/sustainabot.a2ml

@@ -0,0 +1,29 @@
+# SPDX-License-Identifier: MPL-2.0
+# sustainabot.a2ml — Directives for sustainabot in neurophone
+
+project = "neurophone"
+schema_version = "1.0.0"
+
+[identity]
+bot = "sustainabot"
+role = "dependency-updates"
+
+[constraints]
+# All dependency updates must be SHA-pinned (GitHub Actions) or version-pinned (Cargo).
+# No upgrade of Cargo.lock without passing CI.
+# Do not introduce npm, bun, pnpm, or yarn dependencies — Deno only for JS.
+# KNOWN TRAP: do not bump `rand` past 0.9 / `rand_distr` past 0.5 — 0.10/0.6 break
+#   the esn/lsm build (ndarray-rand 0.16 compat). A dependabot bump already caused
+#   this regression once (#152/#154). Guard it.
+# Security advisories are high-priority; ping the maintainer before auto-merging.
+# The conative-gating git dependency (crates/claude-client) is pinned by rev —
+#   do not float it; a rev bump needs a deliberate, CI-verified change.
+
+[targets]
+watch = [
+  "Cargo.toml",
+  "Cargo.lock",
+  ".github/workflows/",
+  ".github/dependabot.yml",
+  "guix.scm",
+]