From e992ded4da76999490215bded6e98b74fbe91f77 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 5 Jun 2026 13:51:21 +0000 Subject: [PATCH] =?UTF-8?q?chore(machine-readable):=20currency=20checkpoin?= =?UTF-8?q?t=20=E2=80=94=20contractiles,=206a2=20refresh,=20bot=5Fdirectiv?= =?UTF-8?q?es=20rename?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Rename .machine_readable/agent_instructions/ → .machine_readable/bot_directives/ via git mv (no external refs remain outside .git) - Contractiles: copy INDEX.a2ml + _base.ncl from canonical (were missing) - Contractiles: copy 5 missing verb .ncl runners (adjust, dust, intend, must, trust) from canonical; bust.ncl was already present and matches canonical - Fix Intentfile.a2ml: remove corrupt copy-paste SPDX line in prose, expand with real Burble intents/wishes (PTP validation, Idris2 fix, AffineScript runtime, test gate, latency benchmark, mobile wishes) - 6a2/STATE.a2ml: bump last-updated to 2026-06-05, add post-2026-05-20 session history (CI campaigns C001-C005, SECURITY-DEPLOY.md, PROTOCOL.md, open-issue triage, MPL-2.0 license alignment PR #114), update Phase 3 completion 85→90 (web-client tests wired) - 6a2/META.a2ml: bump last-updated to 2026-06-05, correct languages list (ReScript is legacy, not primary), add ADR-0003 through ADR-0008 - 6a2/ECOSYSTEM.a2ml: bump last-updated to 2026-06-05, add PROTOCOL.md and SECURITY-DEPLOY.md integration points - All new/edited .a2ml files carry SPDX MPL-2.0 headers Signed-off-by: hyperpolymath <6759885+hyperpolymath@users.noreply.github.com> --- .machine_readable/6a2/ECOSYSTEM.a2ml | 6 +- .machine_readable/6a2/META.a2ml | 14 +- .machine_readable/6a2/STATE.a2ml | 26 +++- .../README.adoc | 2 +- .../coverage.a2ml | 0 .../debt.a2ml | 0 .../methodology.a2ml | 0 .machine_readable/contractiles/INDEX.a2ml | 133 +++++++++++++++++ .machine_readable/contractiles/_base.ncl | 141 ++++++++++++++++++ .../contractiles/adjust/adjust.ncl | 62 ++++++++ .machine_readable/contractiles/dust/dust.ncl | 66 ++++++++ .../contractiles/intend/Intentfile.a2ml | 70 ++++++++- .../contractiles/intend/intend.ncl | 81 ++++++++++ .machine_readable/contractiles/must/must.ncl | 64 ++++++++ .../contractiles/trust/trust.ncl | 88 +++++++++++ 15 files changed, 735 insertions(+), 18 deletions(-) rename .machine_readable/{agent_instructions => bot_directives}/README.adoc (94%) rename .machine_readable/{agent_instructions => bot_directives}/coverage.a2ml (100%) rename .machine_readable/{agent_instructions => bot_directives}/debt.a2ml (100%) rename .machine_readable/{agent_instructions => bot_directives}/methodology.a2ml (100%) create mode 100644 .machine_readable/contractiles/INDEX.a2ml create mode 100644 .machine_readable/contractiles/_base.ncl create mode 100644 .machine_readable/contractiles/adjust/adjust.ncl create mode 100644 .machine_readable/contractiles/dust/dust.ncl create mode 100644 .machine_readable/contractiles/intend/intend.ncl create mode 100644 .machine_readable/contractiles/must/must.ncl create mode 100644 .machine_readable/contractiles/trust/trust.ncl diff --git a/.machine_readable/6a2/ECOSYSTEM.a2ml b/.machine_readable/6a2/ECOSYSTEM.a2ml index c870032..7f4c2de 100644 --- a/.machine_readable/6a2/ECOSYSTEM.a2ml +++ b/.machine_readable/6a2/ECOSYSTEM.a2ml @@ -5,8 +5,8 @@ # Relationships, dependencies, integration points. [metadata] -version = "0.1.0" -last-updated = "2026-04-11" +version = "0.2.0" +last-updated = "2026-06-05" [project] name = "burble" @@ -38,4 +38,6 @@ points = [ { system = "VeriSimDB", direction = "outbound", protocol = "HTTP REST + ClickHouse" }, { system = "gitbot-fleet", direction = "outbound", protocol = "repository_dispatch (CI)" }, { system = "hypatia", direction = "inbound", protocol = "Hypatia scan rules via .hypatia/ config" }, + { system = "PROTOCOL.md (wire surface)", direction = "internal", protocol = "Bolt wire format (UDP/7373), WebRTC DataChannel, AI bridge HTTP REST" }, + { system = "SECURITY-DEPLOY.md", direction = "internal", protocol = "Self-hosting hardening checklist" }, ] diff --git a/.machine_readable/6a2/META.a2ml b/.machine_readable/6a2/META.a2ml index 45d671b..a461b4e 100644 --- a/.machine_readable/6a2/META.a2ml +++ b/.machine_readable/6a2/META.a2ml @@ -5,13 +5,13 @@ # Architecture decisions, design rationale, governance. [metadata] -version = "0.1.0" -last-updated = "2026-04-11" +version = "0.2.0" +last-updated = "2026-06-05" [project-info] type = "service" -languages = ["elixir", "zig", "idris2", "javascript", "rescript", "ephapax"] -languages-target = ["elixir", "zig", "idris2", "javascript", "affinescript", "ephapax"] +languages = ["elixir", "zig", "idris2", "javascript", "affinescript"] +languages-legacy = ["rescript"] license = "MPL-2.0" author = "Jonathan D.A. Jewell (hyperpolymath)" @@ -26,6 +26,12 @@ decisions = [ { id = "ADR-007", title = "ReScript → AffineScript client migration", status = "accepted", date = "2026-04-16" }, { id = "ADR-008", title = "Server-side Opus not implemented — SFU-opaque E2EE model", status = "accepted", date = "2026-04-16" }, { id = "ADR-009", title = "P2P AI bridge is primary Claude-to-Claude channel (not server-side Burble.LLM)", status = "accepted", date = "2026-04-16" }, + { id = "ADR-0003", title = "Bolt wire format — UDP+QUIC dual-bind, ALPN burble-bolt-v1", status = "accepted", date = "2026-05-13" }, + { id = "ADR-0004", title = "Bolt-over-QUIC with optional quicer NIF for sender authentication", status = "accepted", date = "2026-05-13" }, + { id = "ADR-0005", title = "WSL2 Bolt inbound — NAT + host UDP forwarder (default), mirrored last-resort", status = "accepted", date = "2026-05-19" }, + { id = "ADR-0006", title = "Signaling failure-mode coverage added (relay + connection loss)", status = "accepted", date = "2026-06-02" }, + { id = "ADR-0007", title = "Claims-to-evidence discipline — every README claim maps to code + test or flagged", status = "accepted", date = "2026-05-19" }, + { id = "ADR-0008", title = "Formal-proof enforcement scope — compile/type-check only; runtime PoC tracked as issue #55", status = "accepted", date = "2026-05-19" }, ] [development-practices] diff --git a/.machine_readable/6a2/STATE.a2ml b/.machine_readable/6a2/STATE.a2ml index c6316c4..beb3aee 100644 --- a/.machine_readable/6a2/STATE.a2ml +++ b/.machine_readable/6a2/STATE.a2ml @@ -5,8 +5,8 @@ [metadata] project = "burble" -version = "1.2.0-pre" -last-updated = "2026-05-20" +version = "1.3.0-pre" +last-updated = "2026-06-05" status = "active" [project-context] @@ -27,7 +27,7 @@ milestones = [ { name = "Phase 1 — Audio dependable (Opus honest, comfort noise, REMB, Avow chain, echo-cancel ref, neural spectral-gate verified)", completion = 100 }, { name = "Phase 2 — P2P AI channel dependable (burble-ai-bridge fixes, round-trip tests, docs) — CRITICAL PATH for family/pair-programming use case", completion = 100 }, { name = "Phase 2b — server-side Burble.LLM (provider, circuit breaker, fixed parse_frame, NimblePool wired) — SECONDARY, not required for family use case", completion = 100 }, - { name = "Phase 3 — RTSP + signaling + text + AffineScript client start", completion = 85 }, + { name = "Phase 3 — RTSP + signaling + text + AffineScript client start + web client tests", completion = 90 }, { name = "Phase 4 — PTP hardware clock via Zig NIF, phc2sys supervisor, multi-node align", completion = 85 }, { name = "Phase 5 — ReScript -> AffineScript completion", completion = 95 }, { name = "Bolt — magic incoming-call packets (UDP+QUIC dual-bind, ALPN burble-bolt-v1)", completion = 100, date = "2026-05-13" } @@ -74,7 +74,7 @@ phase-1-audio = [ ] [maintenance-status] -last-run-utc = "2026-04-01" +last-run-utc = "2026-06-05" last-report = "docs/reports/maintenance/latest.json" last-result = "pass" open-warnings = 0 @@ -213,13 +213,29 @@ open-failures = 0 # exhausted at merge time (concurrency-pool throttle); # will surface in next post-merge run on main. +# 2026-05-20 to 2026-06-05 (window since last update): +# 2026-06-01: CI/CD configuration fixed (campaigns C001-C005): CodeQL language +# fixes, license identifier standardization, outdated actions audit, +# standards refs pinned to SHA 861b5e9, workflow-level permissions added +# (PR #98, #97, #96 reusable-workflow replacements; PR #102 scorecard; +# PR #103 fake-SHA fix; PR #104 web-client tests; PR #111 CodeQL cron +# monthly; PR #112 a2ml-validate-action bump; PR #113 no-JS scan). +# 2026-06-02: SECURITY-DEPLOY.md published (self-hosting hardening checklist, PR #108). +# PROTOCOL.md published (discoverable wire surface, PR #107). +# Open-issue triage 2026-06-02 report (PR #110). +# Signaling failure-mode coverage added (PR #109). +# 2026-06-02: License drift fixed — LICENSE + 3 manifests (admin/deno.json, +# client/lib/deno.json, server/mix.exs) were AGPL drift while 679 +# source files already declared MPL-2.0. Owner-confirmed alignment +# to MPL-2.0 throughout (PR #114). LICENSE is now pure MPL-2.0. + [crg] grade = "C" achieved = "2026-04-21" previous-grade = "D" demoted-on = "2026-04-18" demotion-reference = "docs/governance/CRG-AUDIT-2026-04-18.adoc" -notes = "CRG C provisionally — CI workflow added, awaiting first green run. Three D-blockers resolved 2026-04-21: (1) READINESS.adoc created at repo root (verified complete), (2) per-directory README.adoc added to all seven core subtrees (timing, llm, chat, transport, media, client/web/src, ffi/zig), (3) .github/workflows/elixir-ci.yml created (test + dialyzer jobs, OTP 27 / Elixir 1.17, PLT cache). CODEOWNERS already covered * @hyperpolymath — no change needed." +notes = "CRG C provisionally — CI workflow present; gate still deactivated (continue-on-error: true) pending OTP27 CI run (issue #39). Post-2026-05-20 progress: web-client test suite wired (PR #104), CI/CD campaigns C001-C005 completed, SECURITY-DEPLOY.md + PROTOCOL.md published, license drift resolved (MPL-2.0 throughout, PR #114). Remaining blocker: re-arm CI test gate once OTP27 run validates suite. READINESS.adoc + per-directory READMEs + elixir-ci.yml all present." [ecosystem] part-of = ["Burble Platform"] diff --git a/.machine_readable/agent_instructions/README.adoc b/.machine_readable/bot_directives/README.adoc similarity index 94% rename from .machine_readable/agent_instructions/README.adoc rename to .machine_readable/bot_directives/README.adoc index 9bc2e24..4e989c7 100644 --- a/.machine_readable/agent_instructions/README.adoc +++ b/.machine_readable/bot_directives/README.adoc @@ -32,7 +32,7 @@ Methodology-aware configuration for AI agents. Read by any AI agent == Relationship to Other Files * `AGENTIC.a2ml` says WHAT agents can do (permissions, gating) -* `agent_instructions/` says HOW agents should work (methodology) +* `bot_directives/` says HOW agents should work (methodology) * `bot_directives/` says what the gitbot-fleet does (fleet-specific) * `CLAUDE.md` says how Claude specifically should work (Claude-specific) diff --git a/.machine_readable/agent_instructions/coverage.a2ml b/.machine_readable/bot_directives/coverage.a2ml similarity index 100% rename from .machine_readable/agent_instructions/coverage.a2ml rename to .machine_readable/bot_directives/coverage.a2ml diff --git a/.machine_readable/agent_instructions/debt.a2ml b/.machine_readable/bot_directives/debt.a2ml similarity index 100% rename from .machine_readable/agent_instructions/debt.a2ml rename to .machine_readable/bot_directives/debt.a2ml diff --git a/.machine_readable/agent_instructions/methodology.a2ml b/.machine_readable/bot_directives/methodology.a2ml similarity index 100% rename from .machine_readable/agent_instructions/methodology.a2ml rename to .machine_readable/bot_directives/methodology.a2ml diff --git a/.machine_readable/contractiles/INDEX.a2ml b/.machine_readable/contractiles/INDEX.a2ml new file mode 100644 index 0000000..d44c3f2 --- /dev/null +++ b/.machine_readable/contractiles/INDEX.a2ml @@ -0,0 +1,133 @@ +# SPDX-License-Identifier: MPL-2.0 +# INDEX.a2ml — Contractile Registry +# Author: Jonathan D.A. Jewell +# +# Machine-readable catalogue of all contractile verbs in this template set. +# Consumers (CI scripts, the contractile CLI, Hypatia rules) SHOULD read this +# file to discover available verbs rather than hard-coding the list. +# +# See: docs/CONTRACTILE-SPEC.adoc §Registry + +--- +id = "contractiles-registry" +version = "2.0.0" # 2.0.0 (2026-04-18): all 6 verbs on trident shape; verb set complete. +spec = "docs/CONTRACTILE-SPEC.adoc" +last_updated = "2026-04-18" +base_schema = ".machine_readable/contractiles/_base.ncl" +meta_schema_status = "pending — see CONTRACTILE-SPEC §validator-meta-schema" + +## Verbs + +[[verbs]] +name = "adjust" +semantics = "drift tolerances + corrective actions" +trident = [ + "adjust/Adjustfile.a2ml", + "adjust/adjust.ncl", + "adjust/adjust.k9.ncl", +] +manifest = "adjust/adjust.manifest.a2ml" +status = "active" +tier = "Yard" +authority = "advisory" +gating = "advisory (continue-with-warnings)" +cardinality = "one per repo" +notes = "Fifth trident instance (2026-04-18). First (Yard, advisory) authority pattern. Specialises in cumulative-drift catchment — tolerance bands + trend tracking across sessions. auto_fix_when_available applies deterministic patches; advisory otherwise." + +[[verbs]] +name = "bust" +semantics = "hard-stop / expiry / must-not-run declarations" +trident = [ + "bust/Bustfile.a2ml", + "bust/bust.ncl", + "bust/bust.k9.ncl", +] +manifest = "bust/bust.manifest.a2ml" +status = "active" +tier = "Hunt-read-only" +authority = "blocking" +gating = "hard (exit-nonzero)" +cardinality = "one per repo" +notes = "Fourth trident instance (2026-04-18). Completes the blocking-authority triple (must + trust + bust). Specialises in deprecated-path-reintroduction catchment. Injects failures via declared probes and verifies recovery paths." + +[[verbs]] +name = "dust" +semantics = "rollback / recovery / deprecation / audit-trail preservation" +trident = [ + "dust/Dustfile.a2ml", + "dust/dust.ncl", + "dust/dust.k9.ncl", +] +manifest = "dust/dust.manifest.a2ml" +status = "active" +tier = "Yard" +authority = "advisory" +gating = "advisory (continue-with-warnings)" +cardinality = "one per repo" +notes = "Sixth and FINAL trident instance (2026-04-18) — completes the full verb set. Specialises in audit-trail preservation + rollback-path verification. Destructive actions gated behind --apply flag + per-item approval; dry-run default." + +[[verbs]] +name = "intend" +semantics = "north-star (commitments + aspirations)" +trident = [ + "intend/Intentfile.a2ml", + "intend/intend.ncl", + "intend/intend.k9.ncl", +] +manifest = "intend/intend.manifest.a2ml" +status = "active" +tier = "Hunt" +authority = "reporting" +gating = "non-gating (continue)" +cardinality = "one per repo" +notes = "First trident instance in the estate (2026-04-18). Reports progress toward committed next-actions AND lists horizon aspirations. Absorbed the deprecated `lust` verb 2026-04-18. Never blocks. Remaining 5 verbs still on file_pair shape until tridents are built." + +[[verbs]] +name = "k9" +semantics = "trust-tier templates (EXCEPTION to one-verbfile rule)" +file_pair = [ + "k9/template-hunt.k9.ncl", + "k9/template-kennel.k9.ncl", + "k9/template-yard.k9.ncl", +] +status = "exception" +gating = "not applicable" +notes = "k9 is service-automation meta-infrastructure, not a verb contractile. Three trust-tier templates (Kennel/Yard/Hunt). Does not have a Verbfile.a2ml. See CONTRACTILE-SPEC §k9-exception." + +# [[verbs]] lust REMOVED 2026-04-18 — name had unwanted associations; +# the horizon/aspiration semantics were always meant to live inside `intend` +# (the north-star verb). The [[wishes]] schema was absorbed into +# intend/Intentfile.a2ml. Any `lust/` dir found in an estate repo is drift +# and should be deleted. + +[[verbs]] +name = "must" +semantics = "invariant assertion — release-blocking" +trident = [ + "must/Mustfile.a2ml", + "must/must.ncl", + "must/must.k9.ncl", +] +manifest = "must/must.manifest.a2ml" +status = "active" +tier = "Hunt-read-only" +authority = "blocking" +gating = "hard (exit-nonzero)" +cardinality = "one per repo" +notes = "Third trident instance (2026-04-18). Completes the blocking-authority pair with trust: must = concrete + persistent invariants; trust = concrete + ephemeral transactions. Specialises in subtle invariant-erosion (tracking per-session trend; flagging silent regression). Single failure blocks merge. Simplest and most commonly populated verb." + +[[verbs]] +name = "trust" +semantics = "security + provenance + safe-hacking" +trident = [ + "trust/Trustfile.a2ml", + "trust/trust.ncl", + "trust/trust.k9.ncl", +] +manifest = "trust/trust.manifest.a2ml" +status = "active" +tier = "Hunt" +authority = "blocking" +gating = "hard (exit-nonzero)" +cardinality = "one per repo" +notes = "Second trident instance (2026-04-18). First (Hunt, blocking) verb — hard gate. Primary defense against threat-model misclassification (B1) and 'turn off the firewall' capability-collapse (C2). Inherits on_open negotiation+accountability+translation from intend.k9.ncl v2.0.0; adds threat_model_foregrounding + block_session_close_on_critical_drift." diff --git a/.machine_readable/contractiles/_base.ncl b/.machine_readable/contractiles/_base.ncl new file mode 100644 index 0000000..22306fa --- /dev/null +++ b/.machine_readable/contractiles/_base.ncl @@ -0,0 +1,141 @@ +# SPDX-License-Identifier: MPL-2.0 +# (MPL-2.0 is automatic legal fallback until PMPL is formally recognised) +# +# _base.ncl — Shared contractile base +# +# Provides four named schema fragments imported by every verb runner: +# +# pedigree_schema — canonical pedigree block shape +# status_core_doc — documentation of the shared status trio (String list) +# probe_schema — target structured probe form (spec only; verb files +# still use probe | String with TODO comments) +# run_defaults — default runner behaviour +# +# Usage in a verb runner: +# +# let base = import "../_base.ncl" in +# { +# pedigree = base.pedigree_schema & { +# contractile_verb = "must", +# semantics = "invariant", +# security = { +# leash = 'Kennel, +# trust_level = "read-only verification", +# allow_network = false, +# allow_filesystem_write = false, +# allow_subprocess = true, +# }, +# metadata = { +# name = "must-runner", +# version = "1.0.0", +# description = "...", +# paired_xfile = "Mustfile.a2ml", +# author = "Jonathan D.A. Jewell ", +# }, +# }, +# schema = { ... }, +# run = base.run_defaults & { on_any_fail = "exit-nonzero" }, +# } +# +# See: docs/CONTRACTILE-SPEC.adoc §Shared Base + +{ + # ------------------------------------------------------------------------- + # pedigree_schema + # + # The canonical shape of the `pedigree` block required in every verb runner. + # Verb runners merge this with their verb-specific values using Nickel's `&` + # (right-priority merge). Override contractile_verb, semantics, security.*, + # and metadata.* in each verb. + # ------------------------------------------------------------------------- + pedigree_schema = { + schema_version | String | default = "1.0.0", + contractile_verb | String | default = "UNSET", # MUST override in verb + semantics | String | default = "UNSET", # MUST override in verb + security = { + leash | [| 'Kennel, 'Yard, 'Hunt |] | default = 'Kennel, + trust_level | String | default = "UNSET", # MUST override in verb + allow_network | Bool | default = false, + allow_filesystem_write | Bool | default = false, + allow_subprocess | Bool | default = true, + # verb-specific additional security fields go in the verb's merge override: + # e.g. authorised_probes_only (trust), injection_scope (bust), + # destructive_mode_requires_flag (dust) + }, + metadata = { + name | String | default = "UNSET", # MUST override in verb + version | String | default = "1.0.0", + description | String | default = "UNSET", # MUST override in verb + paired_xfile | String | default = "UNSET", # MUST override in verb + author | String | default = "Jonathan D.A. Jewell ", + }, + }, + + # ------------------------------------------------------------------------- + # status_core_doc + # + # Documents the minimum shared status values present in every verb's status + # enum: declared, verified, failing. + # + # Nickel does not support structural enum extension, so verb files reproduce + # their full enum verbatim in `schema`. This field serves as documentation + # and for tooling that introspects the base. + # + # Verbs that extend status_core (i.e. all except must + trust): + # adjust: + 'partial + # bust: + 'drilled + # dust: 'declared, 'proposed, 'approved, 'removed (non-standard) + # intend: intents: 'declared, 'in_progress, 'done, 'deferred, 'retired + # wishes: 'declared, 'in_progress, 'achieved, 'abandoned + # (the wishes schema was absorbed from the deprecated `lust` + # verb 2026-04-18; lust/ dir removed estate-wide) + # + # See: docs/CONTRACTILE-SPEC.adoc §Per-Verb Extension + # ------------------------------------------------------------------------- + status_core_doc = "status_core values: declared | verified | failing — extended per verb", + + # ------------------------------------------------------------------------- + # probe_schema + # + # The TARGET structured probe form. See: docs/CONTRACTILE-SPEC.adoc §Probe + # + # IMPORTANT: This is a spec-only definition. Existing verb runner files still + # use `probe | String` with a `# TODO: migrate to probe_schema` comment. + # This is a breaking change; migration happens when the CLI supports both + # forms. + # + # Adopters writing new xfiles should prefer the structured form: + # probe = { + # command = "test -f my-file", + # timeout_seconds = 60, + # allowed_exit_codes = [0], + # permission_class = 'read_only, + # } + # ------------------------------------------------------------------------- + probe_schema = { + command | String, + timeout_seconds | Number | default = 300, + allowed_exit_codes | Array Number | default = [0], + permission_class + | [| 'read_only, 'filesystem_write, 'subprocess, 'network |] + | default = 'read_only, + }, + + # ------------------------------------------------------------------------- + # run_defaults + # + # Default runner behaviour. Verb runners merge this with verb-specific + # overrides using Nickel's `&` (right-priority merge). + # + # Most verbs override on_any_fail: + # "exit-nonzero" : hard gate (must, trust, bust, adjust-gating) + # "continue-with-warnings": advisory (dust, adjust) + # "continue" : never gate (intend — covers both intents and wishes) + # ------------------------------------------------------------------------- + run_defaults = { + on_pass = "continue", + on_any_fail = "exit-nonzero", + report_format = "a2ml", + emit_summary = true, + }, +} diff --git a/.machine_readable/contractiles/adjust/adjust.ncl b/.machine_readable/contractiles/adjust/adjust.ncl new file mode 100644 index 0000000..d6c24f0 --- /dev/null +++ b/.machine_readable/contractiles/adjust/adjust.ncl @@ -0,0 +1,62 @@ +# SPDX-License-Identifier: MPL-2.0 +# Adjust — accessibility runner +# +# Pairs with: Adjustfile.a2ml (same directory) +# Verb: adjust +# Semantics: accessibility compliance (WCAG 2.1 AA baseline). Gating where +# a deterministic fix exists; advisory where human review needed. +# CLI: `contractile adjust check` → run all probes, list violations +# `contractile adjust fix` → apply deterministic fixes where defined +# +# Anything else in this directory is human-only notes/archive; machines ignore. +# +# Base: ../_base.ncl provides pedigree_schema, run_defaults, probe_schema. +# See: docs/CONTRACTILE-SPEC.adoc + +let base = import "../_base.ncl" in + +{ + pedigree = base.pedigree_schema & { + contractile_verb = "adjust", + semantics = "accessibility compliance", + security = { + leash = 'Kennel, + trust_level = "fixes allowed where deterministic", + allow_network = false, + allow_filesystem_write = true, # `adjust fix` may write (deterministic patches only) + allow_subprocess = true, + }, + metadata = { + name = "adjust-runner", + version = "1.0.0", + description = "Evaluates accessibility requirements from Adjustfile.a2ml. Fixes deterministic items; flags the rest for human review.", + paired_xfile = "Adjustfile.a2ml", + author = "Jonathan D.A. Jewell ", + }, + }, + + schema = { + requirements + | Array { + id | String, + description | String, + # TODO: migrate to base.probe_schema (structured probe) when CLI supports it + probe | String, + # status_core values: 'declared, 'verified, 'failing; adjust adds 'partial + status | [| 'declared, 'partial, 'verified, 'failing |] | default = 'declared, + compliance | String | optional, # e.g. "WCAG 2.1 AA" + notes | String | optional, + fix | String | optional, # deterministic fix command (optional) + }, + }, + + # Runner behaviour — inherits from base.run_defaults. + # adjust is advisory (continue-with-warnings) not a hard gate. + # auto_fix_when_available is adjust-specific. + run = base.run_defaults & { + on_any_fail = "continue-with-warnings", # accessibility is progress-tracked, not a hard gate by default + report_format = "a2ml", + emit_summary = true, + auto_fix_when_available = true, + }, +} diff --git a/.machine_readable/contractiles/dust/dust.ncl b/.machine_readable/contractiles/dust/dust.ncl new file mode 100644 index 0000000..36aa89b --- /dev/null +++ b/.machine_readable/contractiles/dust/dust.ncl @@ -0,0 +1,66 @@ +# SPDX-License-Identifier: MPL-2.0 +# Dust — exnovation / code-removal runner +# +# Pairs with: Dustfile.a2ml (same directory) +# Verb: dust +# Semantics: exnovation. Identifies code, docs, files, dependencies that are +# candidates for REMOVAL. Advisory by default; can be flipped to +# active delete via `contractile dust sweep --apply`. +# CLI: `contractile dust find` → list removal candidates +# `contractile dust sweep` → dry-run removals +# `contractile dust sweep --apply` → actually delete (gated) +# +# Anything else in this directory is human-only notes/archive; machines ignore. +# +# Base: ../_base.ncl provides pedigree_schema, run_defaults, probe_schema. +# See: docs/CONTRACTILE-SPEC.adoc + +let base = import "../_base.ncl" in + +{ + pedigree = base.pedigree_schema & { + contractile_verb = "dust", + semantics = "exnovation / removal", + security = { + leash = 'Kennel, + trust_level = "proposes deletion; --apply required to execute", + allow_network = false, + allow_filesystem_write = true, # --apply mode writes (deletes) + allow_subprocess = true, + destructive_mode_requires_flag = "--apply", + }, + metadata = { + name = "dust-runner", + version = "1.0.0", + description = "Identifies and optionally removes exnovation targets listed in Dustfile.a2ml. Destructive mode gated behind --apply.", + paired_xfile = "Dustfile.a2ml", + author = "Jonathan D.A. Jewell ", + }, + }, + + schema = { + removal_candidates + | Array { + id | String, + description | String, + target | String, # file / path / symbol / dep name + reason | String, # why it's a removal candidate + # TODO: migrate to base.probe_schema (structured probe) when CLI supports it + probe | String | optional, # command that confirms it's still removable + # dust has a non-standard status progression (no 'verified): + # 'declared → 'proposed → 'approved → 'removed + status | [| 'declared, 'proposed, 'approved, 'removed |] | default = 'declared, + approver | String | optional, # who signed off (for 'approved / 'removed) + notes | String | optional, + }, + }, + + # Runner behaviour — inherits from base.run_defaults. + # dust is advisory; apply_requires_approval is dust-specific. + run = base.run_defaults & { + on_any_fail = "continue-with-warnings", + report_format = "a2ml", + emit_summary = true, + apply_requires_approval = true, # only 'approved items get swept, even with --apply + }, +} diff --git a/.machine_readable/contractiles/intend/Intentfile.a2ml b/.machine_readable/contractiles/intend/Intentfile.a2ml index 908e832..6f3c547 100644 --- a/.machine_readable/contractiles/intend/Intentfile.a2ml +++ b/.machine_readable/contractiles/intend/Intentfile.a2ml @@ -1,22 +1,80 @@ # SPDX-License-Identifier: MPL-2.0 -# Intentfile (A2ML Canonical) -# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +# Intentfile — North-star contract for Burble +# Author: Jonathan D.A. Jewell +# +# Committed next-actions ([[intents]]) and horizon aspirations ([[wishes]]). +# Run with: intend run +# Progress: intend progress @abstract: -Declared intent and purpose for Burble. +Declared intent and north-star for the Burble P2P voice + AI bridge platform. +Burble is a self-hostable, P2P-first, WebRTC voice platform with an encrypted +AI data channel (Claude-to-Claude protocol over WebRTC DataChannel). @end ## Purpose -Burble — // SPDX-License-Identifier: MPL-2.0 +Burble is a P2P voice communications platform with an AI data channel. +Primary use cases: family/pair-programming voice with co-located Claude instances; +self-hosted voice with zero server infrastructure via the P2P mode. ## Anti-Purpose This project is NOT: - A fork or wrapper around another tool -- A monorepo (unless explicitly structured as one) +- A centralised server-only voice platform (P2P mode is the floor) +- A general-purpose LLM proxy (the AI channel is Claude-to-Claude over WebRTC) ## If In Doubt If you are unsure whether a change is in scope, ask. -Sensitive areas: ABI definitions, license headers, CI workflows. +Sensitive areas: ABI definitions (ffi/zig/, server/lib/burble/coprocessor.ex), +WebRTC DataChannel protocol (docs/AI-CHANNEL-PROTOCOL.json), +Bolt wire format (server/lib/burble/bolt/), license headers, CI workflows. + +## Intents + +### ptp-hardware-validation +- description: Validate PTP hardware path with I210 NIC (sub-microsecond clock sync) +- status: declared +- notes: I210 NIC pending; NTP ~1ms fallback operational. ADR-0007 claim discipline. + +### idris2-mediapipeline-fix +- description: Fix MediaPipeline.idr (postulate → valid Idris2 syntax); all 7 ABI modules compile +- status: declared +- notes: Currently 6/7 compile; MediaPipeline.idr fails on Idris1 `postulate` syntax. Epic #53. + +### runtime-affinescript-verification +- description: Verify AffineScript compiler output at runtime (not just compile/type-check) +- status: declared +- notes: ADR-0008 Option C; PoC tracked in issue #55. + +### test-gate-reenable +- description: Re-enable CI test gate once OTP27 CI run validates 707-test suite +- status: declared +- notes: Currently continue-on-error=true. 707 tests, ~134 failures locally on OTP25 with no singleton-death block. + +### latency-benchmark +- description: Benchmark end-to-end mic-to-speaker latency and 500+ concurrent scale +- status: declared +- notes: Issue #52. Not yet measured. + +## Wishes + +### self-hosting-guide +- description: Complete self-hosting hardening guide for production deployments +- horizon: near +- why: SECURITY-DEPLOY.md exists but deployment guide is still sparse +- status: declared + +### mobile-client +- description: Native mobile client (iOS/Android) via Tauri 2.0 or Dioxus +- horizon: mid +- why: Browser-join works but a native app improves push-to-talk ergonomics +- status: declared + +### android-bolt-receiver +- description: Android Bolt incoming-call receiver (architecture doc landed; implementation deferred) +- horizon: mid +- why: Architecture documented in b1070af; Bluetooth + QUIC plan ready +- status: declared diff --git a/.machine_readable/contractiles/intend/intend.ncl b/.machine_readable/contractiles/intend/intend.ncl new file mode 100644 index 0000000..091b7f6 --- /dev/null +++ b/.machine_readable/contractiles/intend/intend.ncl @@ -0,0 +1,81 @@ +# SPDX-License-Identifier: MPL-2.0 +# Intend — north-star runner (verb is `intend`, file is `Intentfile.a2ml`) +# +# Pairs with: Intentfile.a2ml (same directory) +# Verb: intend +# Semantics: Declares BOTH concrete committed next-actions ([[intents]]) and +# horizon aspirations ([[wishes]]). Not a gate — reports progress +# toward declared intents and lists wishes by horizon. +# Status progressions: +# intents: 'declared → 'in_progress → 'done | 'deferred | 'retired +# wishes: 'declared → 'in_progress → 'achieved | 'abandoned +# CLI: `contractile intend run` → print status table (both sections) +# `contractile intend progress` → diff declared-vs-observed (intents) +# `contractile intend horizon` → group wishes by near/mid/far +# +# History: Absorbed the deprecated `lust` contractile's [[wishes]] schema +# 2026-04-18. `lust/` dir removed estate-wide. +# +# Anything else in this directory is human-only notes/archive; machines ignore. +# +# Base: ../_base.ncl provides pedigree_schema, run_defaults, probe_schema. +# See: docs/CONTRACTILE-SPEC.adoc + +let base = import "../_base.ncl" in + +{ + pedigree = base.pedigree_schema & { + contractile_verb = "intend", + semantics = "north-star (commitments + aspirations)", + security = { + leash = 'Kennel, + trust_level = "read-only reporting", + allow_network = false, + allow_filesystem_write = false, + allow_subprocess = true, # probe commands may shell out (intents only; wishes never probe) + }, + metadata = { + name = "intend-runner", + version = "2.0.0", + description = "Reports progress toward committed next-actions and lists horizon aspirations. Non-gating. Absorbed `lust` semantics 2026-04-18.", + paired_xfile = "Intentfile.a2ml", + author = "Jonathan D.A. Jewell ", + }, + }, + + schema = { + intents + | Array { + id | String, + description | String, + # TODO: migrate to base.probe_schema (structured probe) when CLI supports it + probe | String | optional, # shell command that indicates done-ness + status | [| 'declared, 'in_progress, 'done, 'deferred, 'retired |] | default = 'declared, + notes | String | optional, + target_date | String | optional, + }, + wishes + | Array { + id | String, + description | String, + horizon | [| 'near, 'mid, 'far |] | default = 'mid, + why | String | optional, + status | [| 'declared, 'in_progress, 'achieved, 'abandoned |] | default = 'declared, + notes | String | optional, + } + | optional, + }, + + # Runner behaviour — inherits from base.run_defaults. + # intend never blocks; it is a report only. + # emit_diff is intent-specific (declared vs observed probes). + # emit_grouped_by_horizon renders wishes grouped by near/mid/far. + run = base.run_defaults & { + on_pass = "continue", + on_any_fail = "continue", # never blocks; it's a report + report_format = "a2ml", + emit_summary = true, + emit_diff = true, # declared vs observed (intents) + emit_grouped_by_horizon = true, # wishes grouped by horizon (absorbed from lust) + }, +} diff --git a/.machine_readable/contractiles/must/must.ncl b/.machine_readable/contractiles/must/must.ncl new file mode 100644 index 0000000..47509d3 --- /dev/null +++ b/.machine_readable/contractiles/must/must.ncl @@ -0,0 +1,64 @@ +# SPDX-License-Identifier: MPL-2.0 +# Must — invariants runner +# +# Pairs with: Mustfile.a2ml (same directory) +# Verb: must (invariant assertion) +# Semantics: every check is a hard gate. A single failure blocks merge. +# CLI: `contractile must run` → reads Mustfile.a2ml, evaluates each check, +# emits pass/fail verdict per item, exits non-zero if any failed. +# +# This file is the *schema + runner* that the `contractile` CLI (at +# /var/mnt/eclipse/repos/reposystem/contractiles/cli/) loads alongside +# Mustfile.a2ml. Anything else in this directory is human-only notes/archive +# and MUST be ignored by machines. +# +# Base: ../_base.ncl provides pedigree_schema, run_defaults, probe_schema. +# See: docs/CONTRACTILE-SPEC.adoc + +let base = import "../_base.ncl" in + +{ + pedigree = base.pedigree_schema & { + contractile_verb = "must", + semantics = "invariant", + security = { + leash = 'Kennel, + trust_level = "read-only verification", + allow_network = false, + allow_filesystem_write = false, + allow_subprocess = true, # verification probes may shell out (e.g. grep, test -f) + }, + metadata = { + name = "must-runner", + version = "1.0.0", + description = "Evaluates every invariant in the adjacent Mustfile.a2ml as a hard gate.", + paired_xfile = "Mustfile.a2ml", + author = "Jonathan D.A. Jewell ", + }, + }, + + # Contract schema — the shape every Mustfile.a2ml must satisfy. + # Used by `contractile must typecheck Mustfile.a2ml`. + schema = { + invariants + | Array { + id | String, + description | String, + # TODO: migrate to base.probe_schema (structured probe) when CLI supports it + probe | String, # shell command; exit 0 = pass + # status_core values: 'declared, 'verified, 'failing + status | [| 'declared, 'verified, 'failing |] | default = 'declared, + severity | [| 'critical, 'high, 'medium |] | default = 'critical, + notes | String | optional, + fix | String | optional, + }, + }, + + # Runner behaviour — consumed by the contractile CLI dispatcher. + # Inherits from base.run_defaults; on_any_fail is the hard-gate default. + run = base.run_defaults & { + on_any_fail = "exit-nonzero", # hard gate + report_format = "a2ml", # emit a2ml report, not json + emit_summary = true, + }, +} diff --git a/.machine_readable/contractiles/trust/trust.ncl b/.machine_readable/contractiles/trust/trust.ncl new file mode 100644 index 0000000..21b335c --- /dev/null +++ b/.machine_readable/contractiles/trust/trust.ncl @@ -0,0 +1,88 @@ +# SPDX-License-Identifier: MPL-2.0 +# Trust — security + safe-hacking runner +# +# Pairs with: Trustfile.a2ml (same directory) +# Verb: trust +# Semantics: integrity / provenance / security verification PLUS a declared +# "safe hacking + testing" section — authorised offensive probes +# (pen-test harness runs, chaos-engineering probes) scoped to the +# repo under test, NEVER touching external systems. +# CLI: `contractile trust verify` → run all verifications (read-only) +# `contractile trust probe` → run declared safe-hacking probes +# +# Anything else in this directory is human-only notes/archive; machines ignore. +# +# Base: ../_base.ncl provides pedigree_schema, run_defaults, probe_schema. +# See: docs/CONTRACTILE-SPEC.adoc + +let base = import "../_base.ncl" in + +{ + pedigree = base.pedigree_schema & { + contractile_verb = "trust", + semantics = "security + provenance + safe-hacking", + security = { + leash = 'Kennel, + trust_level = "verification + authorised-probe", + allow_network = false, # verifications are offline by default + allow_filesystem_write = false, # trust writes NOTHING + allow_subprocess = true, + authorised_probes_only = true, # probe section must explicitly list allowed targets + }, + metadata = { + name = "trust-runner", + version = "1.0.0", + description = "Security + provenance verifications plus authorised safe-hacking probes. All probes are scoped to the repo under test; never hits external systems.", + paired_xfile = "Trustfile.a2ml", + author = "Jonathan D.A. Jewell ", + }, + }, + + schema = { + verifications + | Array { + id | String, + description | String, + # TODO: migrate to base.probe_schema (structured probe) when CLI supports it + probe | String, # read-only; exit 0 = pass + # status_core values: 'declared, 'verified, 'failing + status | [| 'declared, 'verified, 'failing |] | default = 'declared, + # trust uses all four severity levels (from base.severity_core) + severity | [| 'critical, 'high, 'medium, 'low |] | default = 'high, + notes | String | optional, + }, + + # Safe-hacking + testing section (added 2026-04-17 per user direction). + # Each probe here is an ACTIVELY EXECUTED test — fuzz runs, chaos probes, + # auth-bypass attempts, injection tests. All scoped to the current repo. + safe_hacking + | { + scope | String, # e.g. "this-repo-only" / "localhost" + allowed_probe_classes + | Array [| 'fuzz, 'property_test, 'chaos, 'auth_bypass, 'injection, 'timing |] + | default = [], + probes + | Array { + id | String, + class | [| 'fuzz, 'property_test, 'chaos, 'auth_bypass, 'injection, 'timing |], + description | String, + # TODO: migrate to base.probe_schema (structured probe) when CLI supports it + probe | String, # command to run the probe + expected_outcome | [| 'probe_blocks_attempt, 'probe_finds_no_issue |], + timeout_seconds | Number | default = 300, + notes | String | optional, + } + | default = [], + } + | default = { scope = "this-repo-only", allowed_probe_classes = [], probes = [] }, + }, + + # Runner behaviour — inherits from base.run_defaults. + # trust has an extra field for unexpected safe-hacking outcomes. + run = base.run_defaults & { + on_any_fail = "exit-nonzero", # hard gate on verifications + safe_hacking_on_unexpected_outcome = "exit-nonzero", # probe found what it shouldn't = block + report_format = "a2ml", + emit_summary = true, + }, +}