RSR audit remediation (workstreams B–F): docs, contractile hole-fix, .adoc conversions, wikis, bot fleet, JNI-bridge tests#170
Merged
Conversation
… directive Fills genuine RSR-compliance documentation gaps identified in the completeness audit (workstream B, docs half). No code changes; no licence/SPDX sweeps. - AFFIRMATION.adoc — honest ground-truthed snapshot. fmt affirmed by a local run; build/test affirmed via CI (last green on main@690b90a), with the conative-gating local-egress boundary named under "what we do NOT claim". - RSR-PHILOSOPHY.adoc — estate operating doctrine (holes-before-goals, fail loudly, solutions-at-source), operationalised for neurophone. - AUDIT.adoc — repo-local hard audit gate summary; points at the standards canon and the proofs/README.adoc obligation ledger. - CITATION.cff — machine-readable citation metadata (MPL-2.0). - .github/pull_request_template.md — RSR quality checklist, adapted to neurophone's real layout (6a2/ paths, JNI seam, proof-escape-hatch ban). - .devcontainer/devcontainer.json — dev container from a base image + rust/just/ nickel features (neurophone has no Containerfile). - .pre-commit-config.yaml — standard + a2ml + k9 + shellcheck + gitleaks hooks (arrival-pack hook dropped; neurophone has none). - .machine_readable/bot_directives/echidnabot.a2ml — proof-verification bot scope; reads proofs/README.adoc as the obligation source of truth. Mirrors hyperpolymath/rsr-template-repo canonical scaffolding. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0172RBMz3qYjb1ttzD2i7RNh
…ng import
`.machine_readable/contractiles/bust/bust.ncl` does `import "../_base.ncl"` and
uses `base.pedigree_schema`, `base.probe_schema`, and `base.run_defaults`, but
the base file did not exist — a genuine broken reference (a hole). This copies
the canonical shared contractile base verbatim from rsr-template-repo (MPL-2.0),
which exports exactly those symbols (plus status_core_doc). bust.ncl is the only
importer in the repo, so this single file fully closes the hole with no new
dependencies.
Deliberately scoped to just the hole: the fuller intend/adjust trident form was
NOT added, because those tridents' k9 components import k9 trust-tier templates
neurophone does not carry and write to a `descriptiles/` layout neurophone
deliberately does not use (it kept 6a2/). Migrating to that layout is a
supervised substrate change, out of scope here; the intend/adjust doctrine
already exists in `.machine_readable/{INTENT,ADJUST}.contractile`.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0172RBMz3qYjb1ttzD2i7RNh
…standard) Workstream C of the audit remediation. These five files were the last non-GitHub-required Markdown docs in the tree; the estate standard is .adoc for all prose except the GitHub-required set (SECURITY/CONTRIBUTING/CODE_OF_CONDUCT/ CHANGELOG), which are untouched. - TOPOLOGY.md → TOPOLOGY.adoc — converted; Android-shell facts corrected to the merged gossamer migration (#83): Kotlin/Compose → gossamer WebView + Java JNI shims; "Kotlin ↔ Rust" → "Java ↔ Rust (#110)". Inbound links updated in README.adoc, docs/BT-PRESENCE-PLAN.adoc, docs/architecture.adoc. - TEST-NEEDS.md → TEST-NEEDS.adoc — converted; dated CRG-C snapshot (2026-04-04) preserved, with a NOTE that the per-crate "stub" labels are superseded (those crates now have property suites; #110 gave neurophone-android a real JNI surface). Live truth is the crate tests + proofs/README.adoc. - docs/tech-debt-2026-05-26.md → .adoc — dated estate-scan snapshot preserved verbatim with a NOTE that several findings are since addressed. - llm-warmup-{dev,user}.md → .adoc — converted; dropped the non-existent `just setup` hint, added `just quality` for the dev warmup. No inbound reference to any removed file remains (verified). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0172RBMz3qYjb1ttzD2i7RNh
Workstream D of the audit remediation. neurophone already had solid developer
and maintainer docs (architecture/build/usage, QUICKSTART-{DEV,MAINTAINER,USER},
MAINTAINERS, HANDOVER) but no wiki hub and nothing for lay readers or
press/partners — the two audiences the completeness audit flagged as unserved.
- docs/wikis/README.adoc — audience-indexed hub; routes each reader (lay, user,
developer, maintainer, journalist) to the right material and cross-links the
existing deep-dive docs rather than duplicating them. Includes a glossary.
- docs/wikis/for-lay-readers.adoc — plain-language, no-jargon explanation of what
NeuroPhone is and why on-device AI differs; honest about pre-1.0 status.
- docs/wikis/for-press-and-partners.adoc — grounded briefing: distinctive points,
an explicit "what is NOT done" section, a fact box, accurate-vs-avoid framings,
a "how to verify" pointer to AFFIRMATION.adoc / proofs/README.adoc, licensing.
- docs/wikis/for-users-faq.adoc — install/privacy/troubleshooting/uninstall FAQ,
pointing at the authoritative AI_INSTALLATION_GUIDE for exact steps.
All claims kept grounded per AUDIT.adoc (no "stable/v1.0.0", no overclaim).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0172RBMz3qYjb1ttzD2i7RNh
Workstream F of the audit remediation. agent_instructions/README.adoc already pointed at `bot_directives/` (line 36) but the directory did not exist — a latent dangling reference. This populates it with the standard hyperpolymath bot fleet (matching odds-and-sods / verisimdb), each directive adapted to neurophone's real files and known traps rather than copied as template residue: - README.a2ml — index of the fleet; documents the bot_directives/ vs agent_instructions/ (methodology) vs AGENTIC.a2ml (permissions) split. - finishbot — task completion: behavioural coverage before close; a proof is "done" only when proofs/README.adoc says checked/property. - glambot — documentation: .adoc format, SPDX, and an explicit NEVER-edit-licence guard (owner-manual only), docs kept within the proof ledger. - rhodibot — git ops: no force-push, SHA-pin actions, no amend-published, sign, no model identifier in commits. - seambot — integration: the JNI seam (#110/#93 lifecycle typestate), the conative egress veto (#103), and the neural->symbolic dimension invariants. - sustainabot — deps: pinning, no npm/bun/yarn, and the rand-0.9 trap guard (#152/#154) plus the pinned conative-gating git rev. echidnabot.a2ml (proof/fuzzing) was added earlier in this branch. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0172RBMz3qYjb1ttzD2i7RNh
…reset edges Workstream E of the audit remediation, scoped to what is genuinely useful and locally sound. #110 already gave crates/neurophone-android real host-testable coverage (full_lifecycle, reset_preserves_running_and_config, bad_config, sensor_map). The remaining gap was the boundary's *guard* error paths — the happy-path lifecycle test does not assert that every entrypoint refuses to run before the affine holder is acquired. Three new inline #[cfg(test)] tests close that, using only the already-proven API and strictly code-derived assertions: - every_boundary_op_before_init_is_rejected — start/process_sensor/query/ neural_context/state_json/reset all Err before init(); stop() is a safe no-op. - empty_or_whitespace_config_falls_back_to_default — parse_config trims before deciding, so "" and " " mean default, not a parse error. - reset_preserves_not_running_and_stays_usable — the running=false branch of reset (complements the existing running=true test), plus post-reset usability. Deliberately NOT added (flagged for a follow-up on a build-capable host): an external tests/ integration file and a Criterion bench. Both would require making the deliberately-private `state`/`sensor_map` modules public (an encapsulation change), and neither can be compiled or run in this session — the workspace does not resolve locally because crates/claude-client git-depends on hyperpolymath/conative-gating, which is outside this session's network scope. A bench of the only pure public-able function (a 5-entry sensor-id lookup) would be theater, which AUDIT.adoc forbids; the meaningful marshalling bench targets are private serde paths. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0172RBMz3qYjb1ttzD2i7RNh
|
hyperpolymath
changed the title
hyperpolymath
marked this pull request as ready for review
July 2, 2026 23:07
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
2 participants
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.
Summary
Completes the repo-side, tractable half of the completeness-audit remediation (workstreams B–F of the approved plan). This is disjoint from the parallel session's work (#103/#83/#84-proofs/#168, all merged) and adds no licence/SPDX sweeps and only one small, well-scoped code change (test-only).
What's in it (by workstream)
B — RSR compliance gaps
AFFIRMATION.adoc,RSR-PHILOSOPHY.adoc,AUDIT.adoc,CITATION.cff,.github/pull_request_template.md,.devcontainer/devcontainer.json,.pre-commit-config.yaml— community-health + philosophy scaffolding mirrored from rsr-template-repo, adapted to neurophone (6a2/paths, JNI seam, noContainerfile/arrival-pack)..machine_readable/contractiles/_base.ncl— fixes a genuine broken reference:bust/bust.nclimported../_base.ncl, which did not exist. Copied verbatim from the canonical template;bust.nclis the only importer, so this fully closes the hole with no new deps. (The fuller intend/adjust trident form was deliberately not added — its k9 components import k9 trust-tier templates neurophone doesn't carry and assume adescriptiles/layout neurophone deliberately kept as6a2/; that's a supervised substrate migration, out of scope.)C — Doc format — the 5 remaining non-GitHub-required
.mddocs →.adoc(TEST-NEEDS,TOPOLOGY,llm-warmup-{dev,user},docs/tech-debt-2026-05-26), inboundlink:TOPOLOGY.md[]refs updated (README, architecture, BT-PRESENCE-PLAN).TOPOLOGYAndroid facts corrected to the merged gossamer migration; the two dated snapshots preserved with honest staleness NOTEs.D — Wikis —
docs/wikis/hub (audience-indexed + glossary) plus the two under-served audiences the audit flagged:for-lay-readers.adocandfor-press-and-partners.adoc, plus afor-users-faq.adoc. All claims grounded per AUDIT.adoc (no "stable/v1.0.0").F — Bot fleet — populated
.machine_readable/bot_directives/(whichagent_instructions/README.adocalready referenced — a latent dangling ref) with the estate-standard fleet: echidnabot, finishbot, glambot, rhodibot, seambot, sustainabot + a README index. Each adapted to neurophone's real files and known traps (rand-0.9, JNI seam, conative egress, licence-manual guard).E — JNI-bridge tests — three inline
#[cfg(test)]tests incrates/neurophone-androidclosing the before-init guard error-path gap (#110 already covered the happy paths). See the flag below re: the external test + bench.Testing
cargo fmt --checkclean (local). New files scanned clean against the empty-linter patterns.governance / Validate Hypatia Baseline— see flags.crates/claude-clientgit-depends onhyperpolymath/conative-gating, which is outside this session's network egress scope (HTTP 403), so the workspace doesn't resolve here. The new tests were written against the crate's already-proven inline-test API with strictly code-derived assertions, and are verified by this PR'srust-ci.Flags / owner-manual
governance / Validate Hypatia Baseline(pre-existing red). This check fails on every main commit (confirmed on 8+, including fix: reduce hypatia raw findings 44 -> 10, honest-baseline the rest #168 which created the baseline). Its job runshypatia-cli.sh scan .and fails on any finding; it does not consult.hypatia-baseline.json(which is also affected by an upstream absolute-vs-relative path bug, hypatia#566). The 14 findings (2 crit/6 high/6 med) are pre-existing code-level items; this docs+test PR does not add any. Blind-baselining unseen criticals would be a forbidden silent-green, so no action taken here — it remains owner's-call debt (real fix is upstream).tests/integration file and a Criterion bench were not added. Both need the deliberately-privatestate/sensor_mapmodules made public (an encapsulation change), and neither can be compiled/run in this session. A bench of the only pure public-able function (a 5-entry lookup) would be theater (AUDIT.adoc forbids). Left for a build-capable host.hyperpolymath/conative-gatingmeans building neurophone requires fetch access to that repo. Flagging for visibility (it's the Adopt conative-gating as policy/egress GO/NO-GO veto (refs proof-obligation #84-3.1) #103 design).🤖 Generated with Claude Code
https://claude.ai/code/session_0172RBMz3qYjb1ttzD2i7RNh