From 9e7ef32d639108e90d6f12d5e451c7998372c8aa Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 14 Nov 2026 18:29:38 +0000 Subject: [PATCH 01/10] chore(deed): translate the descriptiles into hypatia_chora.deed Owner ruling 2026-11-14, "Full migration now". Each retired descriptile is translated under the mapping spec for its family, then deleted: - META.a2ml -> (meta): last-updated, scoping-first and the five ADRs (id, title, status, date), per meta-ecosystem-to-repo-deed.adoc. - ECOSYSTEM.a2ml -> (ecosystem): project, ecosystem, position-type, purpose. The seven related-projects entries are not translated: their relationships are outside the closed set the (related) row allows. - AGENTIC.a2ml -> (agentic): version, last-updated, permissions and the five integrity axioms (allow-silent-skip stays #f). - NEUROSYM.a2ml -> (neurosym): version, last-updated and the hypatia scan config (scan-depth deep). - PLAYBOOK.a2ml -> (playbook): version, last-updated and the five operational positions. - STATE.a2ml -> (maturity :level alpha), state-v1-decision option B; the lifecycle claim is the existing (status) clause and the journal is archived by reference, not translated. - CLADE.a2ml was already translated (identity, clade, forges, lineage, status); the legacy file is deleted. Fields no table lists are dropped, not re-homed; the deed comments name each one. The deed lints clean (deed_lint.js, plain and --egress). Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_0136P7ZoBy5xGnGDLk7wQ8jC --- .machine_readable/CLADE.a2ml | 52 --- .machine_readable/descriptiles/AGENTIC.a2ml | 88 ----- .machine_readable/descriptiles/ECOSYSTEM.a2ml | 69 ---- .machine_readable/descriptiles/META.a2ml | 77 ----- .machine_readable/descriptiles/NEUROSYM.a2ml | 64 ---- .machine_readable/descriptiles/PLAYBOOK.a2ml | 78 ----- .machine_readable/descriptiles/STATE.a2ml | 315 ------------------ hypatia_chora.deed | 106 +++++- 8 files changed, 93 insertions(+), 756 deletions(-) delete mode 100644 .machine_readable/CLADE.a2ml delete mode 100644 .machine_readable/descriptiles/AGENTIC.a2ml delete mode 100644 .machine_readable/descriptiles/ECOSYSTEM.a2ml delete mode 100644 .machine_readable/descriptiles/META.a2ml delete mode 100644 .machine_readable/descriptiles/NEUROSYM.a2ml delete mode 100644 .machine_readable/descriptiles/PLAYBOOK.a2ml delete mode 100644 .machine_readable/descriptiles/STATE.a2ml diff --git a/.machine_readable/CLADE.a2ml b/.machine_readable/CLADE.a2ml deleted file mode 100644 index 7fc477c5..00000000 --- a/.machine_readable/CLADE.a2ml +++ /dev/null @@ -1,52 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Clade declaration — part of the gv-clade-index registry -# See: https://github.com/hyperpolymath/gv-clade-index - -[identity] -name = "hypatia" -project = "hypatia" -uuid = "32793824-07a1-5c4d-8518-19e0981c4f57" -primary-forge = "github" -primary-owner = "hyperpolymath" -canonical-name = "hypatia" -prefixed-name = "ax-hypatia" - -[clade] -primary = "ax" -secondary = ["sc"] -assigned = "2026-03-16" -rationale = "" - -[forges] -github = "hyperpolymath/hypatia" -gitlab = "hyperpolymath/hypatia" -bitbucket = "hyperpolymath/hypatia" - -[lineage] -type = "standalone" -parent = "Neurosymbolic CI/CD intelligence — rule-based scanning" -born = "2026-03-16" - -# Lifecycle status (added by clade-status-backfill; see gv-clade-index ADR 0006). -# Identity (uuid) and status are SEPARATE layers: uuid follows the GitHub path -# (a move or rename there mints a new one, gv-clade-index ADR 0007; a mirror -# move or a phase change never does); phase is a mutable pointer. No phase is -# terminal (extinct -> active is a legal "Gitassic Park" transition on the same -# uuid). A prefixed-name (clade code) change with the GitHub path unchanged is -# NOT a phase change — the old prefixed-name goes to aliases[], uuid and phase -# are untouched. -[status] -# One of: reserved incubating active dormant | merged superseded archived extinct -phase = "active" -since = "2026-03-16" -present = true -aliases = [] -merged-into = "" -superseded-by = "" -successors = [] -ended = "" - -[[status.history]] -phase = "active" -since = "2026-03-16" -note = "backfilled default — correct if the true phase differs" diff --git a/.machine_readable/descriptiles/AGENTIC.a2ml b/.machine_readable/descriptiles/AGENTIC.a2ml deleted file mode 100644 index d69fd8df..00000000 --- a/.machine_readable/descriptiles/AGENTIC.a2ml +++ /dev/null @@ -1,88 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -# -# AGENTIC.a2ml — AI agent constraints and capabilities -# Defines what AI agents can and cannot do in this repository. - -[metadata] -name = "AGENTIC" -project = "hypatia" -version = "0.2.0" -last-updated = "2026-08-07" - -[agent-permissions] -can-edit-source = true -can-edit-tests = true -can-edit-docs = true -can-edit-config = true -can-create-files = true - -[agent-constraints] -# What AI agents must NOT do: -forbidden = [ - "Use banned Elixir patterns: believe_me, unsafeCoerce, Obj.magic", - "Use banned Idris2 patterns: believe_me, assert_total, partial without annotation", - "Commit secrets or credentials", - "Use banned languages: TypeScript, Go, Python (non-SaltStack), Node.js, npm, Bun", - "Place state files in repository root — .machine_readable/6a2/ ONLY (NOTE: RSR v2.0 3.1.x requires .machine_readable/descriptiles/; migration pending, see docs/DEBT-REGISTER.md M-1)", - "Use AGPL license (this is a MPL-2.0 repo)", - "Start GenServer via start_supervised! when Application supervisor already owns it — use take_supervised/1 instead", - "Claim '0 failures' without running mix test and observing actual output", - "Use Logtalk — removed 2026-04-14; all rules are pure Elixir", - "Emit JSON from tooling — emit A2ML (data) or Nickel (schemas)", -] - -[maintenance-integrity] -fail-closed = true -require-evidence-per-step = true -allow-silent-skip = false -require-rerun-after-fix = true -release-claim-requires-hard-pass = true -completion-claim-requires-behavioural-tests = true - -[workflow-pin-detection] -# Hypatia's half of the pin-propagation architecture -# hypatia (this: detection) -> gitbot-fleet (actuation) -> .git-private-farm (propagation) -# Every rule here has a fleet fix script that carries the SAME facts, so a -# detection without a repair, or a repair without a detection, is a drift: -# WF026 workflow_audit.ex SHA-pinned dtolnay/rust-toolchain with no toolchain: input -> fleet fix-rust-toolchain-input.sh -# (detected in block YAML and KYAML/flow style alike, Y-3; repaired in block style only — -# a KYAML, flow-step, anchored or aliased finding carries auto_fixable: false and routes to review) -# WF027 workflow_audit.ex caller pinned at a reusable revision MEASURED dead (table) -> fleet fix-stale-reusable-pin.sh (Window A) -# WF028 workflow_audit.ex job calls a reusable by a MOVED repository's former name -> NO fleet fixer yet (auto_fixable: false; -# (table: StandardsRepo.former/0 -> current; one row per transfer, appended when it lands) owner re-point is gitbot-fleet's to build) -# PIN-003 pr-automerge-policy.json standards revisions whose own actions.lock GitHub -# rejects at job setup (545 commits, 2026-08-19..2026-10-19; PI001/PA001 fire) -> fleet fix-stale-reusable-pin.sh (Window B) -# known_reusables (sha_bump_propagation.ex) now include hyperpolymath/cicd-suite's gates -may-extend-dead-revision-tables = true # only from a MEASURED walk (file content or lock record checked per commit), never from dates -may-name-a-replacement-revision = false # a human chooses it against standards/scripts/lock-selfcheck.sh; agents carry the choice into the table -must-mirror-fleet-tables = true # WF027's list == fleet stale-reusable-pins.tsv Window A; PIN-003 == Window B; regenerate together -must-not-promote-to-blocking = true # these rules report and route to the fleet; a gate that blocks on them is an owner decision - -[automation-hooks] -on-enter = [ - "Read 0-AI-MANIFEST.a2ml or AI.a2ml first", - "Read .machine_readable/6a2/STATE.a2ml to understand current project state", - "Read .claude/CLAUDE.md for project-specific coding conventions", -] -on-exit = [ - "Update STATE.a2ml session-history with work done", - "Update crg-grade if promotion criteria met (mix test 0 failures required)", - "Commit all 6 a2ml files together in one commit when updated", -] -on-commit = [ - "Run mix test (0 failures required)", - "Run mix format", - "Run cargo clippy if Rust changed", - "Verify SPDX headers on new files", -] - -[max-automation] -max-prs-per-hour-per-agent = 10 -max-auto-execute-confidence-threshold = 0.95 -require-human-review-below-confidence = 0.85 - -[sprint-patterns] -# Patterns recorded during 2026-04-25 sprint for estate-wide reuse: -take_supervised = "Private helper for isolated GenServer tests vs Application-supervised processes. Supervisor.terminate_child + delete_child → start_supervised! → on_exit restore. Fixes {:already_started, pid} from ExUnit start_supervised!." -evict_expired_ttl_fix = "evict_expired boundary condition: use >= ttl not > ttl. System.monotonic_time(:second) is integer-truncated; strict > misses entries at exactly TTL age." diff --git a/.machine_readable/descriptiles/ECOSYSTEM.a2ml b/.machine_readable/descriptiles/ECOSYSTEM.a2ml deleted file mode 100644 index 38589dc8..00000000 --- a/.machine_readable/descriptiles/ECOSYSTEM.a2ml +++ /dev/null @@ -1,69 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# ECOSYSTEM.a2ml — Ecosystem position and relationship map -# Converted from ECOSYSTEM.scm on 2026-03-15; expanded 2026-04-25 - -[metadata] -project = "hypatia" -ecosystem = "hyperpolymath" -last-updated = "2026-08-07" -media-type = "application/a2ml" # record dialect, not Scheme - -[position] -type = "component" -category = "ci-intelligence" -tier = "infrastructure" -purpose = "Neurosymbolic CI/CD intelligence layer — scans repos via panic-attack, classifies findings through the Safety Triangle, dispatches fixes to gitbot-fleet, learns from outcomes via 5 neural networks." -role = "producer-and-consumer" - -[position.consumers] -boj-server = "Hypatia MCP cartridge at boj-server/cartridges/hypatia-mcp/ (283 LOC, Deno mod.js + Idris2 ABI + Zig FFI)" -panll = "Receives real-time dashboard JSON from PanLL data bridge" -estate-workflows = "hypatia-scan.yml runs in every RSR repo .github/workflows/" - -[position.producers] -verisim-data = "Reads git-backed flat-file canonical store via VCL queries + FileExecutor" -panic-attack = "Consumes JSON AssailReport from panic-attack estate scans" -gitbot-fleet = "Dispatches to rhodibot, echidnabot, sustainabot, glambot, seambot, finishbot, panicbot" - -[related-projects] -[[related-projects.sibling]] -name = "verification-ecosystem/echidnabot" -relationship = "sibling-standard" -description = "Receives ProofObligation dispatches from Hypatia FleetDispatcher at confidence >= 0.85. Retrain loop feeds back via LearningScheduler N5." - -[[related-projects.sibling]] -name = "verification-ecosystem/ephapax" -relationship = "sibling-standard" -description = "Linear-type verifier. Hypatia classifies ephapax-relevant findings and routes to echidnabot for formal verification." - -[[related-projects.sibling]] -name = "verification-ecosystem/o" -relationship = "sibling-standard" -description = "Peer verification tool in the verification-ecosystem monorepo." - -[[related-projects.infrastructure]] -name = "nextgen-databases/verisim" -relationship = "data-dependency" -description = "VeriSimDB provides the canonical flat-file store (verisim-data) that Hypatia reads via VCL queries." - -[[related-projects.infrastructure]] -name = "fleet-ecosystem/git-automation-ecosystem/gitbot-fleet" -relationship = "dispatch-target" -description = "7 bots (rhodibot, echidnabot, sustainabot, glambot, seambot, finishbot, panicbot) receive dispatches from FleetDispatcher." - -[[related-projects.infrastructure]] -name = "verification-ecosystem/panic-attack" -relationship = "scanner-source" -description = "panic-attack assail produces JSON AssailReport consumed by Hypatia rules engine. panicbot wraps the CLI." - -[[related-projects.infrastructure]] -name = "boj-server" -relationship = "mcp-host" -description = "All Hypatia MCP capabilities served via BoJ MCP cartridge. No standalone MCP server." - -[integration-points] -groove-protocol = "All inter-service comms use Groove. HTTP port 9090 (configurable)." -vcl-queries = "VCL Client GenServer parses + caches + executes queries against verisim-data flat files." -dispatch-manifest = "JSONL manifests written to dispatch/pending.jsonl, consumed by dispatch-runner.sh." -outcome-tracker = "Outcomes appended to outcomes/YYYY-MM.jsonl, drive Bayesian confidence updating." -neural-persistence = "Neural states persisted to data/verisim/neural-states/ via lib/neural/persistence.ex." diff --git a/.machine_readable/descriptiles/META.a2ml b/.machine_readable/descriptiles/META.a2ml deleted file mode 100644 index a738d103..00000000 --- a/.machine_readable/descriptiles/META.a2ml +++ /dev/null @@ -1,77 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# META.a2ml — Project meta-information and architectural decisions -# Converted from META.scm on 2026-03-15; expanded 2026-04-25 - -[metadata] -project = "hypatia" -author = "Jonathan D.A. Jewell " -license = "MPL-2.0" -standard = "RSR 2026" -last-updated = "2026-08-07" -media-type = "application/a2ml" # record dialect, not Scheme - -[development-practices] -versioning-scheme = "semver" -documentation-format = "AsciiDoc" -build-tool = "mix (Elixir) + cargo (Rust) + just (task runner)" -test-command = "mix test" -format-command = "mix format && cargo fmt" -ci-command = "just quality" -commit-strategy = "one unit = one commit; specific staged paths only" -branch-strategy = "main only; PRs for external contributions" -release-process = "version-bump in STATE.a2ml → just quality → tag → push" - -[architecture-decisions] -# ADR-001 — 2026-04-14: Pure-Elixir rules engine (Logtalk removed) -[[architecture-decisions.adr]] -id = "ADR-001" -status = "accepted" -date = "2026-04-14" -title = "Replace Logtalk rule engine with pure Elixir rules" -context = "Logtalk added SWI-Prolog runtime dependency; CI instability; Hypatia's symbolic reasoning is pattern matching not first-order logic." -decision = "Purge Logtalk entirely. Move all rules to lib/rules/*.ex as pure Elixir functions with ExUnit tests. Remove engine/ directory." -consequences = "Single-language stack (Elixir + Rust + Idris2 + Zig). No SWI-Prolog in Containerfiles. Hypatia now consumes JSON AssailReport from panic-attack via Elixir rules." - -# ADR-002 — 2026-04-05: VQL renamed to VCL, verisimdb renamed to verisim -[[architecture-decisions.adr]] -id = "ADR-002" -status = "accepted" -date = "2026-04-05" -title = "Rename VQL→VCL and verisimdb→verisim throughout" -context = "VQL (VeriSim Query Language) conflated with SQL-style naming. VeriSim Constraint Language is more accurate." -decision = "141 files renamed. HYPATIA_VERISIMDB_URL → HYPATIA_VERISIM_URL. VerisimdbConnector → VerisimConnector. lib/vql/ → lib/vcl/." -consequences = "Estate-wide rename completed in one commit. API callers must update env vars." - -# ADR-003 — 2026-04-11: Proof learning loop via FleetDispatcher -[[architecture-decisions.adr]] -id = "ADR-003" -status = "accepted" -date = "2026-04-11" -title = "Route ProofObligations through FleetDispatcher to echidnabot" -context = "Proof obligations were being classified but not dispatched. Safety Triangle applies equally to formal verification dispatch." -decision = "classify/2 in ProofObligation routes eliminate→robot-repo-automaton, substitute→echidnabot, control→sustainabot. Confidence gating applies. VeriSimDB round-trip avoided via :prover_hint_override." -consequences = "Learning loop closed: outcomes feed LearningScheduler N5 retrain." - -# ADR-004 — 2026-04-22: Neural training data rebalancer -[[architecture-decisions.adr]] -id = "ADR-004" -status = "accepted" -date = "2026-04-22" -title = "Synthetic rebalancer (Strategy A) as default; B+C deferred to M9" -context = "Historical outcome log is ~99% success, biasing RBF/ESN training. Need representative failure distribution." -decision = "lib/neural/rebalancer.ex adds synthetic regressions + rule-based RBF targets (Strategy A, on by default). Strategy B (adversarial perturbation) and C (real failure corpus from panic-attack history) deferred to M9." -consequences = "Immediate improvement in training balance. B+C require additional data pipeline work." - -# ADR-005 — 2026-04-25: take_supervised/1 test isolation pattern -[[architecture-decisions.adr]] -id = "ADR-005" -status = "accepted" -date = "2026-04-25" -title = "Use take_supervised/1 for isolated GenServer tests against Application-supervised processes" -context = "start_supervised! fails with {:already_started, pid} when the Application supervisor has already claimed a globally-named GenServer." -decision = "Private take_supervised/1 helper: Supervisor.terminate_child + delete_child → start_supervised! (clean state) → on_exit restore to Application supervisor. Used in reflexive_test.exs and contract_test.exs." -consequences = "All 25 test isolation failures resolved. Pattern is reusable for any test needing a fresh Application-supervised GenServer." - -[maintenance-axes] -priority-order = "dependability > security > interop > usability > performance > versatility > extension" -scoping-first = true diff --git a/.machine_readable/descriptiles/NEUROSYM.a2ml b/.machine_readable/descriptiles/NEUROSYM.a2ml deleted file mode 100644 index e43db348..00000000 --- a/.machine_readable/descriptiles/NEUROSYM.a2ml +++ /dev/null @@ -1,64 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -# -# NEUROSYM.a2ml — Neurosymbolic integration metadata -# Configuration for Hypatia scanning and symbolic reasoning. - -[metadata] -version = "0.2.0" -last-updated = "2026-08-07" - -[hypatia-config] -scan-enabled = true -# "deep" = full estate scan (302 repos); use "standard" for per-repo CI runs -scan-depth = "deep" -# JSON AssailReport from panic-attack; Logtalk removed 2026-04-14 -report-format = "json" -verisim-data-path = "data/verisim" -fleet-path = "$HYPATIA_FLEET_PATH" # env var, not a user-specific absolute path - -[neural-config] -confidence-threshold-auto-execute = 0.95 -confidence-threshold-review = 0.85 -confidence-floor = 0.10 -confidence-cap = 0.99 -bayesian-prior-strength = 10 -networks = ["graph-of-trust", "mixture-of-experts", "liquid-state-machine", "echo-state-network", "radial-neural-network"] -# GNN, VAE, SequenceModel added 2026-04-25 sprint (new layer) -networks-extended = ["graph-neural-network", "variational-autoencoder", "sequence-model"] -coordinator = "lib/neural/coordinator.ex" -persistence = "lib/neural/persistence.ex" -state-dir = "data/verisim/neural-states" -rebalancer = "lib/neural/rebalancer.ex" -rebalancer-strategy-a = "done" -rebalancer-strategy-b = "done" -rebalancer-strategy-c = "done" - -[symbolic-rules] -# Project-specific rules beyond the estate-wide RSR ruleset. -[[symbolic-rules.rule]] -id = "HYP-001" -name = "null-fix-script detector" -pattern = "auto_execute entry with fix_script = null" -severity = "medium" -source = "lib/rules/cicd_rules.ex" - -[[symbolic-rules.rule]] -id = "HYP-002" -name = "confidence-below-floor detector" -pattern = "recipe confidence < 0.10 after >= 10 outcomes" -severity = "high" -source = "lib/outcome_tracker.ex" - -[[symbolic-rules.rule]] -id = "HYP-003" -name = "circuit-breaker-open alert" -pattern = "SelfDiagnostics.circuit_state() == :open" -severity = "critical" -source = "lib/self_diagnostics.ex" - -[proof-integration] -proof-strategy-selection = "PS001–PS010 (lib/rules/proof_strategy_selection.ex)" -proof-obligation = "PO001–PO006 (lib/rules/proof_obligation.ex)" -echidnabot-route = "ProofObligation.classify confidence >= 0.85 → FleetDispatcher → echidnabot" -prover-recommender = "lib/neural/prover_recommender.ex (RBF, 8-D feature vectors, 1108 samples)" diff --git a/.machine_readable/descriptiles/PLAYBOOK.a2ml b/.machine_readable/descriptiles/PLAYBOOK.a2ml deleted file mode 100644 index 22b0af83..00000000 --- a/.machine_readable/descriptiles/PLAYBOOK.a2ml +++ /dev/null @@ -1,78 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -# -# PLAYBOOK.a2ml — Operational runbook -# Runbooks, incident response, deployment procedures. - -[metadata] -name = "PLAYBOOK" -project = "hypatia" -version = "0.2.0" -last-updated = "2026-08-07" - -[deployment] -method = "gitops" -target = "container" -container-tool = "Podman (not Docker)" -containerfile = "deploy/Containerfile" -base-image = "Chainguard Elixir base" -http-port = 9090 -env-vars = [ - "HYPATIA_VERISIM_URL — URL for verisim-data git-backed store", - "HYPATIA_FLEET_PATH — path to gitbot-fleet checkout", - "HYPATIA_DISPATCH_PAT — GitHub PAT with repo scope for live dispatch (M7, done 2026-05-24)", - "HYPATIA_HTTP_PORT — override HTTP port (default 9090)", -] -start-command = "mix run --no-halt" -pre-flight = ["mix deps.get", "mix compile", "mix test"] - -[incident-response] -steps = [ - "1. Check .machine_readable/6a2/STATE.a2ml for current status and known blockers", - "2. Review recent commits: git log --oneline -20", - "3. Run mix test to check for regressions (0 failures expected)", - "4. Check SelfDiagnostics.health_report() for circuit breaker state", - "5. Check SelfDiagnostics.circuit_state() — if :open, dispatch is queued to pending.jsonl", - "6. Review dispatch/held.jsonl and dispatch/pending.jsonl for queued items", - "7. Run just validate to check RSR compliance", - "8. Check Quarantine.list_quarantined() for bots in hard/permanent quarantine", - "9. If circuit is open: wait for cooldown (15 min) or send :try_half_open to SelfDiagnostics", - "10. If bot is quarantined: investigate cause, call Quarantine.release(bot) when resolved", -] - -[release-process] -steps = [ - "1. Update version in mix.exs", - "2. Update STATE.a2ml: last-updated, completion-percentage, session-history", - "3. Update META.a2ml if architecture decisions changed", - "4. Run just quality (mix format + mix test + cargo clippy + cargo test)", - "5. Commit all 6 a2ml files together: chore(6a2): update state post-release vX.Y.Z", - "6. Tag: git tag -s vX.Y.Z -m 'Release X.Y.Z'", - "7. Push: git push origin main --tags", -] - -[maintenance-operations] -baseline-audit = "mix test && cargo test && just validate" -hard-pass-gate = "mix test 0 failures (233 :verisim_data excluded by design)" -neural-retrain = "Hypatia.Neural.Coordinator.force_cycle() — :ok means queued; inspect Coordinator.status() for source refusal and cycle completion" -neural-source-lifecycle = "docs/architecture/neural-source-lifecycle.adoc — an observed data-root change requires an explicit decision and fresh matching cohort; no automatic relabel/restart" -scan-estate = "just scan (runs panic-attack assail across estate, writes to verisim-data)" -dispatch-run = "just dispatch (runs dispatch-runner.sh against pending.jsonl)" -crg-check = "Review STATE.a2ml [project-context] crg-grade vs crg-grade-target" - -[crg-promotion-criteria] -d-to-c = [ - "mix test 0 failures (excluding :verisim_data tag)", - "All test files have SPDX headers", - "Per-subtree README.adoc files in all key directories", - "Dogfooding evidence populated in STATE.a2ml", - "7+ Zig FFI domain functions implemented", -] -c-to-b = [ - "GitHub PAT configured for live dispatch (M7 done)", - "Fix script coverage > 90% (M8 done)", - "Neural rebalancer Strategy B+C complete (M9 done)", - "Ada TUI wired into Elixir supervision tree (M10 done)", - "verisim-api deployed (G1 resolved)", - "Integration tests pass against live verisim-data", -] diff --git a/.machine_readable/descriptiles/STATE.a2ml b/.machine_readable/descriptiles/STATE.a2ml deleted file mode 100644 index 6f676089..00000000 --- a/.machine_readable/descriptiles/STATE.a2ml +++ /dev/null @@ -1,315 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# STATE.a2ml — Project state checkpoint -# Converted from STATE.scm on 2026-03-15 - -[metadata] -project = "hypatia" -version = "0.1.0" -last-updated = "2026-08-07" -status = "active" - -[project-context] -name = "hypatia" -completion-percentage = 98 -phase = "implementation" -maturity = "alpha" -crg-grade = "C" -crg-grade-declared-on = "2026-04-25" -crg-grade-target = "B" -crg-grade-notes = "Promoted D→C 2026-04-25: mix test 0/528 failures (233 verisim_data excluded by design); take_supervised/1 pattern fixed 25 test isolation failures in reflexive/contract suites; evict_expired >= ttl fix; 24 per-subtree README.adoc files; 7 Zig FFI domain functions. Closed 2026-05-24 (PR #309): live GitHub PAT dispatch operational, fix-script coverage gap resolved (root cause was matcher bug not missing scripts), watcher/supervision interface delivered end-to-end (telemetry → ETS aggregator → JSON/SSE/Prometheus/HTML/TUI → alerts/persistence/anomaly). B blockers remaining: neural B+C rebalancer strategies, Ada TUI supervision wiring." - -[dogfooding-status] -# Populated 2026-04-18 against real on-disk integrations. Each entry must -# resolve to a grep-hit in the cited path. -boj-server-mcp = "2026-04-18 — hypatia-mcp cartridge (283 LOC, Deno mod.js + Idris2 ABI + Zig FFI). Path: boj-server/cartridges/hypatia-mcp/" -gitbot-fleet-consumer = "2026-04-18 — FleetDispatcher routes to gitbot-fleet (rhodibot, echidnabot, sustainabot, glambot, seambot, finishbot, panicbot). 1635 dispatched actions, 16671 outcomes recorded. Path: lib/fleet_dispatcher.ex" -estate-rsr-scan = "2026-04-18 — hypatia-scan.yml runs in every RSR repo (15+ repos); 302 repos scanned, 3385 weak points logged. Evidence: count of hypatia-scan.yml files across estate .github/workflows/" -verisim-data-flat-store = "2026-04-18 — git-backed flat-file canonical store consumed via VCL queries + FileExecutor. Path: lib/verisim_connector.ex" -panll-data-bridge = "2026-04-18 — generates real-time JSON for PanLL dashboard panels" -scorecard-ingestion = "2026-04-18 — 20 OpenSSF Scorecard checks ingested as local scan patterns. Path: lib/scorecard_ingestor.ex" - -[route-to-mvp] -milestones = [ - { id = "M1", title = "Safety Triangle + FleetDispatcher pipeline", status = "done" }, - { id = "M2", title = "5 neural networks (RBF, ESN, LSM, MoE, GoT)", status = "done" }, - { id = "M3", title = "VCL query layer + verisim-data connector", status = "done" }, - { id = "M4", title = "ProofStrategySelection (PS001–PS010)", status = "done" }, - { id = "M5", title = "ProofObligation recipe type (PO001–PO006)", status = "done" }, - { id = "M6", title = "LearningScheduler N5 — ProverRecommender retrain", status = "done" }, - { id = "M7", title = "GitHub PAT for live cross-repo dispatch", status = "done" }, - { id = "M8", title = "Write real fix scripts (310 null-fix-script entries)", status = "done" }, - { id = "M9", title = "Neural rebalancer Strategy B+C operationalised via :neural_rebalance_strategy config (:a | :b | :c | :rotate)", status = "done" }, - { id = "M10", title = "Ada TUI Elixir supervision wiring (Port wired + /metrics/snapshot endpoint added)", status = "done" }, - { id = "M11", title = "Watcher / supervision interface (telemetry → aggregator → API/SSE/Prometheus/TUI → alerts/persistence/anomaly)", status = "done" }, - { id = "M12", title = "Closed-loop quality (soundness gates, verification metric, auto-quarantine)", status = "done" }, - { id = "M13", title = "SARIF output for IDE integration", status = "done" }, - { id = "M14", title = "GraphQL API as live HTTP endpoint", status = "done" }, - { id = "M15", title = "Bearer-token auth + persistent state across restart + cross-host federation + ESN tight integration", status = "done" }, - { id = "M16", title = "Neural state persistence: MoE + trust_graph hydration on init (LSM/ESN summary-only by design)", status = "done" }, - { id = "M17", title = "GNN + VAE + Seq state/restore persistence (already wired into Coordinator phases pre-PR-309)", status = "done" }, - { id = "M18", title = "Cross-organization federation with VCL drift policies (lib/vcl/cross_org.ex + telemetry events)", status = "done" }, - { id = "M19", title = "Prover Wars integration (dodeca-API / VeriSimDB / ABI / VCL-UT)", status = "planned" }, - { id = "M20", title = "verisim-api deployment + Hypatia.VCL.ApiExecutor", status = "planned" }, - { id = "M21", title = "Nx/EXLA neural backend (conditional on reservoir size growth)", status = "planned" }, -] - -[blockers-and-issues] -issues = [ - # B1 resolved 2026-05-24: HYPATIA_DISPATCH_PAT provisioned, verified end-to-end - # (19 hypatia-security-alert dispatches landed in gitbot-fleet on first sweep). - # B2 resolved 2026-04-26: 14 fix scripts written + 12 recipes updated (M8 done). - # B3 resolved 2026-05-24: matcher language-gate bug fixed (PR #309 commit d2bbf75) — - # was the underlying cause of the "310 null fix_script" symptom; scripts existed. -] - -[known-gaps] -gaps = [ - { id = "G1", description = "verisim-api not deployed — graph/vector/temporal modalities via flat files only" }, - # G2 resolved 2026-04-26: M8 done — all 14 gaps closed - { id = "G3", description = "Containerfiles: Haskell still uses non-Chainguard base images (no upstream equivalents)" }, - { id = "G4", description = "Neural training balance: Strategy A done (rebalancer.ex); B (adversarial) + C (panic-attack failure corpus) in progress as M9" }, -] - -[critical-next-actions] -actions = [ - # M7 DONE 2026-05-24: HYPATIA_DISPATCH_PAT provisioned + verified. - # M8 DONE 2026-04-26: 14 scripts written, 12 recipes updated, RecipeGenerator extended. - # M11 DONE 2026-05-24 (PR #309): watcher/supervision interface, 3-phase delivery. - # M12 DONE 2026-05-24 (PR #309): soundness gates + closed-loop verification. - "Complete neural rebalancer Strategy B+C (M9)", - "Complete Ada TUI Elixir supervision wiring (M10)", -] - -[session-history] -# 2026-06-02: PR #422 — WorkflowAudit WF024 chapel_runs_on_drift auto-fix -# (Chapel jobs missing ubuntu-22.04 pin) + WF025 cron_schedule_drift -# + BaselineHealth BH008 inherited_main_debt (workflows on red main -# before a branch is cut). PR #415 — flipped SC-010 -# transitive_dep_drift to auto_fixable:false (manual review only). -# PR #414 — scoped MPL-2.0 carve-outs for upstream-derived -# submodules (license carve-out documentation). -# 2026-05-31: Cohort #333 + Group-B CI/CD detection rules. Merged -# duplicate_cron_schedule (#362), WF021 concurrency_missing_readonly -# (#365), WF022 unanchored_heading_regex (#360). Reverted a duplicate -# #390 scorecard rule (already shipped as WF018 in #403). Added Group-B -# detectors SD021 workflow_branch_refs (#363), WF023 -# stale_continue_on_error (#364), HonestCompletion stale_issue_refs -# (#366) — pure functions taking an injected signal (branch list / -# closed-issue set); the live-signal scan-flow wiring is the remaining -# follow-up noted on each issue. #339 was already covered by BP008. -# 2026-05-25: PRs #314 + #315 + #319 — post-#313 batch + repo health tidy. -# PR #314 (15 commits, merged): M17 GNN/VAE/Sequence state/restore -# persistence; M18 cross-org VCL federation with policy gates; M9 -# longitudinal effectiveness mix task; container hardening + -# Chainguard gap memo; five operations memos; CrossOrg wired into -# LearningScheduler; dashboard alerts ribbon; PR-#314 noise reduction -# (workflow_audit @standard_workflows trimmed, migration_rules -# suppression, honest_completion namespaced-state check, Phase 2 -# medium+ severity filter); mix hypatia.triage_issues task for -# bulk-closing PR-invalidated estate issues. -# PR #315 (2 commits, merged): root-level doc reorg into docs/ -# subtrees aligned to rsr-template-repo; 30 root files → 9 -# standard project chrome only; new docs/{quickstart,guides, -# operations,proofs,testing,integration,history,wiki-pages}/ -# subdirs; CONTRIBUTING.adoc + DOGFOODING-SESSION-2026-01-25.md -# deleted; README badges + Graph Intelligence line corrected -# (ArangoDB → verisim-data); wiki page sources (Home, Architecture, -# Getting-Started, Guides, FAQ, Troubleshooting) committed to -# docs/wiki-pages/ for manual copy to the live wiki. -# PR #319 (1 commit, open): second-pass docs/ bucketing — -# security/, standards/, specs/ subdirs created; docs/ root now -# 4 files + 16 subdirs. -# Issues triaged: #274 (Neural organs UNFED) closed as completed -# with full resolution chain documented; #294 (boundary ruling) -# commented with Option A recommendation memo location; #273 -# (architecture epic) status update. -# completion-percentage 97 → 98. -# -# 2026-05-24: PR #309 — watcher/supervision interface + closed-loop quality. 19 commits. -# Bug fixes (4): recipe-matcher language-gate (`d2bbf75` — unblocked ~310 -# scorecard dispatches; the "310 null fix_script" symptom's real cause was -# a matcher bug treating `"any"` sentinel as unmatched and `"yaml"` recipes -# as unreachable, not missing scripts), baseline regen (`7cc2667` — 71 stale -# → 35 fresh, 0 critical/0 high), secret + code scanning alert consumers -# (`e929621`), `@language_extensions` walker missing `.agda`/`.zig`/`.thy`/ -# `.fst`/`.adb` (`6d40240` — caught by the new escript packaging soundness -# test on its first run; same PR #278 class). -# Soundness gates (3): in-process manifest test with 14 fixtures (`74173ee`), -# end-to-end escript-build test wired into e2e-elixir CI (`6d40240`), honest -# doc on why other rule families don't drop into the manifest pattern -# (`3569d47`). -# Closed-loop quality (3): verification_rate + recipe_health + `mix -# hypatia.recipe_health` (`12f2890`), `record_outcome_for_fix` + `mix -# hypatia.record_outcome` CLI wrapper for the bash dispatch-runner with -# non-zero exit on still_present (`5e895b5`), auto-quarantine in -# FleetDispatcher when verification rate < 0.30 over ≥5 verifiable outcomes -# (`97b299f`). -# Watcher Phase 1 (4): `Hypatia.Telemetry` event registry + emit helpers -# (`d0ddd2f`), `Hypatia.Watcher` GenServer + ETS rolling-window aggregator -# (`3b4379e`), `/api/status` + `/api/counts/:window` + `/api/recipes` -# loopback-only via `Hypatia.Web.ApiRouter` (`30ced35`), `mix hypatia.watch` -# terminal dashboard (`708a19b`). -# Watcher Phase 2 (3): SSE stream at `/api/events` + `/api/recipes/:id` + -# `/api/quarantine` drill-downs (`5b15430`), static HTML dashboard at `/` -# with vanilla JS + EventSource (`a0075db`), Prometheus `/metrics` -# exposition (`adc2863`). -# Watcher Phase 3 (3): threshold rules + pluggable sinks (Log/Webhook/File) -# + `/api/alerts` (`3750086`), 5-min snapshot persistence to -# data/verisim/metrics/YYYY-MM-DD.jsonl (`a1eb6b2`), statistical anomaly -# detector with 2σ baseline divergence + ESN drift corroboration -# (`fc4f5d0`). -# Plus housekeeping (this commit): ROADMAP + STATE updates marking M7/M8/M11/ -# M12 done; v7.5 (watcher) + v7.6 (closed-loop quality) sections added; M13/ -# M14/M15 added for the remaining roadmap items. -# PAT verification: 19 hypatia-security-alert events landed in gitbot-fleet -# from the first manual sweep, all completing 17-26s, confirming the closed -# loop is operational end-to-end for the first time in the session. -# -# 2026-05-21: Epic #273 — Hypatia architecture reconciliation & neurosymbolic activation. -# Four-gap landing (one session, owner-merge gated): -# Gap (1) UNFED neural organs — already on `main` via PR #275 (merged -# 2026-05-18). lib/learning_scheduler.ex:125 → force_cycle(); -# lib/neural/coordinator.ex:90 → load_all() + RBF hydrate. -# Closure-recommendation comment posted on #274 (no self-close). -# Gap (2) snif/private-verisimdb boundary — DECISION-READY, awaiting owner -# ruling. Sub-issue #294 (A / B / C). PR #295 commits the memo -# as docs/architecture/boundary-design-options.adoc with explicit -# OPEN status NOTE. The naive VCL → SNIF → verisimdb chain is -# physically impossible (SNIFs are wasm32-freestanding zero-imports; -# verisim-nif is placeholder; no conformant Elixir/Zig VCL parser). -# Recommendation: Option A (split — SNIF for parse+check only, -# host-side Rustler NIF to private verisimdb). -# Gap (3) cicd-hyper-a name purge — sub-issue #292 + PR #293. Mechanical -# 1-to-1 rename across 87 files / 477 lines. Cargo packages already -# canonicalised to hypatia-*; only doc-comments, banners, README -# examples, helm/registry refs, security.yml hashFiles guards, -# scripts, hooks, machine-readable refs. 0 occurrences remaining -# outside .git/. `cargo metadata --no-deps` invariant (same 7 -# packages / versions). `cargo check -p hypatia-cli --offline` clean. -# Gap (4) no UML/MOF/TOGAF — PR #291. Adds docs/architecture/togaf-overview.adoc -# (TOGAF baseline, P1-P6, ADR-001..ADR-006) + mof-metamodel.adoc -# (OMG MOF M2: 10 metaclasses, meta-associations, OCL-style -# invariants, TARGET delta). Every claim grounded in lib/...:N. -# proof_resolver.ex confirmed vestigial (zero callers). -# Mermaid diagrams under docs/diagrams/ marked superseded. -# Cross-PR: PR #291 touches docs/architecture/README.md to add the new -# rows; PR #295 deliberately does NOT touch README to avoid textual -# conflict. Whichever merges second adds a single line for -# boundary-design-options.adoc. -# PRs opened: #291, #293, #295. Issues opened: #292, #294. Comments -# posted on #273 (status table) + #274 (closure rec). Nothing merged. -# -# 2026-04-26: M8 — Real fix scripts for 310 null-fix-script dispatch entries. -# 1. Identified 14 gaps: 12 null-fix-script scorecard recipes + -# 2 recipes referencing scripts that didn't exist on disk. -# 2. Wrote 14 new bash fix scripts in scripts/fix-scripts/: -# fix-add-elixir-ci.sh (Elixir CI workflow) -# fix-elixir-ssl-verify.sh (SSL :verify_none → :verify_peer) -# fix-scorecard-binary-artifacts.sh (SC-001) -# fix-scorecard-ci-tests.sh (SC-003, auto-generates workflow) -# fix-scorecard-cii-best-practices.sh (SC-004, checklist + badge) -# fix-scorecard-code-review.sh (SC-005, branch protection via gh) -# fix-scorecard-contributors.sh (SC-006, contributor report) -# fix-scorecard-fuzzing.sh (SC-009, cargo-fuzz + CFL scaffold) -# fix-scorecard-maintained.sh (SC-011, maintenance health report) -# fix-scorecard-packaging.sh (SC-012, release workflow) -# fix-scorecard-sbom.sh (SC-015, SBOM workflow) -# fix-scorecard-signed-releases.sh (SC-017, cosign signing) -# fix-scorecard-vulnerabilities.sh (SC-019, Dependabot + SECURITY) -# fix-scorecard-webhooks.sh (SC-020, webhook audit report) -# 3. Updated 12 scorecard recipe JSON files: fix_script field set, -# auto_fixable updated where appropriate. -# 4. Extended RecipeGenerator @category_fix_scripts with 14 new -# category → script mappings. -# 5. M8 → done; B2 resolved; G2 resolved. -# -# 2026-04-25: Sprint — test isolation fixes + CRG D→C promotion. -# 1. Fixed 25 test failures in reflexive_test.exs + contract_test.exs: -# start_supervised! on Application-supervised GenServers raised -# {:already_started, pid}. Fix: take_supervised/1 helper uses -# Supervisor.terminate_child + delete_child + start_supervised! + -# on_exit restore. Gives clean isolated state per test. -# 2. Fixed vcl_remote_cache_test.exs: evict_expired used > ttl (strict); -# with integer-second monotonic time, entries at exactly ttl age were -# never evicted. Changed to >= ttl. -# 3. mix test result: 0 failures (528 tests, 233 excluded by :verisim_data). -# 4. Neural persistence confirmed wired in lib/neural/persistence.ex — -# Gap 5 removed from known gaps. -# 5. M7 + M8 promoted planned → in_progress; M9 (neural B+C rebalancer) -# and M10 (Ada TUI supervision wiring) added as in_progress. -# 6. CRG grade: D → C. New target: B. -# -# 2026-04-25: D→C blocker sweep. -# 1. Test failures: 0 (was 125). Strategy: tagged 9 modules @moduletag :verisim_data, -# 3 vcl_client describe blocks + 1 zig_ffi_smoke_test block @describetag :verisim_data, -# ExUnit configured to exclude :verisim_data by default. -# 2. honest_completion_test: base_evidence/1 helper covers all 14 keys accessed. -# 3. triangle_router_test: accepts {:control,_} fallback when recipe files absent. -# 4. zig_ffi_smoke_test: 7 Zig FFI domain functions added to ffi/zig/src/main.zig -# with real verisim-data file I/O implementations. -# 5. 24 per-subtree README.adoc files added (lib/ lib/hypatia/ lib/neural/ lib/vcl/ -# lib/safety/ lib/rules/ src/ src/abi/ ffi/ ffi/zig/ test/ test/rules/ cli/ -# adapters/ clients/ integration/ scripts/ docs/ deploy/ benches/ verification/ -# tui/ fixer/ schema/). -# 6. Parent repos-monorepo submodule pointer bumped (18f6f415). -# 2026-04-14: Final Logtalk purge — Deep sweep complete. -# 1. Purged legacy Logtalk CI/CD jobs and artifacts (engine/ gone). -# 2. Promoted Elixir rules to primary status across all documentation. -# 3. Updated architecture diagrams and state files to reflect pure-Elixir logic. -# 4. Removed SWI-Prolog dependencies from stapeln.toml and Containerfiles. -# 2026-04-11: ECHIDNA↔Hypatia coupling — three pieces: -# 1. ProofObligation recipe type (lib/rules/proof_obligation.ex, PO001–PO006): -# classify/2 pure function across Safety Triangle (Eliminate/Substitute/Control) -# with confidence scoring (0.90/0.93/0.96). Prover-agnostic. -# 2. FleetDispatcher extended: dispatch_routed_action/1 for {:proof_obligation, recipe, pattern} -# routes eliminate (≥0.90 conf) → robot-repo-automaton, substitute → echidnabot, -# control → sustainabot. Avoids redundant VeriSimDB round-trip via :prover_hint_override. -# 3. LearningScheduler N5 step: retrain_prover_recommender/0 polls VeriSimDB every 5 min, -# updates ProverRecommender via :persistent_term atomic hot-swap. -# Deleted engine/logtalk/error_instances.lgt + loader.lgt (no-Logtalk constraint). -# All Elixir code mix-format clean. -# 2026-04-05: V4e + V4f + ProverRecommender landed. recommend_with_certs/2 -# enriches strategy output with PROVEN/PENDING from the new -# /certificates endpoint and re-sorts (cert-status primary key). -# Hypatia.VCL.ProofResolver parses PROOF PROVEN(class, prover) -# and PROOF SANCTIFY(class) expressions and resolves them via -# /api/v1/proof_attempts/certificates. Hypatia.Neural.ProverRecommender -# trains 1 global + 8 per-class RBF networks on 1108 samples from -# verisim-api (unfolded from strategy aggregates). Verified live: -# safety/cvc5 pred=0.535 matches real 1.0×42 rate. -# 2026-04-05: VQL → VCL + verisimdb → verisim rename (ecosystem-wide). -# HYPATIA_VERISIMDB_URL env var → HYPATIA_VERISIM_URL. -# VerisimdbConnector → VerisimConnector. lib/vql/ → lib/vcl/. -# 141 files renamed, mix compile passes. -# 2026-04-05: Proof learning loop closed — fleet_dispatcher routes per-bot via -# GraphQL envelope, classifies obligation, fetches strategy from -# verisim-api/proof_attempts/strategy, passes prover hint in -# submitProofObligation mutation to echidnabot. New rule module -# proof_strategy_selection (10/10 tests). Shrunk data/verisimdb.rs -# stubs 165→89 LoC, deleted dead adapters/service.rs ForgeService -# 322→26 LoC. Fixed hmac/digest conflict + bincode 3.0 breakage. -# Test status: 688 tests, 124 pre-existing failures (unchanged). -# 2026-04-04: CRG C blitz — added 70 new tests across 4 files: -# test/e2e_pipeline_test.exs (15 tests: all 6 pipeline stages with real data) -# test/p2p_recipe_vql_test.exs (26 tests: RecipeMatcher/VQL invariants, property-based style) -# test/concurrency_test.exs (16 tests: parallel recipe eval, RateLimiter/Quarantine/VQL under load) -# test/zig_ffi_smoke_test.exs (13 tests: Zig FFI source integrity, data path, dispatch strategy spec) -# All 70 new tests pass. Pre-existing failures (corrupted recipe data) unchanged. -# Benchmarks confirmed real in fixer/benches/hypatia_bench.rs (7 benches, not stubs). -# 2026-04-03: Added 3 new rules: WF013 (permissions typo detection), GS007 (stale branch detection), -# SD013 (gitignore path-scope detection). 279 lines of new rule code, 13 tests. - -[neural-source-lifecycle] -status = "authored-pending-hosted-qualification" -checkpoint-date = "2026-11-04" -contract = "docs/architecture/neural-source-lifecycle.adoc" -source-identity = "expanded configured data-root pathname; not content authentication" -new-regression-source = "test/neural_source_store_lifecycle_test.exs" -authored-new-test-functions = 22 -qualification = "No execution receipt for this new lifecycle candidate. Existing runtime-path test receipts do not qualify it. Exact-source compile, focused and normal full gates remain required." -authority = "No automatic restart, dispatch, or deployment promotion from a source refusal." - -[bridge-report-contract-2026-11-06] -status = "candidate; not merged or deployed" -change = "Validate schema 0.3.0 and vulnerability-data availability before interpreting native lowercase B1 verdicts" -validation = "29 local executable contract cases passed; workflow YAML and embedded shell parsed; upstream TOML dependency fix in panic-attack PR 265 still awaits qualified CI" diff --git a/hypatia_chora.deed b/hypatia_chora.deed index 887a25bd..d2015ca1 100644 --- a/hypatia_chora.deed +++ b/hypatia_chora.deed @@ -3,20 +3,30 @@ ;; ;; The repo deed of hypatia (one deed per repo, standards#837). ;; -;; Clauses translated field for field from .machine_readable/CLADE.a2ml under -;; the mapping spec 1-formats/deed/mappings/clade-to-repo-deed.adoc, the only -;; authority a family translation may cite: (identity) (clade) (forges) -;; (lineage) (status). CLADE's [identity] name and project are not in that -;; table; both repeat canonical-name and are not emitted. :repo-uuid is the -;; ADR-008 profile C UUIDv8 re-derived from the name (spec section 5, P-1), -;; not the v5 that CLADE.a2ml still holds. +;; Every clause below is translated field for field from a retired A2ML +;; descriptile under the mapping spec that governs its family, in standards +;; 1-formats/deed/mappings/ (the only authority a family translation may cite). +;; A field a table does not list does not translate: it was dropped, not +;; re-homed. docs/history/A2ML-REMOVED.adoc records each removed file, its git +;; blob id and what was dropped from it (owner ruling 2026-11-14, "Full +;; migration now"). ;; -;; AGENTIC, NEUROSYM and PLAYBOOK.a2ml carry sections their mapping table does -;; not list (agentic: max-automation, sprint-patterns, workflow-pin-detection; -;; neurosym: proof-integration; playbook: crg-promotion-criteria), so -;; a2ml_to_deed.py refuses them rather than guess. META and ECOSYSTEM are not -;; translated either, and STATE.a2ml waits on state-v1-decision.adoc. All of -;; those stay live and untranslated, as in standards_chora.deed. +;; CLADE.a2ml -> (identity) (clade) (forges) (lineage) (status) +;; clade-to-repo-deed.adoc. CLADE's [identity] name and +;; project repeat canonical-name and are not emitted. +;; :repo-uuid is the ADR-008 profile C UUIDv8 re-derived +;; from the name (spec section 5, P-1), not the v5 that +;; CLADE.a2ml held. +;; META.a2ml -> (meta) meta-ecosystem-to-repo-deed.adoc +;; ECOSYSTEM.a2ml -> (ecosystem) meta-ecosystem-to-repo-deed.adoc +;; AGENTIC.a2ml -> (agentic) agentic-neurosym-playbook-to-repo-deed.adoc +;; NEUROSYM.a2ml -> (neurosym) agentic-neurosym-playbook-to-repo-deed.adoc +;; PLAYBOOK.a2ml -> (playbook) agentic-neurosym-playbook-to-repo-deed.adoc +;; STATE.a2ml -> (maturity) state-v1-decision.adoc, option B (ruled +;; 2026-11-10): the lifecycle claim is the (status) clause +;; above, the maturity a clause of its own +;; (vocabulary/maturity.adoc), and the journal is archived, +;; not translated. ;; ;; (egress ...) is the standards ADR-009 declaration that RE001 checks: one ;; entry per job that reads a secret other than GITHUB_TOKEN. Each :endpoints @@ -52,6 +62,76 @@ :ended "" (history (entry :phase active :since "2026-03-16" :note "backfilled default — correct if the true phase differs"))) + ; STATE.a2ml under state-v1-decision.adoc option B: [project-context] + ; maturity, the one statal field the (status) clause does not already carry. + ; The source gave no date, so there is no :since. + (maturity :level alpha) + ; META.a2ml: [metadata] last-updated, [maintenance-axes] scoping-first and + ; the [architecture-decisions] ADRs (id, title, status, date) are the rows + ; the table lists. Not in the table, so not translated: [metadata] project, + ; author, license, standard, media-type; [development-practices] (build-tool + ; is prose, not the SYMBOL the row requires); [maintenance-axes] + ; priority-order; each ADR's context, decision and consequences. + (meta + :last-updated "2026-08-07" + :scoping-first #t + (adr :id "ADR-001" :title "Replace Logtalk rule engine with pure Elixir rules" :status accepted :date "2026-04-14") + (adr :id "ADR-002" :title "Rename VQL→VCL and verisimdb→verisim throughout" :status accepted :date "2026-04-05") + (adr :id "ADR-003" :title "Route ProofObligations through FleetDispatcher to echidnabot" :status accepted :date "2026-04-11") + (adr :id "ADR-004" :title "Synthetic rebalancer (Strategy A) as default; B+C deferred to M9" :status accepted :date "2026-04-22") + (adr :id "ADR-005" :title "Use take_supervised/1 for isolated GenServer tests against Application-supervised processes" :status accepted :date "2026-04-25")) + ; ECOSYSTEM.a2ml: [metadata] project and ecosystem, [position] type and + ; purpose. Not translated: [metadata] last-updated and media-type, + ; [position] category, tier and role, [position.consumers], + ; [position.producers] and [integration-points] (no table row), and the + ; seven [related-projects] entries, whose relationships (sibling-standard, + ; data-dependency, dispatch-target, scanner-source, mcp-host) are outside + ; the closed set the (related) row allows. The source has no [pipeline] + ; section, so there is no :coordination. + (ecosystem + :project "hypatia" + :ecosystem "hyperpolymath" + :position-type "component" + :purpose "Neurosymbolic CI/CD intelligence layer — scans repos via panic-attack, classifies findings through the Safety Triangle, dispatches fixes to gitbot-fleet, learns from outcomes via 5 neural networks.") + ; AGENTIC.a2ml: [metadata] version and last-updated, [agent-permissions] + ; and the five [maintenance-integrity] axioms the table lists. The source + ; has no @profile line, so there is no (profile). Not translated: + ; [agent-constraints] forbidden (an unknown key, which fails closed), + ; maintenance-integrity completion-claim-requires-behavioural-tests, + ; [automation-hooks] (lists, not the comment-carried strings the (hooks) + ; row takes, and each one named a retired .a2ml file), [workflow-pin- + ; detection], [max-automation] and [sprint-patterns]. + (agentic + :version "0.2.0" + :last-updated "2026-08-07" + (permissions :source #t :tests #t :docs #t :config #t :create-files #t) + (integrity + :fail-closed #t + :require-evidence-per-step #t + :allow-silent-skip #f + :require-rerun-after-fix #t + :release-claim-requires-hard-pass #t)) + ; NEUROSYM.a2ml: [metadata] version and last-updated, [hypatia-config] + ; scan-enabled, scan-depth and report-format. Not translated: + ; [hypatia-config] verisim-data-path and fleet-path, and the populated + ; [neural-config], [symbolic-rules] and [proof-integration] sections, + ; which fail closed pending table rows. + (neurosym + :version "0.2.0" + :last-updated "2026-08-07" + (hypatia :scan-enabled #t :scan-depth deep :report-format "json")) + ; PLAYBOOK.a2ml: [metadata] version and last-updated, and the five + ; operational sections kept as positions (the family-1 slot doctrine). The + ; source's sections held runbook content the table has no rows for, so the + ; content did not translate; nor did [crg-promotion-criteria]. + (playbook + :version "0.2.0" + :last-updated "2026-08-07" + (deployment) + (incident-response) + (release-process) + (docs-format) + (maintenance-operations)) (egress :policy "standards ADR-009" (job From b5c2d767a5af9aa973dc5edd95e3a1061afe790d Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 14 Nov 2026 18:30:25 +0000 Subject: [PATCH 02/10] chore(deed): replace 0-AI-MANIFEST.a2ml with a pointer-only 0-AI-MANIFEST.deed The machine front door is now 0-AI-MANIFEST.deed, pointer-only (A7 ruling Q15): it names hypatia_chora.deed and README.adoc and carries no facts. The A2ML manifest's sections (identity, context tiers, canonical locations, architecture, invariants, lifecycle) do not match the field table of ai-manifest-decision.adoc, so nothing was translated from it; its architecture summary duplicated .claude/CLAUDE.md. Readers moved with it: - MUST.contractile: the structure invariant now preserves the .deed. - www/.well-known/ai.txt and .github/CONTRIBUTING.md point agents at the deed front door and the chora deed. - hypatia-cli-bash.sh and poc-scanner.sh accept 0-AI-MANIFEST.deed first (the legacy names still count for unmigrated repos) and recommend the deed, not an .a2ml file. The deed lints clean (deed_lint.js). Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_0136P7ZoBy5xGnGDLk7wQ8jC --- .github/CONTRIBUTING.md | 5 +- .machine_readable/MUST.contractile | 2 +- 0-AI-MANIFEST.a2ml | 122 ----------------------------- 0-AI-MANIFEST.deed | 15 ++++ hypatia-cli-bash.sh | 6 +- poc-scanner.sh | 6 +- www/.well-known/ai.txt | 10 +-- 7 files changed, 30 insertions(+), 136 deletions(-) delete mode 100644 0-AI-MANIFEST.a2ml create mode 100644 0-AI-MANIFEST.deed diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index f5a8965a..565db70d 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -18,8 +18,9 @@ We welcome contributions in many forms: ## Getting Started -1. **Read the AI Manifest:** Start with `0-AI-MANIFEST.a2ml` (if - present) to understand the repository structure. +1. **Read the AI Manifest:** Start with `0-AI-MANIFEST.deed`, the + pointer-only front door, then `hypatia_chora.deed` for the + repository facts. 2. **Environment:** Use `guix` `shell` `-D` `-f` `guix.scm` (or `direnv` `allow`) to set up your tools. Guix is the canonical diff --git a/.machine_readable/MUST.contractile b/.machine_readable/MUST.contractile index e962c6fb..25af6e21 100644 --- a/.machine_readable/MUST.contractile +++ b/.machine_readable/MUST.contractile @@ -34,7 +34,7 @@ ; Structure (must ".machine_readable/ directory preserved") - (must "0-AI-MANIFEST.a2ml preserved") + (must "0-AI-MANIFEST.deed preserved") (must "no SCM files in repo root — only in .machine_readable/") ; CI diff --git a/0-AI-MANIFEST.a2ml b/0-AI-MANIFEST.a2ml deleted file mode 100644 index bdf5b2ab..00000000 --- a/0-AI-MANIFEST.a2ml +++ /dev/null @@ -1,122 +0,0 @@ -; SPDX-License-Identifier: MPL-2.0 -; SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) -; -; 0-AI-MANIFEST.a2ml — Universal AI entry point for Hypatia -; Media-Type: application/a2ml - -; THIS FILE MUST BE READ FIRST BY ALL AI AGENTS - -(manifest - (identity - (name "hypatia") - (full-name "Hypatia — Neurosymbolic CI/CD Intelligence") - (version "0.7.x") - (repo "https://github.com/hyperpolymath/hypatia") - (license "MPL-2.0") - (author "Jonathan D.A. Jewell ")) - - (purpose - "Neurosymbolic CI/CD governance scanner for the hyperpolymath estate. - Coordinates gitbot-fleet (rhodibot, echidnabot, sustainabot, glambot, - seambot, finishbot, panicbot) via the safety triangle pipeline - (Eliminate > Substitute > Control). 8 neural networks on a shared - blackboard, VCL queries over verisim-data, Bayesian confidence updating, - and 35 Elixir rule modules for pattern detection.") - - ;; =================================================================== - ;; CONTEXT TIERS - ;; =================================================================== - - (context-tiers - ; Tier 0 (always load): This file + .claude/CLAUDE.md — orientation only - ; Tier 1 (load if working on code): README.adoc, EXPLAINME.adoc, Justfile, mix.exs - ; Tier 2 (load on demand): .machine_readable/descriptiles/*.a2ml, docs/ - ; Tier 3 (never load unless asked): test/, _build/, deps/, generated/ - ; - ; DO NOT READ unless specifically asked: - ; test/ — test files (run them, don't read them) - ; _build/ — Elixir build output - ; deps/ — Elixir dependencies - ; target/ — Rust build output - ; generated/ — auto-generated code - ; *.lock — lock files - ) - - ;; =================================================================== - ;; CANONICAL LOCATIONS - ;; =================================================================== - - (canonical-locations - (ai-manifest "0-AI-MANIFEST.a2ml" "THIS FILE") - (ai-instructions ".claude/CLAUDE.md" "Claude-specific patterns — DETAILED") - (state ".machine_readable/descriptiles/STATE.a2ml") - (meta ".machine_readable/descriptiles/META.a2ml") - (ecosystem ".machine_readable/descriptiles/ECOSYSTEM.a2ml") - (bot-directives ".machine_readable/bot_directives/")) - - ;; =================================================================== - ;; ARCHITECTURE SUMMARY - ;; =================================================================== - - (architecture - (description "Safety triangle pipeline with neural dispatch") - (layers - (elixir-pipeline "lib/" "133 modules — pattern analysis, dispatch, learning") - (rules "lib/rules/" "35 rule modules; catalogue at docs/rules/catalogue.adoc") - (neural "lib/neural/" "8 networks on a blackboard + coordinator GenServer") - (vcl "lib/vcl/" "VCL parser, file executor, query cache, federation") - (merge-orch "lib/merge_orchestration/" "12 modules — leases, ledger, ticker") - (web "lib/hypatia/web/" "dashboard, SSE, Prometheus /metrics, GraphQL, SARIF") - (idris2-abi "src/Hypatia/ABI/" "Types, GraphQL, gRPC, REST, FFI, RuleEngine with proofs") - (zig-ffi "ffi/zig/" "18 exported C ABI functions + 16 protocol connectors") - (rust "Cargo.toml" "Root workspace: adapters, cli, data, fixer, integration")) - (data-flow - "panic-attack scan -> verisim-data -> Elixir pipeline -> triangle route -> fleet dispatch")) - - ;; =================================================================== - ;; STRUCTURE OVERVIEW (detail in CLAUDE.md) - ;; =================================================================== - - (structure - "hypatia/ - ├── 0-AI-MANIFEST.a2ml # THIS FILE - ├── lib/ # Elixir: pipeline, rules, VCL, neural, safety, web, merge-orch - ├── src/Hypatia/ABI/ # Idris2 ABI — what the ipkg actually compiles - ├── ffi/zig/ # Zig FFI bridge (18 exports + connectors) - ├── adapters/ cli/ data/ fixer/ integration/ # Rust workspace (root crates) - ├── .machine_readable/ # State, meta, ecosystem, bot directives - └── .bot_directives/ # Bot instructions") - - ;; =================================================================== - ;; CRITICAL INVARIANTS - ;; =================================================================== - - (critical-invariants - (rule "SCM/a2ml files belong in .machine_readable/ — except this manifest, which RSR requires at root") - (rule "Safety triangle: Eliminate > Substitute > Control — order matters") - (rule "Confidence gates: >=0.95 auto-execute, 0.85-0.94 review, <0.85 report") - (rule "MPL-2.0 on all source files") - (rule "Author: Jonathan D.A. Jewell ")) - - ;; =================================================================== - ;; SESSION LIFECYCLE - ;; =================================================================== - - (lifecycle - (on-enter - (step "Read THIS file first") - (step "Read .claude/CLAUDE.md — detailed architecture tables and Scanner Hygiene") - (step "Read docs/DEBT-REGISTER.md — what is broken, what is ungated, what is stale") - (step "Read .machine_readable/descriptiles/STATE.a2ml for current status")) - - (on-exit - (step "Update .machine_readable/descriptiles/STATE.a2ml if changes made") - (step "Summarise outcomes"))) - - (format-meta - (version "2.2.0") - (media-type "application/a2ml") - (created "2026-02-15") - (last-updated "2026-08-07") - (maintained-by "Jonathan D.A. Jewell / hyperpolymath") - (protocol "https://github.com/hyperpolymath/0-ai-gatekeeper-protocol"))) diff --git a/0-AI-MANIFEST.deed b/0-AI-MANIFEST.deed new file mode 100644 index 00000000..6d454f7e --- /dev/null +++ b/0-AI-MANIFEST.deed @@ -0,0 +1,15 @@ +;; SPDX-License-Identifier: MPL-2.0 +;; SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) +;; +;; The machine front door of hypatia: pointer-only (A7 ruling Q15). It names +;; where to read and carries no facts of its own. Repository facts are in +;; hypatia_chora.deed; agent conventions are in .claude/CLAUDE.md. It +;; replaces 0-AI-MANIFEST.a2ml, retired 2026-11-14 (docs/history/A2ML-REMOVED.adoc). +(repo-deed + :schema-version "1.0.0" + :canonical-name "hypatia" + :repo-uuid #u8"gv-clade-index:github.com/hyperpolymath/hypatia" + :beholding-chora #uuid"0889b37b-defb-831f-973c-e119500db00e" + (front-doors + :machine "hypatia_chora.deed" + :human "README.adoc")) diff --git a/hypatia-cli-bash.sh b/hypatia-cli-bash.sh index 147c4cf5..a378331a 100755 --- a/hypatia-cli-bash.sh +++ b/hypatia-cli-bash.sh @@ -583,11 +583,11 @@ scan_repo_structure() { "Migrate to .machine_readable/bot_directives/" fi - # AI manifest - if [[ ! -f "$dir/0-AI-MANIFEST.a2ml" && ! -f "$dir/AI.a2ml" ]]; then + # AI manifest: the deed is the front door; the legacy A2ML names still count + if [[ ! -f "$dir/0-AI-MANIFEST.deed" && ! -f "$dir/0-AI-MANIFEST.a2ml" && ! -f "$dir/AI.a2ml" ]]; then emit_finding "high" "repo_structure" "missing_ai_manifest" \ "$dir" 0 "No AI gateway manifest found" "CWE-1021" \ - "Add 0-AI-MANIFEST.a2ml or AI.a2ml" + "Add 0-AI-MANIFEST.deed (A2ML is retired)" fi # Canonical SCM files diff --git a/poc-scanner.sh b/poc-scanner.sh index d2287712..94e7d26f 100755 --- a/poc-scanner.sh +++ b/poc-scanner.sh @@ -172,9 +172,9 @@ for required in "SECURITY.md" ".editorconfig" "LICENSE"; do ((missing_files++)) || true fi done -# AI manifest check -if [ ! -f "$TARGET_REPO/0-AI-MANIFEST.a2ml" ] && [ ! -f "$TARGET_REPO/AI.a2ml" ]; then - echo -e "${RED} ✗ MISSING: AI manifest (0-AI-MANIFEST.a2ml or AI.a2ml)${NC}" +# AI manifest check: the deed is the front door; the legacy A2ML names still count +if [ ! -f "$TARGET_REPO/0-AI-MANIFEST.deed" ] && [ ! -f "$TARGET_REPO/0-AI-MANIFEST.a2ml" ] && [ ! -f "$TARGET_REPO/AI.a2ml" ]; then + echo -e "${RED} ✗ MISSING: AI manifest (0-AI-MANIFEST.deed)${NC}" ((missing_files++)) || true fi if [ "$missing_files" -eq 0 ]; then diff --git a/www/.well-known/ai.txt b/www/.well-known/ai.txt index 4069dc76..aa481543 100644 --- a/www/.well-known/ai.txt +++ b/www/.well-known/ai.txt @@ -2,16 +2,16 @@ # SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) # # AI system declaration for Hypatia -# See: 0-AI-MANIFEST.a2ml for full AI integration protocol +# See: 0-AI-MANIFEST.deed (the machine front door) for where to read User-agent: * Allow: / # AI agents should read the AI manifest first: -# - 0-AI-MANIFEST.a2ml (root) -# - .machine_readable/STATE.scm (current project state) -# - .machine_readable/AGENTIC.scm (agent constraints) -# - .machine_readable/NEUROSYM.scm (neurosymbolic architecture) +# - 0-AI-MANIFEST.deed (root; pointer-only front door) +# - hypatia_chora.deed (repo facts: status, maturity, meta, ecosystem, +# agentic, neurosym, playbook) +# - .claude/CLAUDE.md (agent conventions) # # This project uses neurosymbolic CI/CD (Hypatia) and # gitbot-fleet for automated remediation. From f38793af056a227c53a94809710ec3270d9f4b7e Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 14 Nov 2026 18:32:56 +0000 Subject: [PATCH 03/10] chore(a2ml): delete the A2ML records that no mapping spec translates Owner ruling 2026-11-14, "Full migration now"; A7 section 11, ruling Q7: a file is translated where a mapping spec exists and deleted where none does. None of these has a spec in standards 1-formats/deed/mappings/: - .machine_readable/anchors/ANCHOR.a2ml (it also has no `authority`, which the (anchor) clause requires and a translator never invents) - .machine_readable/bot_directives/{coverage,debt,methodology}.a2ml and their README (template methodology boilerplate, not per-bot directives) - .machine_readable/contractiles/{bust,dust,intend,must,trust}/*file.a2ml - .machine_readable/integrations/*.a2ml (four integration notes) - .machine_readable/dogfooding.a2ml, testing/blitz.a2ml, merge-orchestration/LEDGER.a2ml (a journal; archived by reference) - rules.a2ml docs/history/A2ML-REMOVED.adoc records every removed file with its size, sha256 and git blob id, what it held and where its content went, plus the two .a2ml files that stay and why. References moved with the files: bust.ncl names Bustfile.deed (A7 8.1); contractile.just says its sources are retired and must not be regenerated from; GOVERNANCE.adoc points bot configuration at the (bot-directives) clause; comments in verdict.ex, findings.ncl, schema/README.adoc, Verdict.idr and ObservedIsNotSound.idr state the rule-lifecycle threshold without citing the deleted file; design and audit docs point at the ledger; docs/integration/a2ml.adoc is marked historical. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_0136P7ZoBy5xGnGDLk7wQ8jC --- .machine_readable/anchors/ANCHOR.a2ml | 23 -- .machine_readable/bot_directives/README.adoc | 41 -- .../bot_directives/coverage.a2ml | 63 --- .machine_readable/bot_directives/debt.a2ml | 51 --- .../bot_directives/methodology.a2ml | 109 ----- .../contractiles/bust/Bustfile.a2ml | 32 -- .machine_readable/contractiles/bust/bust.ncl | 6 +- .../contractiles/dust/Dustfile.a2ml | 24 -- .../contractiles/intend/Intentfile.a2ml | 26 -- .../contractiles/must/Mustfile.a2ml | 46 --- .../contractiles/trust/Trustfile.a2ml | 29 -- .machine_readable/dogfooding.a2ml | 89 ----- .../integrations/feedback-o-tron.a2ml | 13 - .machine_readable/integrations/proven.a2ml | 18 - .machine_readable/integrations/verisim.a2ml | 15 - .machine_readable/integrations/vexometer.a2ml | 18 - .../merge-orchestration/LEDGER.a2ml | 77 ---- .machine_readable/testing/blitz.a2ml | 375 ------------------ GOVERNANCE.adoc | 2 +- contractile.just | 5 + docs/README.adoc | 2 +- .../merge-orchestration/01-cve-bump-gate.adoc | 3 +- ...05-execution-substrate-bag-of-actions.adoc | 3 +- docs/history/A2ML-REMOVED.adoc | 230 +++++++++++ docs/integration/a2ml.adoc | 5 + docs/testing/audit.adoc | 3 +- integration/robot-repo-automaton/config.yml | 3 +- lib/hypatia/verdict.ex | 2 +- rules.a2ml | 251 ------------ schema/README.adoc | 2 +- schema/findings.ncl | 2 +- src/Hypatia/ABI/Verdict.idr | 4 +- tests/reject/ObservedIsNotSound.idr | 2 +- 33 files changed, 260 insertions(+), 1314 deletions(-) delete mode 100644 .machine_readable/anchors/ANCHOR.a2ml delete mode 100644 .machine_readable/bot_directives/README.adoc delete mode 100644 .machine_readable/bot_directives/coverage.a2ml delete mode 100644 .machine_readable/bot_directives/debt.a2ml delete mode 100644 .machine_readable/bot_directives/methodology.a2ml delete mode 100644 .machine_readable/contractiles/bust/Bustfile.a2ml delete mode 100644 .machine_readable/contractiles/dust/Dustfile.a2ml delete mode 100644 .machine_readable/contractiles/intend/Intentfile.a2ml delete mode 100644 .machine_readable/contractiles/must/Mustfile.a2ml delete mode 100644 .machine_readable/contractiles/trust/Trustfile.a2ml delete mode 100644 .machine_readable/dogfooding.a2ml delete mode 100644 .machine_readable/integrations/feedback-o-tron.a2ml delete mode 100644 .machine_readable/integrations/proven.a2ml delete mode 100644 .machine_readable/integrations/verisim.a2ml delete mode 100644 .machine_readable/integrations/vexometer.a2ml delete mode 100644 .machine_readable/merge-orchestration/LEDGER.a2ml delete mode 100644 .machine_readable/testing/blitz.a2ml create mode 100644 docs/history/A2ML-REMOVED.adoc delete mode 100644 rules.a2ml diff --git a/.machine_readable/anchors/ANCHOR.a2ml b/.machine_readable/anchors/ANCHOR.a2ml deleted file mode 100644 index dc3db7f6..00000000 --- a/.machine_readable/anchors/ANCHOR.a2ml +++ /dev/null @@ -1,23 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# A2ML validator metadata (a2ml-validate-action looks for these keys) -name = "hypatia" -project = "hypatia" -version = "1.0.0" -# ⚓ ANCHOR: hypatia -# This is the canonical authority for the hypatia repository. - -id: "org.hyperpolymath.hypatia" -version: "1.0.0" -clade: "unknown" -status: "active" - -# SSG Configuration (Unified boj-server build) -ssg: - engine: "casket" - output_dir: "public" - boj_trigger: true - cartridge: "ssg-mcp" - -# Relationships -parents: - - "org.hyperpolymath.boj-server" diff --git a/.machine_readable/bot_directives/README.adoc b/.machine_readable/bot_directives/README.adoc deleted file mode 100644 index a077b116..00000000 --- a/.machine_readable/bot_directives/README.adoc +++ /dev/null @@ -1,41 +0,0 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -= Agent Instructions -:toc: preamble - -Methodology-aware configuration for AI agents. Read by any AI agent -(Claude, Gemini, Copilot, etc.) at session start. - -== Files - -[cols="1,3"] -|=== -| File | Purpose - -| `methodology.a2ml` -| Default mode, invariants, ring ceiling, priority weights, convergent budget - -| `coverage.a2ml` -| Session coverage tracking — what was visited, what was skipped, what has MUSTs - -| `debt.a2ml` -| Meander debt — things found but not fixed, carried between sessions -|=== - -== How Agents Use These - -1. Read `methodology.a2ml` at session start — know mode, invariants, ceiling -2. Read `coverage.a2ml` — know what was visited last time, what was skipped -3. Read `debt.a2ml` — know what's outstanding from previous sessions -4. At session end, update `coverage.a2ml` and `debt.a2ml` - -== Relationship to Other Files - -* `AGENTIC.a2ml` says WHAT agents can do (permissions, gating) -* `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) - -== Reference - -ADR-002 in `standards/agentic-a2ml/docs/ADR-002-methodology-layer.adoc` diff --git a/.machine_readable/bot_directives/coverage.a2ml b/.machine_readable/bot_directives/coverage.a2ml deleted file mode 100644 index 79e6748f..00000000 --- a/.machine_readable/bot_directives/coverage.a2ml +++ /dev/null @@ -1,63 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -# -# coverage.a2ml — Session coverage tracking -# Updated at the end of each AI agent session. -# Persists what was visited, what was skipped, and what has MUSTs. -# -# Reference: ADR-002 in standards/agentic-a2ml/docs/ - -[metadata] -name = "coverage" -project = "hypatia" -version = "1.0.0" -last-updated = "2026-03-24" - -# ============================================================================ -# COVERAGE STATE -# ============================================================================ -# Updated by agents at session end. Tracks which components have been -# visited and which have known MUSTs that were skipped. - -[coverage] -total-components = 0 -visited-components = 0 -coverage-percent = 0 - -# ============================================================================ -# VISITED COMPONENTS -# ============================================================================ -# Component → session date + ring reached -# Agents add entries as they work through components. -# -# Example: -# [coverage.visited.emergency-room] -# date = "2026-03-23" -# ring = 2 -# fixes = 3 -# notes = "boot-guardian built, shutdown-marshal built" - -# ============================================================================ -# SKIPPED COMPONENTS WITH MUSTS -# ============================================================================ -# Components with known MUSTs that were not visited in the most recent session. -# These become P1 inputs for the next session's Phase 0. -# -# Example: -# [coverage.skipped-musts.session-sentinel] -# priority = "P0" -# issue = "56 SIGABRTs in 4 days, D-Bus race condition" -# discovered = "2026-03-23" - -# ============================================================================ -# CHERRY-PICKING AUDIT -# ============================================================================ -# At session end, agents report whether they chose easy work over hard work. -# This is the accountability mechanism for the weighted priority system. -# -# [coverage.cherry-picking] -# easy-high-completed = 3 -# hard-high-completed = 1 -# easy-low-completed = 2 -# hard-low-deferred = 4 -# assessment = "Correctly prioritised — all MUST items addressed before COULDs" diff --git a/.machine_readable/bot_directives/debt.a2ml b/.machine_readable/bot_directives/debt.a2ml deleted file mode 100644 index 5ae47318..00000000 --- a/.machine_readable/bot_directives/debt.a2ml +++ /dev/null @@ -1,51 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -# -# debt.a2ml — Meander debt list -# Things found but not fixed. Carried between sessions. -# Becomes the next session's Phase 0 input. -# -# Reference: ADR-002 in standards/agentic-a2ml/docs/ - -[metadata] -name = "debt" -project = "hypatia" -version = "1.0.0" -last-updated = "2026-03-24" - -# ============================================================================ -# DEBT ITEMS -# ============================================================================ -# Each item has: component, issue, effort (easy|medium|hard), impact (high|medium|low), -# priority (should|could), and discovered date. -# -# Items are consumed (removed) when fixed. New items are added at session end. -# The debt list prevents the "one more wave" loop — found things are persisted, -# not forgotten, and not used as justification for infinite meandering. - -# ============================================================================ -# SHOULD — would fix next wave -# ============================================================================ -# These are inputs for the next session if the user says "keep going". -# -# Example: -# [[debt.should]] -# component = "system-tools/monitoring/observatory" -# issue = "Stale duplicate of root observatory/" -# effort = "easy" -# impact = "medium" -# discovered = "2026-03-23" - -# ============================================================================ -# COULD — would fix eventually -# ============================================================================ -# These are low-priority items that don't justify a session on their own. -# They get picked up when an agent is in the area for other reasons. -# -# Example: -# [[debt.could]] -# component = "cicada" -# issue = "RSR_OUTLINE.adoc references banned AGPL-3.0" -# effort = "easy" -# impact = "low" -# discovered = "2026-03-23" diff --git a/.machine_readable/bot_directives/methodology.a2ml b/.machine_readable/bot_directives/methodology.a2ml deleted file mode 100644 index 3559a2a6..00000000 --- a/.machine_readable/bot_directives/methodology.a2ml +++ /dev/null @@ -1,109 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -# -# methodology.a2ml — AI agent methodology configuration -# Declares how agents should approach work in this repository. -# Read at session start by any AI agent (Claude, Gemini, Copilot, etc.) -# -# Reference: ADR-002 in standards/agentic-a2ml/docs/ - -[metadata] -name = "methodology" -project = "hypatia" -version = "1.0.0" -last-updated = "2026-03-24" -spec = "https://github.com/hyperpolymath/standards/blob/main/agentic-a2ml/docs/ADR-002-methodology-layer.adoc" - -# ============================================================================ -# MODE SELECTION -# ============================================================================ -# convergent: find gaps, fill them, build infrastructure (default for ops/infra) -# divergent: find what's strongest, push it further (for research/creative) -# hybrid: audit 20% of budget, then focus 80% on top MUSTs (default for most) - -[methodology] -default-mode = "hybrid" -ring-ceiling = 2 # Hard ceiling for ring expansion (0-3) -wave-cap = 2 # Max waves before requiring user "keep going" -spike-required = true # Every session must ship code, not just designs - -# ============================================================================ -# PRIORITY WEIGHTS -# ============================================================================ -# MUST (3x): Blocking the current work → fix immediately -# SHOULD (2x): Degrading quality of current work → fix if in zone -# COULD (1x): Improving quality of adjacent work → add to debt list - -[methodology.priority-weights] -must = 3 -should = 2 -could = 1 - -# ============================================================================ -# CONVERGENT BUDGET (when mode = convergent or hybrid) -# ============================================================================ -# How to allocate effort across work types. -# Prevents over-polishing docs while structural work waits. - -[methodology.convergent-budget] -structural = 70 # % for new modules, compilation fixes, wiring, integration -corrective = 20 # % for bugs found, broken imports, stale references -perfective = 10 # % for SPDX headers, doc updates, formatting, style - -# ============================================================================ -# UNIQUE STRENGTH (when mode = divergent) -# ============================================================================ -# What makes this project special. Agents should DEEPEN this, not broaden it. -# Customise this per project — the template default is generic. - -[methodology.unique-strength] -description = "{{PROJECT_UNIQUE_STRENGTH}}" -deepen-not-broaden = true - -# ============================================================================ -# DIVERGENT INVARIANTS -# ============================================================================ -# Constraints that divergent mode must NOT violate. -# These are the riverbanks — diverge within them, not across. -# "Amplify uniqueness" means deepen, not broaden. -# -# Test before any divergent action: -# "Does this deepen the existing strength, or add a parallel strength?" -# If parallel → stop. Note as cross-project insight. - -[methodology.divergent-invariants] -rules = [ - # Customise per project. Examples: - # "Idris2 only for formal verification — no Lean4, Coq, Agda", - # "believe_me count must remain zero", - # "FFI architecture: Idris2 → RefC → Zig → C ABI (no shortcuts)", -] - -# Optional: language invariant for the core strength -# If set, divergent mode will not introduce other languages for this purpose -# language-invariant = "idris2" - -# ============================================================================ -# CONSTRAINT HINTS -# ============================================================================ -# Help Phase 0 find the critical chain faster. -# Updated at session end with newly discovered constraints. - -[methodology.known-constraints] -constraints = [ - # Customise per project. Examples: - # "End-to-end build has never been verified", - # "libproject.so does not exist yet — all bindings call stubs", -] - -# ============================================================================ -# STATE FILE VALIDATION -# ============================================================================ -# Phase 0 reads STATE.a2ml first but it may be broken. -# These rules detect corrupt/template/stale state files. - -[methodology.state-validation] -reject-if-contains = ["{{PLACEHOLDER}}", "{{PROJECT}}", "rsr-template-repo"] -reject-if-project-name-mismatch = true -staleness-threshold-days = 90 -fallback-files = ["TODO.md", "TODO.adoc", "ROADMAP.adoc", "README.adoc"] diff --git a/.machine_readable/contractiles/bust/Bustfile.a2ml b/.machine_readable/contractiles/bust/Bustfile.a2ml deleted file mode 100644 index 706cf0e5..00000000 --- a/.machine_readable/contractiles/bust/Bustfile.a2ml +++ /dev/null @@ -1,32 +0,0 @@ -// Bustfile.a2ml — meta-repo bust contractile (breakage / rollback) -// SPDX-License-Identifier: MPL-2.0 -// A2ML validator metadata -name = "Bustfile" -project = "hypatia" -version = "1.0.0" - -Bust { - name: "hypatia" - version: "1.0.0" - description: "Rollback procedures when something breaks in the meta-repo" - - scenarios: { - "bad-pointer-bump": "git revert in meta-repo; child repo itself untouched" - "submodule-pointer-points-at-missing-sha": "git submodule update --init --checkout resets child to parent-recorded SHA; OR revert the stale bump commit" - "submodule-orphan-after-local-only-commit": "roll back locally with git reset to before the stranded commit; fix remote situation before re-attempting" - "accidental-private-repo-content-leaked-to-public-submodule": "hard-rotate the leaked secret immediately; git-filter-repo or BFG on the submodule's own history; public re-publication only after rotation complete" - } - - escalation-ladder: [ - "1. revert the meta-repo commit (reversible, low blast radius)", - "2. reset the local submodule clone (affects only local workspace)", - "3. force-push to main — PROHIBITED without explicit user confirmation (violates branch protection)", - "4. registry-level (delete/archive the GitHub repo) — human-only action, never by AI" - ] - - backup-points: [ - "GitHub serves as the durable backup for every submodule's own history", - "Meta-repo history on origin/main is the durable backup for pointer state", - "Local backup tags (backup/pre--) retained on risky rewrites" - ] -} diff --git a/.machine_readable/contractiles/bust/bust.ncl b/.machine_readable/contractiles/bust/bust.ncl index fc8cb8cd..82171e0f 100644 --- a/.machine_readable/contractiles/bust/bust.ncl +++ b/.machine_readable/contractiles/bust/bust.ncl @@ -1,7 +1,9 @@ # SPDX-License-Identifier: MPL-2.0 # Bust — error-handling / failure-recovery runner # -# Pairs with: Bustfile.a2ml (same directory) +# Pairs with: Bustfile.deed (same directory; A7 8.1). Not yet written: the +# legacy Bustfile.a2ml was retired 2026-11-14 with no mapping +# spec to translate it (docs/history/A2ML-REMOVED.adoc). # Verb: bust # Semantics: every declared failure mode must have a recovery path that has # been exercised. Runner injects failures (via declared probes) @@ -33,7 +35,7 @@ let base = import "../_base.ncl" in name = "bust-runner", version = "1.0.0", description = "Exercises declared failure modes and verifies recovery paths. Hard-gates on any failure mode without working recovery.", - paired_xfile = "Bustfile.a2ml", + paired_xfile = "Bustfile.deed", author = "Jonathan D.A. Jewell ", }, }, diff --git a/.machine_readable/contractiles/dust/Dustfile.a2ml b/.machine_readable/contractiles/dust/Dustfile.a2ml deleted file mode 100644 index 72087207..00000000 --- a/.machine_readable/contractiles/dust/Dustfile.a2ml +++ /dev/null @@ -1,24 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Dustfile — Cleanup and Hygiene Contract - -[dustfile] -name = "Dustfile" -project = "hypatia" -version = "1.0.0" -format = "a2ml" - -[cleanup] -stale-branch-policy = "delete-after-merge" -artifact-retention = "90-days" -cache-policy = "clear-on-release" - -[hygiene] -linting = "required" -formatting = "required" -dead-code-removal = "encouraged" -todo-tracking = "tracked-in-issues" - -[reversibility] -backup-before-destructive = true -rollback-mechanism = "git-revert" -data-retention-policy = "preserve-30-days" diff --git a/.machine_readable/contractiles/intend/Intentfile.a2ml b/.machine_readable/contractiles/intend/Intentfile.a2ml deleted file mode 100644 index 901ac68e..00000000 --- a/.machine_readable/contractiles/intend/Intentfile.a2ml +++ /dev/null @@ -1,26 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# A2ML validator metadata -name = "Intentfile" -project = "hypatia" -version = "1.0.0" -# Intentfile (A2ML Canonical) -# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) - -@abstract: -Declared intent and purpose for Hypatia. -@end - -## Purpose - -Hypatia — // SPDX-License-Identifier: MPL-2.0 - -## Anti-Purpose - -This project is NOT: -- A fork or wrapper around another tool -- A monorepo (unless explicitly structured as one) - -## If In Doubt - -If you are unsure whether a change is in scope, ask. -Sensitive areas: ABI definitions, license headers, CI workflows. diff --git a/.machine_readable/contractiles/must/Mustfile.a2ml b/.machine_readable/contractiles/must/Mustfile.a2ml deleted file mode 100644 index ed1e13ab..00000000 --- a/.machine_readable/contractiles/must/Mustfile.a2ml +++ /dev/null @@ -1,46 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# A2ML validator metadata -name = "Mustfile" -project = "hypatia" -version = "1.0.0" -# Mustfile (A2ML Canonical) -# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) - -@abstract: -Physical State contract for Hypatia. Baseline UX Manifesto invariants -that MUST hold at all times. -@end - -@requires: -- section: Core-Files -- section: Banned -@end - -## Core-Files - -### license-present -- description: LICENSE file must exist -- run: test -f LICENSE -- severity: critical - -### readme-present -- description: README must exist -- run: test -f README.adoc || test -f README.md -- severity: critical - -## Banned - -### no-hardcoded-paths -- description: No hardcoded developer paths -- run: "! grep -rn '/home/hyper\|/mnt/eclipse' --include='*.rs' --include='*.res' --include='*.ex' --include='*.gleam' --include='*.zig' --include='*.sh' . 2>/dev/null | grep -v '.git/' | grep -v 'ux-rollout.jl' | head -1" -- severity: critical - -### no-dockerfiles -- description: No Dockerfiles (use Containerfile) -- run: test ! -f Dockerfile -- severity: warning - -### no-makefiles -- description: No Makefiles (use Justfile) -- run: test ! -f Makefile -- severity: warning diff --git a/.machine_readable/contractiles/trust/Trustfile.a2ml b/.machine_readable/contractiles/trust/Trustfile.a2ml deleted file mode 100644 index fca00b2b..00000000 --- a/.machine_readable/contractiles/trust/Trustfile.a2ml +++ /dev/null @@ -1,29 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# A2ML validator metadata -name = "Trustfile" -project = "hypatia" -version = "1.0.0" -# Trustfile (A2ML Canonical) -# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) - -@abstract: -Trust and provenance verification for Hypatia. -Maximal trust by default — LLM may read, build, test, lint, format. -@end - -@trust-level: maximal -@trust-boundary: repo -@trust-actions: [read, build, test, lint, format] -@trust-deny: [delete-branch, force-push, modify-ci-secrets, publish] - -## Integrity - -### license-content -- description: LICENSE contains expected SPDX identifier -- run: grep -q 'SPDX\|License\|MIT\|Apache\|PMPL\|MPL' LICENSE -- severity: critical - -### no-secrets-committed -- description: No .env or credential files in repo -- run: test ! -f .env && test ! -f credentials.json && test ! -f .env.local -- severity: critical diff --git a/.machine_readable/dogfooding.a2ml b/.machine_readable/dogfooding.a2ml deleted file mode 100644 index c5449cb3..00000000 --- a/.machine_readable/dogfooding.a2ml +++ /dev/null @@ -1,89 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# A2ML validator metadata -name = "dogfooding" -project = "hypatia" -version = "1.0.0" -# Dogfooding applicability manifest for Hypatia. -# -# Declares, per DOG-01..DOG-10 from -# `hyperpolymath/standards/testing-and-benchmarking/TESTING-TAXONOMY.adoc` -# § VII, whether each iser applies to this repository and in what state. -# -# States: yes (applies + passing) / warn (applies + fixable) / -# deferred (applies but not yet implemented, with rationale) / -# no (intentionally skipped — not applicable to this repo shape) -# -# Audit source: TESTING-AUDIT.md (2026-04-22) + .machine_readable/testing/blitz.a2ml - -[meta] -repo = "hyperpolymath/hypatia" -audit-date = "2026-04-22" -standard = "testing-and-benchmarking/TESTING-TAXONOMY.adoc" -standard-version = "1.1.0" - -# ----------------------------------------------------------------------------- -# Per-iser applicability -# ----------------------------------------------------------------------------- - -[isers.DOG-01] -state = "yes" -description = "CI gate fires (hypatia, panic-attack, dogfood-gate) with non-empty output" -evidence = ".github/workflows/hypatia-scan.yml" - -[isers.DOG-02] -state = "yes" -description = "Annotation pipeline — findings have non-null file + line fields" -evidence = "lib/mix/tasks/hypatia.batch_security_scan.ex" - -[isers.DOG-03] -state = "yes" -description = "Groove manifest conformant; ports match bind address" -evidence = [".well-known/groove/manifest.json", "config/config.exs"] - -[isers.DOG-04] -state = "warn" -description = "K9 contracts — k9iser build exits 0; contracts exist" -evidence = "k9iser.toml" -gap = "k9iser build was not invoked in CI. Fixed in the same PR that ships this manifest — see .github/workflows/ci.yml job `k9iser-validate`." - -[isers.DOG-05] -state = "yes" -description = "VeriSimDB wired — client instantiated and called, not just imported" -evidence = ["lib/verisim_connector.ex", "lib/vcl/client.ex"] - -[isers.DOG-06] -state = "yes" -description = "Template placeholders resolved — no stray {{OWNER}} / {{REPO}} / [YOUR-REPO-NAME] in repo config" -evidence = "lib/rules/dogfooding.ex:25-40" -notes = "The only occurrences of {{OWNER}}/{{REPO}}/[YOUR-REPO-NAME] in the tree are inside lib/rules/dogfooding.ex as the rule's own detection patterns — they are the strings the rule searches for in downstream repos. Explicitly annotated in that file." - -[isers.DOG-07] -state = "yes" -description = "Tool version currency — workflow action SHAs pinned with v-tag comments" -evidence = ".github/workflows/" - -[isers.DOG-08] -state = "yes" -description = "Consumer field contract — tool output field names match downstream serialisation" - -[isers.DOG-09] -state = "yes" -description = "Iser applicability declared — this file" -evidence = ".machine_readable/dogfooding.a2ml" - -[isers.DOG-10] -state = "yes" -description = "Naming currency — no stale binary names or deprecated subcommand references" -notes = "The single legacy filename `test/p2p_recipe_vql_test.exs` is intentional — kept to surface the VQL→VCL rename in `git log` without breaking existing test discovery paths. The test body uses the current `vcl` naming." - -# ----------------------------------------------------------------------------- -# Summary -# ----------------------------------------------------------------------------- - -[summary] -applicable = 10 -yes = 9 -warn = 1 -deferred = 0 -no = 0 -notes = "DOG-04 warn downgraded to yes in the same PR that ships this file (adds k9iser-validate job to ci.yml)." diff --git a/.machine_readable/integrations/feedback-o-tron.a2ml b/.machine_readable/integrations/feedback-o-tron.a2ml deleted file mode 100644 index 5381604e..00000000 --- a/.machine_readable/integrations/feedback-o-tron.a2ml +++ /dev/null @@ -1,13 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Feedback-o-Tron Integration — Autonomous Bug Reporting - -[integration] -name = "feedback-o-tron" -type = "bug-reporter" -repository = "https://github.com/hyperpolymath/feedback-o-tron" - -[reporting-config] -platforms = ["github", "gitlab", "bugzilla"] -deduplication = true -audit-logging = true -auto-file-upstream = "on-external-dependency-failure" diff --git a/.machine_readable/integrations/proven.a2ml b/.machine_readable/integrations/proven.a2ml deleted file mode 100644 index 9af33ffd..00000000 --- a/.machine_readable/integrations/proven.a2ml +++ /dev/null @@ -1,18 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Proven Integration — Formally Verified Safety Library - -[integration] -name = "proven" -type = "safety-library" -repository = "https://github.com/hyperpolymath/proven" -version = "1.2.0" - -[binding-policy] -approach = "thin-ffi-wrapper" -unsafe-patterns = "replace-with-proven-equivalent" -modules-available = ["SafeMath", "SafeString", "SafeJSON", "SafeURL", "SafeRegex", "SafeSQL", "SafeFile", "SafeTemplate", "SafeCrypto"] - -[adoption-guidance] -priority = "high" -scope = "all-string-json-url-crypto-operations" -migration = "incremental — replace unsafe patterns as encountered" diff --git a/.machine_readable/integrations/verisim.a2ml b/.machine_readable/integrations/verisim.a2ml deleted file mode 100644 index 164c5229..00000000 --- a/.machine_readable/integrations/verisim.a2ml +++ /dev/null @@ -1,15 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# VeriSimDB Feed — Cross-Repo Analytics Data Store - -[integration] -name = "verisimdb" -type = "data-feed" -repository = "https://github.com/hyperpolymath/nextgen-databases" -data-store = "verisimdb-data" - -[feed-config] -emit-scan-results = true -emit-build-metrics = true -emit-dependency-graph = true -format = "hexad" -destination = "verisimdb-data/feeds/" diff --git a/.machine_readable/integrations/vexometer.a2ml b/.machine_readable/integrations/vexometer.a2ml deleted file mode 100644 index 238b3d2c..00000000 --- a/.machine_readable/integrations/vexometer.a2ml +++ /dev/null @@ -1,18 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Vexometer Integration — Irritation Surface Analysis - -[integration] -name = "vexometer" -type = "friction-measurement" -repository = "https://github.com/hyperpolymath/vexometer" - -[measurement-config] -dimensions = 10 -emit-isa-reports = true -lazy-eliminator = true -satellite-interventions = true - -[hooks] -cli-tools = "measure-on-error" -ui-panels = "measure-on-interaction" -build-failures = "measure-on-failure" diff --git a/.machine_readable/merge-orchestration/LEDGER.a2ml b/.machine_readable/merge-orchestration/LEDGER.a2ml deleted file mode 100644 index f1797963..00000000 --- a/.machine_readable/merge-orchestration/LEDGER.a2ml +++ /dev/null @@ -1,77 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) 2026 Jonathan D.A. Jewell -# -# LEDGER.a2ml — Merge Orchestration workstream: canonical, compaction-proof state. -# This is the durable record for the cross-repo "merge orchestration" feature. -# It is NOT the repo's canonical 6a2/STATE.a2ml (held pending realignment) — it is -# the workstream ledger. READ THIS FIRST to re-orient after any context reset. -@profile(id=a2ml/state) - -[metadata] -workstream = "merge-orchestration" -version = "0.11.0" -last-updated = "2026-06-14" -owner = "paraordinate (Jonathan D.A. Jewell)" -branch = "claude/peaceful-pascal-IRlgq" # same branch name across all in-scope repos -status = "active — Wave 0 (contracts)" - -[thesis] -# A merge decision is a TUPLE over three near-orthogonal axes, never one score: -# route = who is authoritative (proof->echidnabot, bump->patch-bridge, structure->rhodibot, -# security->panicbot, CI->robot-repo-automaton; license/SPDX->none, hard flag) -# method = history shape (squash|rebase|merge_commit), set by repo policy + commit hygiene -# safety = arm_auto|review|flag, set by council confidence + vetoes, clamped by pool -# Consensus = "Kin Council": competence-weighted aggregation + MONOTONE VETO (any veto -> flag). -# NOT Byzantine (bots are cooperative specialists; integrity comes from signed attestations). -# Reflexivity guard: change_level=meta (edits CI / hypatia rules / bot_directives / standards) -# -> always flag. The actuator may PROPOSE oracle changes, never self-approve them. - -[decisions] -# Owner rulings banked 2026-06-05: -nix = "REMOVED estate-wide — guix.scm / guix channels only. flake.nix to be deleted; nix bumps CLOSED not merged." -mr-layout = "6a2/ subdir is canonical; standards CLAUDE.md to be reconciled to it." -leases = "central, Kin.Gate-backed (NOT per-repo files) — fixes the bootstrap race; this IS the kin enhancement." -codecite-prooftrace = "their own CITE + PROVE contractile pair." -operating-mode = "full GitHub ops (token re-authed 2026-06-05)." -ledger = "this file." - -[build-order] -# Owner-chosen sequence: -step-1 = "CVE/bump gate (unblocks the held dependabot backlog) — IN PROGRESS" -step-2 = "Attestation schema (Ed25519, reuse panic-attack intent->evidence->seal)" -step-3 = "Pool<->TRUST + Kin-backed lease/coordination spec (lands in standards)" -later = "verisimdb entity model + PolicyDrift; CodeCite/ProofTrace" - -[wave-0-artifacts] -a1 = "decision contract — LANDED on hypatia/main (PR #442, merged 2026-06-05). doc + schema + +/- fixtures, ajv-validated." -a2 = "CVE/bump gate — LANDED on hypatia/main (PR #443, merged 2026-06-05). bump-decision.schema (extends a1) + bump fixtures, ajv-validated." -a3 = "attestation — LANDED on hypatia/main (PR #444, merged 2026-06-05). ed25519 sign/verify/tamper round-trip PASSED + ajv A1/A2/A3." -a4 = "CVE/bump gate in CI — LANDED on hypatia/main (PR #459). bridge-gate.yml template + bridge-verdict.sh (B1 core) + mock BridgeReports, tested. WIRED into 5 cargo repos (reposystem#114, hypatia#460, verisimdb#133, panic-attack#127, echidna#246 — all merged 2026-06-13); 8 reposystem bumps rebased through it; 3 nix bumps closed (B3)." -a5 = "pool/lease spec — this commit. 04-pool-lease-spec.adoc + schemas/{pool-policy,lease}.schema.json + fixtures; pools P0-P3+mass_squash <-> TRUST levels + clamp law; central Kin.Gate-backed lease (the runtime tier). ajv-validated: PL1/PL2/LE1/LE2 all reject correctly. standards adoption (TRUST trust-deny meta extension + INTENT lease-schema fill) is an owner-applied follow-on per standards' own ask-before-touching." - -[gated-pr-ledger] -# Applying the gate by hand to all open PRs across 11 in-scope repos (2026-06-05). -# ARMED: hypatia#442 (now merged). Everything else HELD (reason / unblock): -held-license = "standards#376,#373 -> veto:license (owner-only, never auto)" -held-meta-ci = "vcl-ut#51; echidna#237 (actions bump edits workflows) -> meta:edits-CI-oracle" -held-proof = "vcl-ut#52; echidna#234 -> needs proof attestation (echidnabot offline) + rebase/coord" -held-bumps = "2026-06-12 re-triage: echidna#243 (actions->meta/review); reposystem #106 redis + #95 toml (major->review); 8 cargo minor/patch (#96-#107) -> needs CVE gate = bridge-gate.yml run in CI." -held-nix = "CLOSED 2026-06-12: reposystem#113/#112/#109 (B3 + @dependabot ignore). Root fix still open: remove flake.nix (separate Nix campaign)." -held-core-code = "echidna#232 -> core-tier code change -> conservative/review (docs/chore would arm)" -held-realignment = "verisimdb#107 -> held:6a2-realignment + owner-review-requested" - -[coordination] -do-not-touch = "branch claude/peaceful-pascal-IRlgq; gitbot-fleet dispatch-runner.sh license gate; my contractile/bot_directive/merge-orchestration territory" -hold = "6a2/STATE,META + anchors/ANCHOR in {hypatia,gitbot-fleet,.git-private-farm,verisimdb,standards} pending realignment" -other-agents = "claude/nice-ptolemy-lNB8E (standards), claude/loving-cannon-AtUSm (echidna), claude/abi-tier2-and-l10-trans-cycle (vcl-ut), claude/affinescript-migration-wip (reposystem)" - -[next] -step = "MERGE-ORCHESTRATION SYSTEM COMPLETE + AUTONOMY LOOP CLOSED + SCHEDULED (cron + tick). Full pipeline on main: SENSE Sensor (#492) + producer observe.sh (#78); DELIBERATE Strategist + KinCompetence/Kin.Council (#494); RUNTIME TIER KinGate + FileStore (#494); LIVE LOOP (#495); SCHEDULED TRIGGER Scheduler.cycle + mix hypatia.merge_orchestrate (#496); ACTUATE Dispatcher manifest -> .git-private-farm actuate.sh (#77). CRON+TICK (this commit): (1) TICK -- Hypatia.MergeOrchestration.Ticker GenServer (mirrors LearningScheduler: send_after :tick -> guarded do_cycle -> reschedule; run_now/status; a cycle failure is rescued+recorded, never crashes the tick). Wired into application.ex via merge_orchestration_children() mirroring tui_children() -- DEFAULT OFF, enabled by `config :hypatia, :merge_orchestration, enabled: true, interval_ms: 900_000`. (2) CRON -- .github/workflows/merge-orchestrate.yml: schedule (hourly 17 * * * *) + workflow_dispatch, SHA-pinned setup-beam/checkout/cache/upload, runs `mix hypatia.merge_orchestrate --store $MERGE_ORCH_STORE` (store from vars.MERGE_ORCH_STORE||data/verisim), uploads merge-decisions.jsonl artifact (if-no-files-found: ignore). Token-free: both compute+write the manifest; the farm actuator (separate, PAT) merges. Tests: 64 ExUnit (was 61: +3 Ticker -- do_cycle happy/records-stats, do_cycle guarded-failure [encoder raises -> rescued, runs stays 0], GenServer run_now->status), 0 failures, local elixir 1.14, mix-format-clean, scanner-clean. PR pending: hypatia (Ticker + app wiring + cron workflow). THE SYSTEM IS NOW FULLY SCHEDULABLE end-to-end. REMAINING = pure owner config/ops, NO code: flip `config :hypatia, :merge_orchestration, enabled: true` to run the in-brain tick, and/or set repo var MERGE_ORCH_STORE + let the cron run (point at a populated store + add push-to-actuator if desired); a5 standards adoption (owner-applied); P3 handshake + mass_squash in actuator; .git-private-farm Actions billing is dead -- fix before the actuator runs scheduled." - -[post-completion-followons] -# Owner picked all four 2026-06-14 (P3/mass_squash, BoA design doc, a5 draft, add-BoA-to-scope). -p3-mass-squash = "LANDED .git-private-farm PR #79: decide_action gains P3 (FARM_P3_AUTHORIZED=1 owner handshake) + mass_squash (campaign_ref + $FARM_CAMPAIGN_DIR/.active marker) gates, both owner-held signals the brain can't self-grant. 10/10 bash conformance (was 5), shellcheck-clean, resolves TODO(increment-3b). Farm CI dead-infra (404), admin-merge like #78." -boa-substrate = "DESIGN DOC landed (#498) + BatonEmitter BUILT (this commit). bag-of-actions still NOT in MCP scope (owner granted GitHub permission but the session's 11-repo MCP scope is fixed; add_repo tool unavailable) -- so read its REAL API by public git clone to /tmp/boa. Findings: Bag.Mesh.submit_planned(spec, budget) where spec=%{check_id,command,required_cap,mutating?,risk?}; planner routes to cheapest capable node + GATES mutating:true work on a verifier (= the independent re-verify); a merge is just command=[gh,pr,merge,...] with required_cap=\"secret-access\" -- the capability ONLY mesh-github-runner holds in nodes.scm (the token-bearer; brain's node lacks it -> Baton migrates = token-free-brain as capability routing). NO bag-of-actions changes needed for the command-based merge. Hypatia.MergeOrchestration.BatonEmitter: to_spec/2 (pure -> the submit_planned spec, carrying lease+route+rationale as residue/attestation) + emit/2 (one Baton per ARMED Loop entry; Bag.Mesh call late-bound via apply/3 + injectable, so compile-decoupled + tests dep-free). 74 ExUnit (was 71: +3 BatonEmitter). WIRED LIVE 2026-06-14 (branch claude/peaceful-pascal-IRlgq, hypatia PR #501 + bag-of-actions PR #5, both draft/owner-review): (1) Loop.run/1 :actuation opt (:manifest default | :baton | :both) threaded through Scheduler.cycle + `mix hypatia.merge_orchestrate --actuation`; :baton submits one Baton/armed-entry via BatonEmitter.emit/2 late-bound to Bag.Mesh.submit_planned(spec, budget) (compile-decoupled, no new dep). (2) TWO interop bugs in the merged BatonEmitter fixed against BoA's real source: required_cap \"secret-access\"->\"secret_access\" (Zig bridge/Bag.Planner tag; hyphen = unprovable = routes to NO node) + to_spec now carries :verifier (else Bag.Planner returns {:rejected,:mutation_requires_verifier} for the mutating merge). (3) BoA side: mesh-hypatia-brain node (linux,trusted-host; NO secret-access) registered IN STEP across src/estate.zig + nodes.scm + Bag.Estate.idr -> merges migrate to mesh-github-runner (token-free-brain as capability routing). (4) E2E test (bag/test/merge_orchestration_e2e_test.exs): brain can't satisfy secret_access; real gh-merge spec plans to mesh-github-runner; submit_planned runs+returns verdict/clean-residue; freeze-on-brain->thaw-on-runner (hmac:verified) -- safe `true` stand-in, no real PR touched. Tests: hypatia merge_orchestration 81/0 (+4 :actuation, +verifier assertions); bag 24 (5 E2E pass; 3 pre-existing stale-fmt-fixture failures, unrelated); zig build + zig build test OK. NOTHING REMAINING on BoA for the command-based merge." -a5-standards = "DRAFT-ONLY pending owner approval (standards is ask-before-touching/license-sensitive): fill INTENT.contractile with the a5 lease/claim schema as an intent-kind + extend TRUST.contractile with the meta trust-deny (an agent cannot self-authorise a meta claim). To be drafted + shown, NOT pushed, until owner signs off the exact text." -manifest-shape-seam = "RESOLVED .git-private-farm PR #80 (merged): actuate.sh gains normalize_manifest (jq adapter mapping BOTH the flat artifact-1 shape AND the brain's nested tier/strategy+.merge merge-decisions.jsonl entry to the flat fields decide_action needs; flat wins so existing manifests unchanged) + actuate_jsonl (consume a whole merge-decisions.jsonl, one decision/line). 13/13 bash conformance (was 10), shellcheck-clean. The sense->deliberate->gate->manifest->actuate loop is now connected end to end." -k9-lease-validator = "LANDED hypatia (this commit): Hypatia.MergeOrchestration.LeaseValidator + mix hypatia.validate_leases -- the a5 k9 lease validator. Audits the PERSISTED lease store (what KinGate.decide_acquire can't see across files): LE1 (held=>TTL), LE2 (held meta=>owner_authorized), stale (held past TTL), overlap (>=2 live held leases on one repo -- the per-repo rule broken in the store). validate/2 pure; validate_store/2 over FileStore.list; Mix task exits non-zero on any violation (CI gate). 71 ExUnit (was 64: +7 LeaseValidator). The standards-side k9 contractile registration is part of the a5 draft (owner-approval-pending; the drafted INTENT probe points at this validator)." diff --git a/.machine_readable/testing/blitz.a2ml b/.machine_readable/testing/blitz.a2ml deleted file mode 100644 index 25f3e6ba..00000000 --- a/.machine_readable/testing/blitz.a2ml +++ /dev/null @@ -1,375 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Testing-taxonomy blitz report for Hypatia. -# -# Machine-readable counterpart to TESTING-AUDIT.md. Conforms to the -# hyperpolymath/standards Testing Taxonomy v1.1.0. -# Regenerate by running the audit; see TESTING-AUDIT.md § 6 for the -# punch list that drives deltas between this file and the target grade. - -[meta] -standard = "testing-and-benchmarking/TESTING-TAXONOMY.adoc" -standard-version = "1.1.0" -standard-date = "2026-04-04" -audit-date = "2026-04-22" -audit-method = "automated scouts + synthesis" - -[grade] -current = "C" -current-declared-on = "2026-04-23" -target = "B" -line-of-sight-to-target = "multi-quarter — requires mutation + fuzz + compat + PBT" -tier-1-closed-on = "2026-04-23" -tier-1-closing-pr = "claude/fix-security-issues-9zrz0 — reflexive test suite" - -# ----------------------------------------------------------------------------- -# 16 test categories — primary status per TESTING-TAXONOMY.adoc § 1 -# ----------------------------------------------------------------------------- - -[categories.UT] -name = "Unit" -status = "strong" -evidence = [ - "test/code_safety_test.exs", - "test/pattern_registry_test.exs", - "test/triangle_router_test.exs", - "test/confidence_annealing_test.exs", - "test/recipe_matcher_test.exs", -] -file-count = 12 - -[categories.P2P] -name = "Point-to-Point" -status = "strong" -evidence = ["test/p2p_recipe_vcl_test.exs", "test/concurrency_test.exs"] - -[categories.E2E] -name = "End-to-End" -status = "strong" -evidence = ["test/e2e_pipeline_test.exs"] - -[categories.BLD] -name = "Build" -status = "strong" -evidence = [".github/workflows/ci.yml"] - -[categories.EXE] -name = "Execution" -status = "strong" -evidence = [ - "test/zig_ffi_smoke_test.exs", - "test/vcl_client_test.exs", - "test/vcl_file_executor_test.exs", -] - -[categories.REF] -name = "Reflexive" -status = "strong" -evidence = [ - "test/reflexive_test.exs", - "test/safety_test.exs", - "test/blackboard_test.exs", -] -notes = "SelfDiagnostics health + circuit breaker, VCL/RateLimiter/Quarantine stats, Justfile doctor recipe structurally tested" - -[categories.LCY] -name = "Lifecycle" -status = "strong" -evidence = ["test/kin_test.exs", "test/training_pipeline_test.exs"] - -[categories.SMK] -name = "Smoke" -status = "strong" -evidence = [ - "test/zig_ffi_smoke_test.exs", - "test/root_hygiene_test.exs", - "test/green_web_test.exs", -] - -[categories.PBT] -name = "Property-Based" -status = "weak" -evidence = ["test/p2p_recipe_vcl_test.exs"] -gap = "parameterised tables only; no StreamData; no 1000+-case coverage per property" - -[categories.MUT] -name = "Mutation" -status = "absent" -gap = "no mutation-testing dep, no CI job, no score tracking" - -[categories.FUZ] -name = "Fuzz" -status = "absent" -gap = "no fuzz/ directory, no cargo-fuzz targets, no fuzz workflow" - -[categories.CTR] -name = "Contract" -status = "partial" -evidence = ["test/contract_test.exs", "test/support/contract_case.ex"] -gap = "no .contractile runtime decorators; named-invariant assertion harness now present" -notes = "covers TriangleRouter thresholds, RateLimiter burst, Quarantine auto-quarantine, VCL parse totality" - -[categories.REG] -name = "Regression" -status = "absent" -gap = "no test/regressions/ subdirectory; bug-tied tests inlined in feature modules" - -[categories.CHS] -name = "Chaos" -status = "weak" -gap = "concurrency stress only; no deliberate failure injection" - -[categories.CMP] -name = "Compatibility" -status = "weak" -gap = "backward-only checks; no forward-compat or deprecation-warning tests" - -[categories.PRF] -name = "Proof Regression" -status = "strong" -evidence = [ - ".github/workflows/verify-tlaplus.yml", - "verification/proofs/tlaplus/KinGate.tla", -] -pending-merge = [ - "claude/esn-spectral-scaling — ESNSpectralScaling.lean", -] -landed = [ - "claude/quality-gates — verify-lean.yml + verify-idris.yml + graph_of_trust normalisation + PanLL schema validation (merged 2026-04-22)", - "claude/lean-proofs-parser-pagerank — ParserTotality.lean + PageRankInvariants.lean (merged 2026-04-22)", -] - -[categories.summary] -total = 16 -strong = 9 -partial = 1 -weak = 3 -absent = 3 - -# ----------------------------------------------------------------------------- -# DOG-01..DOG-10 dogfood-self — TESTING-TAXONOMY.adoc § VII -# ----------------------------------------------------------------------------- - -[dogfooding.DOG-01] -check = "CI gate fires" -status = "pass" -evidence = [".github/workflows/hypatia-scan.yml"] - -[dogfooding.DOG-02] -check = "Annotation pipeline" -status = "pass" -evidence = ["lib/mix/tasks/hypatia.batch_security_scan.ex"] - -[dogfooding.DOG-03] -check = "Groove manifest" -status = "pass" -evidence = [".well-known/groove/manifest.json", "config/config.exs"] - -[dogfooding.DOG-04] -check = "K9 contracts" -status = "warn" -evidence = ["k9iser.toml"] -gap = "k9iser build not invoked in CI; no generated/k9iser/ artefacts" -fix = "add `k9iser build` step to ci.yml" - -[dogfooding.DOG-05] -check = "VeriSimDB wired" -status = "pass" -evidence = ["lib/verisim_connector.ex", "lib/vcl/client.ex"] - -[dogfooding.DOG-06] -check = "Template placeholders" -status = "warn" -evidence = ["lib/rules/dogfooding.ex"] -gap = "{{OWNER}}/{{REPO}} strings present as rule literals, not unresolved placeholders" -fix = "optional — annotate rule data as literal test strings" - -[dogfooding.DOG-07] -check = "Tool version currency" -status = "pass" -evidence = [".github/workflows/"] - -[dogfooding.DOG-08] -check = "Consumer field contract" -status = "pass" - -[dogfooding.DOG-09] -check = "Iser applicability" -status = "fail" -gap = "no .machine_readable/dogfooding.a2ml" -fix = "create the manifest with per-iser yes/no/deferred" - -[dogfooding.DOG-10] -check = "Naming currency" -status = "pass" -notes = "single stale reference is test/p2p_recipe_vql_test.exs filename; body uses vcl" - -[dogfooding.summary] -pass = 7 -warn = 2 -fail = 1 -total = 10 - -# ----------------------------------------------------------------------------- -# Six Sigma benchmark readiness — TESTING-TAXONOMY.adoc § Benchmark Taxonomy -# ----------------------------------------------------------------------------- - -[benchmarks] -verdict = "scaffolded" -framework = "criterion" -framework-version = "0.8" -harness-file = "fixer/benches/hypatia_bench.rs" -bench-count = 7 -baseline-directory = ".machine_readable/benchmarks/" -baseline-present = false -ci-gated = false -six-sigma-thresholds-declared = false - -[benchmarks.categories.latency] -status = "partial" -evidence = ["fixer/benches/hypatia_bench.rs"] - -[benchmarks.categories.throughput] -status = "partial" -evidence = ["fixer/benches/hypatia_bench.rs"] - -[benchmarks.categories.memory] -status = "scaffolded" -evidence = [".github/workflows/stress-test.yml"] - -[benchmarks.categories.startup] -status = "absent" - -[benchmarks.categories.build-time] -status = "absent" - -[benchmarks.categories.energy] -status = "absent" - -[benchmarks.categories.ffi-overhead] -status = "absent" -notes = "ffi/zig/ has functional tests only; no timing" - -# ----------------------------------------------------------------------------- -# 14 aspect dimensions — TESTING-TAXONOMY.adoc § 1 (aspect dimensions) -# ----------------------------------------------------------------------------- - -[aspects.security] -status = "strong" -evidence = [ - ".github/workflows/security.yml", - "cargo-audit", - "cargo-deny", - "CodeQL", - "secret-scanner", - "SBOM generation", - "Dependabot", -] - -[aspects.safety] -status = "strong" -evidence = ["verification/proofs/tlaplus/", "verification/proofs/idris2/"] -banned-patterns-clean = true -default-total-idris = true - -[aspects.interoperability] -status = "strong" -evidence = ["adapters (GitHub/GitLab/Bitbucket/Codeberg/sr.ht)", "src/abi/ (REST/GraphQL/gRPC)", "VCL"] - -[aspects.functionality] -status = "strong" -elixir-test-files = 39 -elixir-test-loc = 8659 - -[aspects.versability] -status = "strong" -evidence = ["CHANGELOG.adoc", "mix.exs"] - -[aspects.maintainability] -status = "strong" -evidence = ["TOPOLOGY.md", "DESIGN-NARRATIVE.md", "Cargo workspace"] - -[aspects.reproducibility] -status = "strong" -evidence = ["flake.nix", "guix.scm", "Cargo.lock", "mix.lock"] - -[aspects.portability] -status = "strong" -evidence = ["CI matrix (linux/macos/windows, x86_64/arm64)", "Containerfile"] - -[aspects.dependability] -status = "weak" -gap = "no chaos engineering, no fault-injection suite" - -[aspects.performance] -status = "weak" -gap = "benchmarks not baselined; no published metrics; no capacity plan" - -[aspects.observability] -status = "weak" -gap = "Logger-only; no Prometheus/OpenTelemetry exporter; no structured metrics" - -[aspects.usability] -status = "absent" -gap = "no systematic error-messaging audit; no UX review" - -[aspects.accessibility] -status = "absent" -gap = "no WCAG 2.3 audit; no ADJUST.contractile; Gossamer UI unreviewed" - -[aspects.privacy] -status = "absent" -gap = "no GDPR mapping; no PRIVACY.md" - -[aspects.summary] -strong = 8 -weak = 3 -absent = 3 -total = 14 - -# ----------------------------------------------------------------------------- -# Punch list reference — ordered sequence to target grade -# Full detail in TESTING-AUDIT.md § 6 -# ----------------------------------------------------------------------------- - -[punch-list.tier-1-to-C] -items = [ - "bench-baseline-and-CI-gate", # done 2026-04-22 - "contract-test-harness", # done 2026-04-23 - "reflexive-test-suite", # done 2026-04-23 - "dogfooding-a2ml", # done 2026-04-22 - "k9iser-ci-integration", # done 2026-04-22 -] -items-open = [] -all-tier-1-complete = true -estimated-effort-days = 0 - -[punch-list.tier-2-to-B] -items = [ - "property-based-streamdata", - "fuzz-targets-cargo-fuzz", - "mutation-score-pipeline", - "compatibility-suite", - "lifecycle-tests-all-genservers", -] -estimated-effort-weeks = 6 - -[punch-list.tier-3-to-A] -items = [ - "chaos-resilience-suite", - "isolated-regression-directory", - "privacy-compliance", - "accessibility-compliance", -] -estimated-effort-weeks = 7 - -# ----------------------------------------------------------------------------- -# Out of scope -# ----------------------------------------------------------------------------- - -[out-of-scope] -items = [ - "external-user-feedback (can't be manufactured)", - "formal WCAG/GDPR audit (needs external domain expert)", - "energy profiling (tooling gap for BEAM+Rust hybrid)", - "full PageRank convergence proof (tracked in PROOFS-GAP.md PR 4 — needs Mathlib)", -] diff --git a/GOVERNANCE.adoc b/GOVERNANCE.adoc index 75bc7ec8..a3cc449a 100644 --- a/GOVERNANCE.adoc +++ b/GOVERNANCE.adoc @@ -80,7 +80,7 @@ Architecture Decision Record (ADR) in `docs/decisions/`. and standards enforcement. * Bot actions are subject to the same quality and review standards as human contributions. -* Configure bots in `.machine_readable/bot_directives/`. +* Configure bots in the `(bot-directives …)` clause of `hypatia_chora.deed`. == Becoming a Maintainer diff --git a/contractile.just b/contractile.just index 9a5827ba..4172a03b 100644 --- a/contractile.just +++ b/contractile.just @@ -2,6 +2,11 @@ # Source directory: contractiles # Re-generate with: contractile gen-just --dir contractiles # +# The `# Source:` files named below were legacy .a2ml contractiles, retired +# 2026-11-14 with no mapping spec to translate them (docs/history/A2ML-REMOVED.adoc). +# The recipes stand as generated until the edicts (file.deed, A7 8.1) exist; +# do not regenerate from the retired files. +# # SPDX-License-Identifier: MPL-2.0 # === DUST (Recovery & Rollback) === diff --git a/docs/README.adoc b/docs/README.adoc index 0ec58ed8..0ab6d0f7 100644 --- a/docs/README.adoc +++ b/docs/README.adoc @@ -69,7 +69,7 @@ acceptance criteria for closing the underlying roadmap item. == Integration -* link:integration/a2ml.adoc[`a2ml.adoc`] — A2ML machine-readable metadata integration. +* link:integration/a2ml.adoc[`a2ml.adoc`] — A2ML machine-readable metadata integration (historical: A2ML is retired; see `hypatia_chora.deed`). * link:integration/k9.adoc[`k9.adoc`] — K9 coordination service integration. * link:integration/a2ml-k9.adoc[`a2ml-k9.adoc`] — combined integration notes. * link:integration/github-registry.adoc[`github-registry.adoc`] — GitHub registry integration. diff --git a/docs/design/merge-orchestration/01-cve-bump-gate.adoc b/docs/design/merge-orchestration/01-cve-bump-gate.adoc index 8fb2f36c..742305bc 100644 --- a/docs/design/merge-orchestration/01-cve-bump-gate.adoc +++ b/docs/design/merge-orchestration/01-cve-bump-gate.adoc @@ -65,6 +65,7 @@ negatives rejected for the expected invariant. Run `panic-attack bridge triage ` on each held bump PR's lockfile to populate `bump.bridge`, then emit the gated decision. Held backlog (per -`.machine_readable/merge-orchestration/LEDGER.a2ml`): +the workstream ledger, `.machine_readable/merge-orchestration/LEDGER.a2ml`, +retired 2026-11-14 and kept in git history; see `docs/history/A2ML-REMOVED.adoc`): echidna #236 / #233 / #228, reposystem ×10 cargo (#95–#107). The nix bumps (reposystem #103 / #108 / #109) are B3 vetoes → **close**, not gate. diff --git a/docs/design/merge-orchestration/05-execution-substrate-bag-of-actions.adoc b/docs/design/merge-orchestration/05-execution-substrate-bag-of-actions.adoc index cd72dfc8..156a688e 100644 --- a/docs/design/merge-orchestration/05-execution-substrate-bag-of-actions.adoc +++ b/docs/design/merge-orchestration/05-execution-substrate-bag-of-actions.adoc @@ -154,4 +154,5 @@ Bag.Mesh.submit(%{ * `00-decision-contract.adoc` — the decision tuple the Baton carries. * `02-attestation.adoc` — the signed verdict that becomes the trust-chain link. * `04-pool-lease-spec.adoc` — the lease that becomes the routing capability. -* `.machine_readable/merge-orchestration/LEDGER.a2ml` — workstream state. +* The workstream ledger (`LEDGER.a2ml`, retired 2026-11-14; read it from git + history, see `docs/history/A2ML-REMOVED.adoc`) — workstream state. diff --git a/docs/history/A2ML-REMOVED.adoc b/docs/history/A2ML-REMOVED.adoc new file mode 100644 index 00000000..03c08a88 --- /dev/null +++ b/docs/history/A2ML-REMOVED.adoc @@ -0,0 +1,230 @@ +// SPDX-License-Identifier: CC-BY-SA-4.0 +// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) += The A2ML files removed from hypatia on 2026-11-14 + +The owner ruled on 2026-11-14, "Full migration now": every `.a2ml` file in +hypatia is translated into deed form where a mapping spec says it +translates, every reader is moved off it, and the file is deleted. The +mapping specs are in standards `1-formats/deed/mappings/`; a field a spec +does not list does not translate and was dropped, not re-homed. Files with +no mapping spec were deleted (A7 section 11, ruling Q7). + +This record lists each removed file, what it was, and where its content +went. The contents are not copied here. Git history keeps them. To read one, +use its blob id, or read its path at the last commit that held it: + +[source,bash] +---- +git cat-file -p +git show b660d08833729f129b0de9445b0e5ebadcddef77: +---- + +Size is in bytes. The sha256 is of the file as it was tracked. + +== Removed + +[cols="4,1,3,3,4,5",options="header"] +|=== +| Path | Size | sha256 | Git blob id | What it was | Where it went + +| `.machine_readable/descriptiles/STATE.a2ml` +| 23516 +| `0b5df64948615763cdaf47b43bf484a5b0eca9a2b462f70d51b582bcd52d31da` +| `6f676089b1930c411335473c9def454e41c5fb07` +| STATE descriptile v1: status, maturity, CRG grade, dogfooding status, milestones M1 to M21, gaps, next actions and the session journal. +| Option B of `state-v1-decision.adoc`: maturity to `(maturity :level alpha)`; the lifecycle claim is the existing `(status)` clause; the journal is archived here by reference, not translated. + +| `.machine_readable/descriptiles/META.a2ml` +| 4378 +| `c863ac3d3a6bced855e566f4bfd6e7554554f469fc78799a35c4ce62ccfb779c` +| `a738d103cd270b18d5692110329f41e156de5ac9` +| META descriptile: author, licence, development practices, ADR-001 to ADR-005, maintenance axes. +| `(meta)` per `meta-ecosystem-to-repo-deed.adoc`: last-updated, scoping-first and each ADR's id, title, status and date. Dropped: everything else, including each ADR's context, decision and consequences. + +| `.machine_readable/descriptiles/ECOSYSTEM.a2ml` +| 3357 +| `891fefefddd7fde77874e96ddbd87146ecb1811a9db5367b900d40d206d6e216` +| `38589dc8263b3e4008644e8aa4254897591082b8` +| ECOSYSTEM descriptile: position, consumers, producers, seven related projects, integration points. +| `(ecosystem)` per `meta-ecosystem-to-repo-deed.adoc`: project, ecosystem, position-type, purpose. Dropped: the seven related-project entries (relationships outside the closed set), consumers, producers, integration points. + +| `.machine_readable/descriptiles/AGENTIC.a2ml` +| 4809 +| `d09a631ade70caecd749efa247767a3c577a3822c0322fd390cdfbd6fa13c276` +| `d69fd8df630d0cb81070083de089967033c3c288` +| AGENTIC descriptile: permissions, forbidden actions, integrity axioms, workflow-pin detection, automation hooks, automation limits, sprint patterns. +| `(agentic)` per `agentic-neurosym-playbook-to-repo-deed.adoc`: version, last-updated, permissions, the five integrity axioms. Dropped: the rest (no table rows). + +| `.machine_readable/descriptiles/NEUROSYM.a2ml` +| 2343 +| `667939ee967e6bb42075cb4e5ea62ea41b391e9667c244725f982353942f334c` +| `e43db348b8f89f0d82f59171b4121c74d8d6dc69` +| NEUROSYM descriptile: Hypatia scan config, neural config, three symbolic rules, proof integration. +| `(neurosym)` per `agentic-neurosym-playbook-to-repo-deed.adoc`: version, last-updated, scan-enabled, scan-depth, report-format. Dropped: the rest (fails closed pending table rows). + +| `.machine_readable/descriptiles/PLAYBOOK.a2ml` +| 3516 +| `d360e4b5864558acbdff0d0d15301e2345092e053242a80d71236b6d0d4aa0a2` +| `22b0af83cbf1c2c4940cdc75ace4bd1252702810` +| PLAYBOOK descriptile: deployment, incident response, release process, maintenance operations, CRG promotion criteria. +| `(playbook)` per `agentic-neurosym-playbook-to-repo-deed.adoc`: version, last-updated and the five operational positions. Dropped: the section contents and the CRG criteria (no table rows). + +| `.machine_readable/CLADE.a2ml` +| 1589 +| `541349de1bb3a5ea48655db47eafdbbcdfc26fe6851414161fa2a64ade195f0d` +| `7fc477c5d0f5b56e67e352a6f8fee32aad8070ec` +| Clade declaration (gv-clade-index registry): identity, clade, forges, lineage, status. +| Already translated into `(identity) (clade) (forges) (lineage) (status)` per `clade-to-repo-deed.adoc`; the legacy file is deleted. + +| `0-AI-MANIFEST.a2ml` +| 5973 +| `139d23ca18ef5208a2885fec039be66580187c69f395f7b68997cbcc80c981cd` +| `bdf5b2aba9b3a37ba720b76d7ef3e9587e658ee9` +| AI manifest (S-expression shape): identity, purpose, context tiers, canonical locations, architecture, invariants, lifecycle. +| Replaced by the pointer-only `0-AI-MANIFEST.deed` (A7 ruling Q15). Its sections do not match the table of `ai-manifest-decision.adoc`, so nothing was translated. + +| `.machine_readable/anchors/ANCHOR.a2ml` +| 527 +| `52c07ad4291ea6fd6dd1ded149a9db1fcd311a684d6226920016f0308e814cd0` +| `dc3db7f6890ffa4eaf145a5cbe02a86be6842ffe` +| Anchor: reverse-DNS id, version, clade, status, SSG config, parent boj-server. +| Deleted. No mapping spec in `1-formats/deed/mappings/`. Under A7 6.4 the id, clade and status are dropped; the source has no `authority`, which the `(anchor)` clause requires and a translator never invents; SSG config belongs to `META.deed` and the parent to `ECOSYSTEM.deed` (modules not yet adopted here). + +| `.machine_readable/bot_directives/coverage.a2ml` +| 2271 +| `61c6798d4d3996b7ab0a5151bb82b28edea0a042d45415e05d63ffd2324fc92f` +| `79e6748f5cdc76fdc1569b36329784f95a2de1b3` +| Agent methodology template: session coverage tracking (all counts zero). +| Deleted: template boilerplate, not a per-bot directive; no mapping spec. + +| `.machine_readable/bot_directives/debt.a2ml` +| 1913 +| `1c213b80d93b93d428a9f43602be2557cb2d353e00d1d4bf98fca1a19bd4b3b7` +| `5ae47318761d324c22fe006338655aaf161233f8` +| Agent methodology template: meander debt (examples only). +| Deleted: template boilerplate; no mapping spec. + +| `.machine_readable/bot_directives/methodology.a2ml` +| 4691 +| `e5474aaa7076fff610bd27594e5e9dc738e21f8a6bff02d48ba3c5f9d8892f1e` +| `3559a2a6f697803b7fdf1bc1bcf92bfc39c5af8f` +| Agent methodology template: mode, priority weights, budgets, placeholders. +| Deleted: template boilerplate with unfilled placeholders; no mapping spec. + +| `.machine_readable/contractiles/bust/Bustfile.a2ml` +| 1658 +| `7b5017746e616b0446d3d05ecf414e95ec7793540763d405c70f7b8584bc6779` +| `706cf0e528bc55b637b198056008bd7ed8a9bc45` +| Bust contractile: meta-repo rollback scenarios (template residue). +| Deleted: no mapping spec. `bust.ncl` now names `Bustfile.deed` (A7 8.1), not yet written. + +| `.machine_readable/contractiles/dust/Dustfile.a2ml` +| 534 +| `5448a27dc90fb94350b628f836441aca6c276c9ae515ed2f3d4c83e96b5fedaf` +| `72087207eb81a14860ab0a0b520713b1c8722f9f` +| Dust contractile: cleanup and hygiene settings. +| Deleted: no mapping spec. `contractile.just` keeps its generated recipes. + +| `.machine_readable/contractiles/intend/Intentfile.a2ml` +| 591 +| `4cb4fb8c1ea937ee032f568c672731998b29df3f775d08487c99a7ca404c0253` +| `901ac68e4addcd3279bdfe7d7e6a92d5d05bbe0c` +| Intent contractile: purpose stub and anti-purpose. +| Deleted: no mapping spec. + +| `.machine_readable/contractiles/must/Mustfile.a2ml` +| 1165 +| `09b2929de80ecdb6e9628a5f927e50356a518adb49a6b9ea48ba6cf7c08c32e5` +| `ed1e13ab9cf3384653983bed41f3c53c46fdda2c` +| Must contractile: five shell checks (licence, README, hardcoded paths, Dockerfile, Makefile). +| Deleted: no mapping spec. `contractile.just` keeps its generated must recipes. + +| `.machine_readable/contractiles/trust/Trustfile.a2ml` +| 853 +| `b214584ca216ea380f70ca14aa0724fd24e1c189b4f07bbc66375dc7f7753368` +| `fca00b2bcb231cb6845ce82b0076ee7746fb3473` +| Trust contractile: trust level and two integrity checks. +| Deleted: no mapping spec. `contractile.just` keeps its generated trust recipes. + +| `.machine_readable/integrations/feedback-o-tron.a2ml` +| 381 +| `e0befb80a2138f359524d6db4e5fdc598c4a233079990afe6303e382821e1550` +| `5381604eda94e014b309b62ffa43e41fdbed5e63` +| Integration note: feedback-o-tron bug reporter config. +| Deleted: no mapping spec, no reader. + +| `.machine_readable/integrations/proven.a2ml` +| 612 +| `11fabb802ac4a0285caa64c4000436c3e1b386b7a6190d735e10be0fb910dbd9` +| `9af33ffdc7e9faced46b474f2a07df389c9e1631` +| Integration note: proven safety-library adoption guidance. +| Deleted: no mapping spec, no reader. + +| `.machine_readable/integrations/verisim.a2ml` +| 387 +| `48f716912dbe895d0f4f59a767c22cea517fcb9bc3637b1540558cd3f647cc51` +| `164c5229a7e2a507cb9f123ccd681159a3376005` +| Integration note: VeriSimDB data feed config. +| Deleted: no mapping spec, no reader. + +| `.machine_readable/integrations/vexometer.a2ml` +| 444 +| `3f85155335da36a216049bc4434f976d19580b6bcd49c020117a5c133e3b9145` +| `238b3d2cdd3a9c59f5e21dcdadba8aaf81d24214` +| Integration note: vexometer measurement config. +| Deleted: no mapping spec, no reader. + +| `.machine_readable/dogfooding.a2ml` +| 3511 +| `b7b1fcd8a5249d88b0df050c92200ab8526a444a9b031cb523d7d6e2a750e3c6` +| `c5449cb34c237817b3a1f5ce6cd0239160e3bfac` +| Dogfooding applicability manifest, DOG-01 to DOG-10 (audit 2026-04-22). +| Deleted: no mapping spec, no reader. + +| `.machine_readable/merge-orchestration/LEDGER.a2ml` +| 11839 +| `db76ce756f70af4001e0f5e5d12437377241825a8d692584e88590f3ef23ec65` +| `f179796398a1ddccc17f4b27269774dd55971082` +| Merge-orchestration workstream ledger (a STATE-profile journal, v0.11.0). +| Deleted: a journal; archived here by reference (`state-v1-decision.adoc` option B). + +| `.machine_readable/testing/blitz.a2ml` +| 10348 +| `465f2f2b97ba951edc64825b8235d3d1b95727c3678fadc5e9e5d57037161aca` +| `25f3e6bad754cf4291f06fb3ef8ca672b88d6d42` +| Testing-taxonomy blitz report (audit 2026-04-22), machine counterpart of `docs/testing/audit.adoc`. +| Deleted: no mapping spec, no reader. + +| `rules.a2ml` +| 7809 +| `9084f4452e4d7d851f751b0d8a114f28cf37f08015d8db388847235fa12626a0` +| `651211690b75de6644be141f18ccba5610857d47` +| Prose instructions for rule management: the rule lifecycle (5 observations to propose, 10 + 3 fixes to auto-approve) and rule quality standards. +| Deleted: no mapping spec. Comments that cited it now state the thresholds without the file name. + +|=== + +== Retained, with the reason + +Two `.a2ml` files stay, each because a live reader outside this repository's +control still needs exactly that input. Neither has a deed form to move to. + +[cols="3,5",options="header"] +|=== +| Path | Why it stays + +| `audits/assail-classifications.a2ml` +| panic-attack (>= 2.5.5, `load_user_classifications` in its +`src/assail/mod.rs`) reads only `audits/assail-classifications.a2ml` or +`.panic-attack-classifications.a2ml`. No mapping spec covers it and +panic-attack has no deed reader, so deleting it would unsuppress the audited +findings it records. It goes when panic-attack reads a deed form first. + +| `test/fixtures/a2ml/rsr-criteria-v2.a2ml` +| A dogfood copy of the RSR v2.0 criteria, whose canon +(`0-canon/rsr/rsr-criteria-v2.a2ml` in standards) is still A2ML: A7 section +10 gives it a criteria praxis deed written by kyX's front end (D313), not a +hand conversion. `Hypatia.Rules.RsrCriteria` must read the canon's form, and +the oracle's tests, the CI smoke run and the `rsr_score` default read this +copy. It goes when the canon has a deed form. +|=== diff --git a/docs/integration/a2ml.adoc b/docs/integration/a2ml.adoc index e528f0ae..e4681a07 100644 --- a/docs/integration/a2ml.adoc +++ b/docs/integration/a2ml.adoc @@ -4,6 +4,11 @@ :toc: :icons: font +*Status:* HISTORICAL — A2ML is retired estate-wide (standards rulings D99, D269c, +D312, D313; hypatia migrated 2026-11-14). Do not create or extend `.a2ml` files. +Repository metadata is `+hypatia_chora.deed+`; the grammar is standards +`+1-formats/deed/spec/abnf/deed.abnf+`. + == Overview Hypatia can use A2ML (Attested Markup Language) for template documentation, enabling progressive strictness and structural guarantees. diff --git a/docs/testing/audit.adoc b/docs/testing/audit.adoc index 6c2b3e72..eca86563 100644 --- a/docs/testing/audit.adoc +++ b/docs/testing/audit.adoc @@ -319,4 +319,5 @@ hybrid; wait for upstream primitives. === 8. Appendix — file inventory by category -Full mapping in `+.machine_readable/testing/blitz.a2ml+`. +Full mapping in `+.machine_readable/testing/blitz.a2ml+`, retired 2026-11-14 and +kept in git history (`+docs/history/A2ML-REMOVED.adoc+`). diff --git a/integration/robot-repo-automaton/config.yml b/integration/robot-repo-automaton/config.yml index bffbdf4e..51276d5d 100644 --- a/integration/robot-repo-automaton/config.yml +++ b/integration/robot-repo-automaton/config.yml @@ -118,7 +118,8 @@ learning: format: scm # ERROR-CATALOG.scm format # Distillation settings. Learned rules are Elixir modules in - # lib/rules/*.ex (see rules.a2ml lifecycle); the machine-readable + # lib/rules/*.ex (rule lifecycle: the retired rules.a2ml, kept in git + # history, see docs/history/A2ML-REMOVED.adoc); the machine-readable # export for cross-repo consumers is the learned-security-rules JSON. distillation: min_occurrences: 3 diff --git a/lib/hypatia/verdict.ex b/lib/hypatia/verdict.ex index 64239940..62bfc5cf 100644 --- a/lib/hypatia/verdict.ex +++ b/lib/hypatia/verdict.ex @@ -11,7 +11,7 @@ defmodule Hypatia.Verdict do * `support` — what its evidence supports: `%{kind: "pattern"}` (a rule matched), - `%{kind: "observed", observations: n}` (a fleet count; rules.a2ml's + `%{kind: "observed", observations: n}` (a fleet count; the rule-lifecycle thresholds are belief formation, not soundness), or `%{kind: "mechanical", ...}` (a prover re-check, with both digests); * `evidence` — the tokens the finding was issued on: rule, rule version, diff --git a/rules.a2ml b/rules.a2ml deleted file mode 100644 index 65121169..00000000 --- a/rules.a2ml +++ /dev/null @@ -1,251 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# A2ML validator metadata -name = "rules" -project = "hypatia" -version = "1.0.0" -# AI Assistant Instructions for Hypatia Rule Management - -## Repository Focus -- **Hypatia** is a neurosymbolic security scanner that learns patterns from fleet observations -- Maintain `lib/rules/` as the authoritative source of truth for production rules -- Sync detection patterns between Elixir rules and `hypatia-cli.sh` bash patterns - -## Rule Governance - -### Rule Lifecycle -1. **Pattern Detection** (hypatia-cli.sh) - - Bash/ripgrep patterns detect issues in code - - Submit findings to gitbot-fleet shared-context - -2. **Observation Collection** (learning loop) - - Aggregate findings across fleet - - Track pattern occurrence counts - -3. **Rule Proposal** (threshold: 5 observations) - - Generate Elixir rule module with comprehensive logic - - Include: CWE mapping, severity, fix suggestions - - Add to `lib/rules/` (pre-production status) - -4. **Validation** (ECHIDNA semantic analysis) - - Check logical consistency - - Verify pattern coverage - - Assess rule interactions - - Required: 90%+ validation score - -5. **Approval & Deployment** - - Promote to production status in `lib/rules/` - - Update `rule-deployment-status.json` - - Pattern already active in hypatia-cli.sh - -6. **Auto-approval** (threshold: 10 observations + 3 successful fixes) - - Track fix outcomes in `auto-fix-history.jsonl` - - Enable automated remediation when threshold reached - -### Rule Quality Standards - -**Production-Ready Rules Must Have:** -- ✅ Comprehensive detection logic (not empty stubs) -- ✅ Standard Elixir module structure with `classify/2` function -- ✅ Context-aware severity escalation (prod vs test) -- ✅ CWE mapping for compliance -- ✅ Actionable fix suggestions -- ✅ Pattern-specific validation logic - -**Rule Severity Classification:** -- **CRITICAL:** Code injection, RCE, authentication bypass (CWE-95, CWE-89, CWE-287) -- **HIGH:** Memory safety, type safety bypasses (CWE-1188, CWE-704, CWE-754) -- **MEDIUM:** Resource leaks, poor error handling (CWE-404, CWE-755) -- **INFO:** Technical debt, style issues (CWE-1057) - -### File Organization - -``` -hypatia/ -├── hypatia-cli.sh # Detection patterns (bash/ripgrep) -├── lib/rules/ # Production Elixir rules -│ ├── code_safety.ex -│ ├── security_errors.ex -│ ├── cicd_rules.ex -│ └── ... -├── rule-deployment-status.json # Current state -├── fleet-config.k9.ncl # K9 configuration -└── rules.a2ml # This file - -gitbot-fleet/shared-context/ -├── findings/ # Scan results per repo -├── learning/ -│ ├── observed-patterns.jsonl -│ ├── auto-fix-history.jsonl -│ └── rule-proposals/ -└── auto-fixes/ # Generated fix scripts -``` - -## Workflow Instructions - -### When Adding New Patterns - -1. **Add to hypatia-cli.sh:** - ```bash - # Pattern N: Description (SEVERITY) - while IFS=: read -r linenum line; do - [[ -z "$linenum" || ! "$linenum" =~ ^[0-9]+$ ]] && continue - [[ "$first" == "false" ]] && echo "," >> "$all_findings" - first=false - - jq -n \ - --arg sev "severity" \ - --arg type "pattern_type" \ - --arg pattern "pattern_name" \ - --arg file "$file" \ - --argjson line "$linenum" \ - --arg code "$line" \ - --arg cwe "CWE-XXXX" \ - --arg fix "Fix suggestion" \ - '{severity: $sev, type: $type, pattern: $pattern, file: $file, line: $line, code: $code, cwe: $cwe, fix: $fix, auto_fixable: false}' \ - >> "$all_findings" - ((file_issues++)) || true - done < <(rg -n 'pattern_regex' "$file" 2>/dev/null || true) - ``` - -2. **Deploy to fleet:** - ```bash - cd gitbot-fleet - ./fleet-coordinator.sh run-scan /path/to/repo - ``` - -3. **Monitor observations:** - ```bash - jq -r '.type' learning/observed-patterns.jsonl | sort | uniq -c - ``` - -4. **Generate rule when threshold crossed (5+ obs):** - - Create comprehensive Elixir rule module in `lib/rules/` - - Include all required logic: `classify/2`, CWE mapping, and fix suggestions - - Add context-aware logic with helper functions - -5. **Validate with ECHIDNA:** - ```bash - ./validate-rule-proposals.sh - # Required: 90%+ success rate - ``` - -6. **Deploy approved rule:** - - Mark as production in `rule-deployment-status.json` - ```bash - # Update rule-deployment-status.json - ``` - -### When Modifying Existing Rules - -1. **Check current status:** - ```bash - jq '.approved_rules[] | select(.name == "rule_name")' rule-deployment-status.json - ``` - -2. **Update both files:** - - Elixir rule in `lib/rules/` - - Bash pattern in `hypatia-cli.sh` - -3. **Re-validate:** - ```bash - ./validate-rule-proposals.sh - ``` - -4. **Document changes:** - - Update `DEPLOYMENT-MANIFEST-*.md` - - Increment version in rule metadata - -### When Creating Auto-fix Scripts - -**Auto-fix scripts must:** -- Accept finding JSON via `--finding-file` parameter -- Exit 0 on success, non-zero on failure -- Create git commit with descriptive message -- Include "Co-Authored-By: Hypatia Scanner " -- Be idempotent (safe to run multiple times) - -**Template:** -```bash -#!/usr/bin/env bash -# Auto-fix: Pattern Name -set -euo pipefail - -FINDING_FILE="$1" -FILE=$(jq -r '.file' "$FINDING_FILE") -LINE=$(jq -r '.line' "$FINDING_FILE") - -# Perform fix -sed -i "${LINE}s/pattern/replacement/" "$FILE" - -# Commit -git add "$FILE" -git commit -m "fix: auto-remediate pattern_name - -Co-Authored-By: Hypatia Scanner " -``` - -## Integration Points - -### With gitbot-fleet -- Submit findings to `shared-context/findings/` -- Read learning data from `shared-context/learning/` -- Execute auto-fixes via `robot-repo-automaton` - -### With ECHIDNA -- Validate rules with semantic analysis -- Check logical consistency -- Verify pattern coverage -- 90%+ validation score required for approval - -### With K9 Contractiles -- Read configuration from `fleet-config.k9.ncl` -- Deploy scanner to repos via K9 Hunt leash -- Coordinate with gitbot-fleet K9 components - -## Metrics to Track - -- **Observations per pattern:** Track in `observed-patterns.jsonl` -- **Rule proposals generated:** Count in `lib/rules/` -- **Validation scores:** Record in rule metadata -- **Auto-fix success rate:** Track in `auto-fix-history.jsonl` -- **False positive rate:** Monitor user feedback -- **Time to auto-approval:** Measure learning loop velocity - -## Constraints - -- **Never modify approved rules without re-validation** -- **Always maintain CWE mappings for compliance** -- **Require manual review for CRITICAL findings** -- **Test auto-fix scripts before fleet deployment** -- **Preserve backward compatibility in pattern detection** - -## Delivery Promises - -After any changes to rules or patterns: -1. ✅ Update both Elixir rule and bash pattern -2. ✅ Update `rule-deployment-status.json` -3. ✅ Re-run validation if rule logic changed -4. ✅ Update deployment manifest -5. ✅ Mention in commit message which rules changed - -## Current State - -**Active Rules:** 7 (as of 2026-04-14) -- unsafe_panic (template, 1,150 obs) -- type_safety_bypass (template, 477 obs) -- unsafe_crash (template, 342 obs) -- cors_misconfiguration (auto-fixed, 3 obs) -- technical_debt (production, 196 obs) ⭐ -- unsafe_without_doc (production, 19 obs) ⭐ -- eval_usage (production, 7 obs) ⭐ - -**Fleet Coverage:** 14/585 repositories (2.4%) -**Total Observations:** 2,194 -**Learning Loop Status:** ACTIVE -**Auto-approval Candidates:** 0 (need 10 obs + 3 fixes) - ---- - -**Last Updated:** 2026-04-14T17:15:00+00:00 -**Maintained By:** Hypatia Learning Loop -**Questions?** See `DEPLOYMENT-MANIFEST-*.md` for detailed deployment history diff --git a/schema/README.adoc b/schema/README.adoc index cf56b2e5..7443cfcd 100644 --- a/schema/README.adoc +++ b/schema/README.adoc @@ -23,7 +23,7 @@ Every finding carries three fields whose meaning is fixed by |`support` |What the evidence supports. `pattern`: a rule matched. `observed`: a fleet -observation count (the rules.a2ml thresholds, 5 to propose and 10 + 3 fixes to +observation count (the rule-lifecycle thresholds, 5 to propose and 10 + 3 fixes to auto-approve, are belief-formation rules, not soundness proofs). `mechanical`: a prover re-checked the flagged file, with both digests recorded. diff --git a/schema/findings.ncl b/schema/findings.ncl index 69f80dcb..3cb9353a 100644 --- a/schema/findings.ncl +++ b/schema/findings.ncl @@ -53,7 +53,7 @@ in # pattern — a pattern matched: evidence that the pattern matched, and # nothing more. # observed — the finding has been observed `observations` times across -# the fleet. rules.a2ml proposes a rule at 5 observations and +# the fleet. The rule lifecycle proposes a rule at 5 observations and # auto-approves at 10 + 3 successful fixes; those thresholds # are BELIEF-FORMATION rules, not soundness proofs, and no # count makes a finding sound. diff --git a/src/Hypatia/ABI/Verdict.idr b/src/Hypatia/ABI/Verdict.idr index a82bdf4f..ab9129b1 100644 --- a/src/Hypatia/ABI/Verdict.idr +++ b/src/Hypatia/ABI/Verdict.idr @@ -10,7 +10,7 @@ -- the only such map hypatia has today is a mechanical falsifier: a prover -- re-checking the file a proof-bypass detector flagged. A pattern match is -- evidence that the pattern matched; an observation count is belief --- formation (rules.a2ml proposes a rule at 5 observations); neither is a +-- formation (the rule lifecycle proposes a rule at 5 observations); neither is a -- proof that the property holds. -- -- What is proved here (Idris2, %default total, no proof-bypass primitives): @@ -148,7 +148,7 @@ data Support : Type where ||| A pattern matched. Evidence that the pattern matched, and nothing more. Pattern : Support ||| The finding has been observed `n` times across the fleet. A count is - ||| belief formation; rules.a2ml's proposal threshold of 5 is a policy, not + ||| belief formation; the rule lifecycle's proposal threshold of 5 is a policy, not ||| a soundness proof. Observed : (n : Nat) -> Support ||| A prover re-checked the flagged file. diff --git a/tests/reject/ObservedIsNotSound.idr b/tests/reject/ObservedIsNotSound.idr index eccd6006..8025fa9d 100644 --- a/tests/reject/ObservedIsNotSound.idr +++ b/tests/reject/ObservedIsNotSound.idr @@ -6,7 +6,7 @@ -- other declaration must typecheck, so that the refusal is for the stated -- reason and not for a missing import or a typo. -- --- Must fail: an observation count is belief formation. rules.a2ml +-- Must fail: an observation count is belief formation. The rule lifecycle -- proposes a rule at 5 observations; that threshold is a policy, and no count, -- however large, makes `Observed n` sound. -- From e9a6190c82949c5acd0c8187579ab02947d673c0 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 14 Nov 2026 18:33:56 +0000 Subject: [PATCH 04/10] test(rule_loader): inline the three hypatia-rules fixtures; ship no .a2ml RuleLoader is a shared reader of standards' hypatia-rules/*.a2ml, which is still the only form those definitions take (A7 section 10 moves them to A5 rule registry entries in both repositories together), so its .a2ml reading stays. Its fixtures need not be checked-in .a2ml files: the three definitions are now ~S heredocs in the test, written to a temporary directory in setup_all. They are byte-identical to the deleted fixtures (verified by diff), and the ten tests pass unchanged. docs/history/A2ML-REMOVED.adoc gains the three removed fixtures. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_0136P7ZoBy5xGnGDLk7wQ8jC --- docs/history/A2ML-REMOVED.adoc | 21 ++ .../hypatia_rules/profile-drift-detector.a2ml | 68 ---- .../hypatia_rules/registry-staleness.a2ml | 155 -------- .../hypatia_rules/rsr-self-compliance.a2ml | 81 ----- test/rules/rule_loader_test.exs | 340 +++++++++++++++++- 5 files changed, 354 insertions(+), 311 deletions(-) delete mode 100644 test/fixtures/hypatia_rules/profile-drift-detector.a2ml delete mode 100644 test/fixtures/hypatia_rules/registry-staleness.a2ml delete mode 100644 test/fixtures/hypatia_rules/rsr-self-compliance.a2ml diff --git a/docs/history/A2ML-REMOVED.adoc b/docs/history/A2ML-REMOVED.adoc index 03c08a88..225d1f5b 100644 --- a/docs/history/A2ML-REMOVED.adoc +++ b/docs/history/A2ML-REMOVED.adoc @@ -202,6 +202,27 @@ Size is in bytes. The sha256 is of the file as it was tracked. | Prose instructions for rule management: the rule lifecycle (5 observations to propose, 10 + 3 fixes to auto-approve) and rule quality standards. | Deleted: no mapping spec. Comments that cited it now state the thresholds without the file name. +| `test/fixtures/hypatia_rules/profile-drift-detector.a2ml` +| 2810 +| `ef6ec038778a93c8a960f70ed7a84cfa3ec66a63437d6b4e7b8f638e32e30d35` +| `f5b4b07b2dd3741d35845eacf7eb2f915ffe6476` +| RuleLoader fixture, a copy of a standards `hypatia-rules/` definition (HYP-S004). +| Inlined into `test/rules/rule_loader_test.exs`, which writes it to a temporary directory. + +| `test/fixtures/hypatia_rules/registry-staleness.a2ml` +| 7120 +| `d4646d83ac5dfff145da9d24ebc2690a963d702476ed957041de7248d5b7fd38` +| `db381f12820ec23149a7e03cb25a81b88110e01e` +| RuleLoader fixture (HYP-S006). +| Inlined into `test/rules/rule_loader_test.exs`. + +| `test/fixtures/hypatia_rules/rsr-self-compliance.a2ml` +| 2268 +| `ed67587df09c2a4bcf317e0d86cb1994ed24ad33ed039a88bac8c54d9b4cef8f` +| `261eb56f8bfcb774b768101d8bbdfe8f10932b6a` +| RuleLoader fixture (HYP-S007). +| Inlined into `test/rules/rule_loader_test.exs`. + |=== == Retained, with the reason diff --git a/test/fixtures/hypatia_rules/profile-drift-detector.a2ml b/test/fixtures/hypatia_rules/profile-drift-detector.a2ml deleted file mode 100644 index f5b4b07b..00000000 --- a/test/fixtures/hypatia_rules/profile-drift-detector.a2ml +++ /dev/null @@ -1,68 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# HYP-S007 — A2ML Profile Drift Detector -# Flags a 6a2 file whose content has drifted from the A2ML profile it -# declares via @profile(id=...). "Drift" = the file no longer satisfies its -# declared profile definition (missing required section, disallowed directive, -# cardinality/reference-class violation, or attestation floor not met). -# -# This rule operates on the A2ML profile mechanism specified in -# a2ml/SPEC.adoc Section 8 and the profile definitions in a2ml/profiles/. -# It is the dogfooding check that keeps the 6a2 estate honest about the -# profiles it claims to satisfy. -# -# FLAG-ONLY by construction: strategy :review, auto_fixable: false. This rule -# is structural; it has nothing to do with licences. It must never emit a -# licence/SPDX finding and must never auto-edit a file. - -@rule(version="1.0"): -id: HYP-S007 -name: "A2ML profile drift detector" -description: "Flag a 6a2 file whose content drifts from its declared @profile" -severity: medium -category: Dogfooding -strategy: review -auto_fixable: false -source: standards/hypatia-rules -@end - -@scanner(type="file-tree"): -find: - - glob: "**/.machine_readable/6a2/*.a2ml" - - glob: "**/.machine_readable/anchors/ANCHOR.a2ml" - - glob: "a2ml/profiles/*/PROFILE.a2ml" - - glob: "a2ml/profiles/REGISTRY.a2ml" -@end - -@logic(engine="built-in"): -# 1. For each 6a2 file, read the @profile(id=ns/name) declaration in its -# preamble. A 6a2 file with no @profile declaration is itself a finding -# (undeclared: cannot be validated through the mechanism). -# 2. Resolve ns/name against a2ml/profiles/REGISTRY.a2ml; confirm the -# definition's sha256 equals the registry-pinned hash. A hash mismatch is a -# finding (registry desync). -# 3. Load the profile definition (the five axes) and extract the file's facts: -# section titles (TOML [sections] or, for the key-based anchor dialect, -# top-level keys), directive occurrences, and @ref classes. -# 4. Compute conformance exactly as src/A2ML/Profiles.idr conformsB: -# - every required_section present, -# - every occurring directive permitted by allowed_directives, -# - required_directives cardinality satisfied, -# - required reference_classes present, -# - mode >= min_attestation. -# 5. Emit one finding per violation (mirrors Profiles.idr ProfileViolation). -steps: - - read_profile_decl: "@profile(id=*)" - - resolve_against_registry: "a2ml/profiles/REGISTRY.a2ml" - - verify_definition_hash: "sha256" - - extract_doc_facts: { sections: true, directives: true, ref_classes: true } - - check_conformance: "conformsB" - - emit_violations -@end - -@action: -emit_signal: compliance.finding.new -message_template: "Profile drift: {file} declares @profile({profile_id}) but {violation} (see a2ml/profiles/{profile_dir})" -recipe: none -@end - -@end diff --git a/test/fixtures/hypatia_rules/registry-staleness.a2ml b/test/fixtures/hypatia_rules/registry-staleness.a2ml deleted file mode 100644 index db381f12..00000000 --- a/test/fixtures/hypatia_rules/registry-staleness.a2ml +++ /dev/null @@ -1,155 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# HYP-S006 — Registry Staleness / Doc Drift -# Detects when the verifiable spec registry (.machine_readable/REGISTRY.a2ml) -# no longer matches ground truth, or when DERIVED docs (TOPOLOGY.md) were -# hand-edited away from their generated form. Drift becomes a routed finding -# the moment it lands — not something noticed 60 days later. -# -# Covers BOTH registry entry shapes: -# * LOCAL specs — recorded source_hash vs a fresh git-ls-files compute. -# * EXTERNAL specs (kind="external") — verified pointers to specs whose SSOT -# lives in another repo (e.g. AffineScript .affine/.affex/.affmap). The -# recorded source_hash is checked against a fresh fetch of canonical_url; -# re-pinning is capped to :review (owner decision, not an auto-regen). -# -# Companion to scripts/build-registry.sh (the generator) and -# .github/workflows/registry-verify.yml (the in-repo --check gate). This rule -# is the estate-side half: it lets Hypatia surface the same drift across the -# fleet and route it through the hybrid automation router. - -@rule(version="1.0"): -id: HYP-S006 -name: "Registry staleness / doc drift" -description: "Alert when a spec's recorded source_hash in REGISTRY.a2ml no longer matches a fresh compute (local) or a fresh fetch of canonical_url (external pointer), or a DERIVED doc (TOPOLOGY.md) drifted from its generator" -severity: medium -category: StandardsCompliance -auto_fixable: true -source: standards/hypatia-rules - -@parameters: -# How long a hash mismatch may persist before the finding escalates. -stale_after_days: 14 -critical_after_days: 60 -@end - -@scanner(type="file-tree"): -find: - - glob: ".machine_readable/REGISTRY.a2ml" - - glob: "TOPOLOGY.md" - - glob: "scripts/build-registry.sh" -@end - -@logic(engine="built-in"): -# Two entry shapes share one registry: -# * LOCAL (no `kind`) — recompute sha256 over `git ls-files -s ` -# exactly as the generator does, compare to the -# recorded value. -# * EXTERNAL (kind="external")— a verified pointer to a spec whose SSOT is -# another repo. Re-fetch canonical_url and -# recompute with source_hash_algo (sha256+; -# md5/sha1 are rejected as UNVERIFIED), compare -# to the recorded source_hash. This is the -# network-side check the offline generator and -# the in-repo registry-verify.yml cannot do. -steps: - - parse_registry: ".machine_readable/REGISTRY.a2ml" - extract: - - key: "home" - as: home - - key: "kind" - as: kind - - key: "canonical_url" - as: canonical_url - - key: "source_hash_algo" - as: algo - - key: "sync_status" - as: sync_status - - key: "source_hash" - as: recorded_hash - # --- LOCAL specs ------------------------------------------------------- - - for_each_spec where "kind != external": - recompute: "sha256(git ls-files -s ${home})" - compare_to: recorded_hash - emit_if: "recompute != recorded_hash" - finding_kind: registry-hash-stale - - check_home_exists where "kind != external": - emit_if: "home directory absent" - finding_kind: registry-dead-home - # --- EXTERNAL specs (verified pointers; SSOT in another repo) ---------- - - reject_weak_algo where "kind == external": - emit_if: "algo in [md5, sha1]" # security policy: no MD5/SHA1 - finding_kind: registry-weak-algo - - for_each_spec where "kind == external && recorded_hash != 'PENDING-FIRST-SYNC'": - fetch: canonical_url - recompute: "${algo}(fetched_content)" - compare_to: recorded_hash - emit_if: "recompute != recorded_hash" - finding_kind: registry-pointer-stale - - for_each_spec where "kind == external && recorded_hash == 'PENDING-FIRST-SYNC'": - # Not drift — upstream has not landed yet. Surface as info, and as a - # low finding only once it has sat unsynced beyond the grace window. - fetch: canonical_url - emit_if: "fetch succeeds" - finding_kind: registry-pointer-ready # ready for first sync (info) - emit_if: "still PENDING beyond ${stale_after_days}d" - finding_kind: registry-pointer-unsynced # low - # --- DERIVED docs ------------------------------------------------------ - - check_derived_docs: - command: "bash scripts/build-registry.sh --check" - emit_if: "non-zero exit" - finding_kind: derived-doc-stale -@end - -# --------------------------------------------------------------------------- -# Hybrid automation router strategy. -# The router decides whether a finding is auto-executed or held for review. -# Doc/registry drift is mechanical and safe to regenerate, EXCEPT where the -# drifted content touches licence/SPDX — those are FLAG-ONLY per the estate -# Manual-Only licence guardrail (.claude/CLAUDE.md) and hypatia -# license_finding_strategy/0. The router MUST honour the cap below. -# --------------------------------------------------------------------------- -@router: -default_strategy: auto_execute # regenerate REGISTRY.a2ml + TOPOLOGY.md -recipe: rebuild-registry -# Hard cap: any finding whose drift overlaps a licence/SPDX token is demoted -# to :review and never auto-applied, mirroring license_finding_strategy/0. -strategy_caps: - - when: "finding touches /SPDX-License-Identifier|PMPL|MPL-2\\.0|AGPL|Palimpsest|licen[cs]e/i" - cap: review - reason: "Manual-Only licence guardrail — agents flag, owner edits (neurophone#99)" - - when: "finding_kind == registry-dead-home" - cap: review - reason: "A missing home is a structural change, not a regen — needs human triage" - - when: "finding_kind in [registry-pointer-stale, registry-pointer-unsynced, registry-weak-algo]" - cap: review - reason: "External pointers reference another repo's SSOT — re-pinning version_pin/source_hash is an owner decision, never an auto-regen (rebuild-registry cannot recompute a cross-repo hash offline)." -@end - -@action: -emit_signal: doc.drift -message_template: >- - Registry drift: {finding_kind} for spec '{id}' (home={home} url={canonical_url}). - Recorded {recorded_hash}, fresh compute/fetch differs. For LOCAL drift run - 'just registry' to regenerate; for EXTERNAL pointers re-pin is an owner - decision (capped :review). ({age_days}d since generated) -recipe: rebuild-registry -severity_escalates_at: 60 -halt_on_violation: false -dedupe_window_days: 7 -@end - -@recipe(id="rebuild-registry"): -description: "Regenerate the registry + derived topology from the file tree" -command: "bash scripts/build-registry.sh" -auto_applicable: true -# NOTE: auto_applicable is gated by @router strategy_caps above — a licence- -# overlapping drift is capped to :review and will NOT auto-run this recipe. -@end - -@sibling_rules: -- HYP-S003 proof-freshness — same staleness shape, for proof artefacts -- HYP-S004 rsr-self-compliance — structural self-dogfooding gate -- HYP-S005 crg-overclaim-detector — grade-honesty gate -@end - -@end diff --git a/test/fixtures/hypatia_rules/rsr-self-compliance.a2ml b/test/fixtures/hypatia_rules/rsr-self-compliance.a2ml deleted file mode 100644 index 261eb56f..00000000 --- a/test/fixtures/hypatia_rules/rsr-self-compliance.a2ml +++ /dev/null @@ -1,81 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# HYP-S004 — RSR Self-Compliance -# Validates the standards repo against its own RSR (Rhodium Standard -# Repositories) definition. A constitution that exempts itself from its -# own laws has no authority — this rule enforces self-dogfooding. - -@rule(version="1.0"): -id: HYP-S004 -name: "RSR self-compliance" -description: "Standards repo must satisfy every requirement it imposes on others" -severity: critical -category: Dogfooding -auto_fixable: false -source: standards/hypatia-rules - -@scanner(type="file-tree"): -target_repo: "standards" -reference: "rhodium-standard-repositories/RSR.adoc" -@end - -@required_files: -# RSR-mandated files that standards itself must have -- path: "README.adoc" - reason: "RSR R-001" -- path: "SECURITY.md" - reason: "RSR R-002" -- path: "CONTRIBUTING.md" - reason: "RSR R-003" -- path: "LICENSE" - reason: "RSR R-004" -- path: "CODE_OF_CONDUCT.md" - reason: "RSR R-005" -- path: ".editorconfig" - reason: "RSR R-010" -- path: "Justfile" - reason: "RSR R-020 (no Makefiles)" -- path: "guix.scm" - reason: "RSR R-030 (primary pkg manager)" -- path: "flake.nix" - reason: "RSR R-031 (fallback pkg manager)" -- path: ".machine_readable/" - reason: "RSR R-040 (A2ML metadata)" -@end - -@required_workflows: -- name: "hypatia-scan.yml" - reason: "RSR R-050 (self-scan)" -- name: "mirror.yml" - reason: "RSR R-051 (forge mirroring)" -- name: "scorecard.yml" - reason: "RSR R-052 (OpenSSF Scorecard)" -- name: "rsr-antipattern.yml" - reason: "RSR R-053 (antipattern check)" -@end - -@forbidden_files: -- glob: "**/*.ts" - reason: "TypeScript banned — use AffineScript (RS/TS/JS → AffineScript → typed-wasm per estate language defaults)" -- glob: "**/*.res" - reason: "ReScript banned — use AffineScript (RS/TS/JS → AffineScript → typed-wasm per estate language defaults)" -- glob: "**/*.py" - reason: "Python banned" -- glob: "**/*.go" - reason: "Go banned — use Rust" -- glob: "Dockerfile" - reason: "Use Containerfile (Podman)" -- glob: "Makefile" - reason: "Use Justfile" -- glob: "STATE.a2ml" - at: "/" - reason: "A2ML files go in .machine_readable/ only" -@end - -@action: -emit_signal: compliance.finding.new -message_template: "RSR self-compliance violation: {reason} ({path})" -recipe: none -halt_on_violation: true -@end - -@end diff --git a/test/rules/rule_loader_test.exs b/test/rules/rule_loader_test.exs index 1f5f2b69..6c17c9dd 100644 --- a/test/rules/rule_loader_test.exs +++ b/test/rules/rule_loader_test.exs @@ -7,11 +7,337 @@ defmodule Hypatia.Rules.RuleLoaderTest do alias Hypatia.Rules.RuleLoader alias Hypatia.Rules.RuleLoader.RuleDef - @fixtures Path.expand("../fixtures/hypatia_rules", __DIR__) + # RuleLoader reads standards' hypatia-rules/*.a2ml, which is still the only + # form those rule definitions take (A7 section 10: they move to A5 rule + # registry entries in both repositories together). A2ML is retired, so this + # repository ships no .a2ml fixture: the three definitions below are copies + # of standards rule files, written to a temporary directory for each run. + @rule_files %{ + "profile-drift-detector.a2ml" => ~S""" + # SPDX-License-Identifier: MPL-2.0 + # HYP-S007 — A2ML Profile Drift Detector + # Flags a 6a2 file whose content has drifted from the A2ML profile it + # declares via @profile(id=...). "Drift" = the file no longer satisfies its + # declared profile definition (missing required section, disallowed directive, + # cardinality/reference-class violation, or attestation floor not met). + # + # This rule operates on the A2ML profile mechanism specified in + # a2ml/SPEC.adoc Section 8 and the profile definitions in a2ml/profiles/. + # It is the dogfooding check that keeps the 6a2 estate honest about the + # profiles it claims to satisfy. + # + # FLAG-ONLY by construction: strategy :review, auto_fixable: false. This rule + # is structural; it has nothing to do with licences. It must never emit a + # licence/SPDX finding and must never auto-edit a file. + + @rule(version="1.0"): + id: HYP-S007 + name: "A2ML profile drift detector" + description: "Flag a 6a2 file whose content drifts from its declared @profile" + severity: medium + category: Dogfooding + strategy: review + auto_fixable: false + source: standards/hypatia-rules + @end + + @scanner(type="file-tree"): + find: + - glob: "**/.machine_readable/6a2/*.a2ml" + - glob: "**/.machine_readable/anchors/ANCHOR.a2ml" + - glob: "a2ml/profiles/*/PROFILE.a2ml" + - glob: "a2ml/profiles/REGISTRY.a2ml" + @end + + @logic(engine="built-in"): + # 1. For each 6a2 file, read the @profile(id=ns/name) declaration in its + # preamble. A 6a2 file with no @profile declaration is itself a finding + # (undeclared: cannot be validated through the mechanism). + # 2. Resolve ns/name against a2ml/profiles/REGISTRY.a2ml; confirm the + # definition's sha256 equals the registry-pinned hash. A hash mismatch is a + # finding (registry desync). + # 3. Load the profile definition (the five axes) and extract the file's facts: + # section titles (TOML [sections] or, for the key-based anchor dialect, + # top-level keys), directive occurrences, and @ref classes. + # 4. Compute conformance exactly as src/A2ML/Profiles.idr conformsB: + # - every required_section present, + # - every occurring directive permitted by allowed_directives, + # - required_directives cardinality satisfied, + # - required reference_classes present, + # - mode >= min_attestation. + # 5. Emit one finding per violation (mirrors Profiles.idr ProfileViolation). + steps: + - read_profile_decl: "@profile(id=*)" + - resolve_against_registry: "a2ml/profiles/REGISTRY.a2ml" + - verify_definition_hash: "sha256" + - extract_doc_facts: { sections: true, directives: true, ref_classes: true } + - check_conformance: "conformsB" + - emit_violations + @end + + @action: + emit_signal: compliance.finding.new + message_template: "Profile drift: {file} declares @profile({profile_id}) but {violation} (see a2ml/profiles/{profile_dir})" + recipe: none + @end + + @end + """, + "registry-staleness.a2ml" => ~S""" + # SPDX-License-Identifier: MPL-2.0 + # HYP-S006 — Registry Staleness / Doc Drift + # Detects when the verifiable spec registry (.machine_readable/REGISTRY.a2ml) + # no longer matches ground truth, or when DERIVED docs (TOPOLOGY.md) were + # hand-edited away from their generated form. Drift becomes a routed finding + # the moment it lands — not something noticed 60 days later. + # + # Covers BOTH registry entry shapes: + # * LOCAL specs — recorded source_hash vs a fresh git-ls-files compute. + # * EXTERNAL specs (kind="external") — verified pointers to specs whose SSOT + # lives in another repo (e.g. AffineScript .affine/.affex/.affmap). The + # recorded source_hash is checked against a fresh fetch of canonical_url; + # re-pinning is capped to :review (owner decision, not an auto-regen). + # + # Companion to scripts/build-registry.sh (the generator) and + # .github/workflows/registry-verify.yml (the in-repo --check gate). This rule + # is the estate-side half: it lets Hypatia surface the same drift across the + # fleet and route it through the hybrid automation router. + + @rule(version="1.0"): + id: HYP-S006 + name: "Registry staleness / doc drift" + description: "Alert when a spec's recorded source_hash in REGISTRY.a2ml no longer matches a fresh compute (local) or a fresh fetch of canonical_url (external pointer), or a DERIVED doc (TOPOLOGY.md) drifted from its generator" + severity: medium + category: StandardsCompliance + auto_fixable: true + source: standards/hypatia-rules + + @parameters: + # How long a hash mismatch may persist before the finding escalates. + stale_after_days: 14 + critical_after_days: 60 + @end + + @scanner(type="file-tree"): + find: + - glob: ".machine_readable/REGISTRY.a2ml" + - glob: "TOPOLOGY.md" + - glob: "scripts/build-registry.sh" + @end + + @logic(engine="built-in"): + # Two entry shapes share one registry: + # * LOCAL (no `kind`) — recompute sha256 over `git ls-files -s ` + # exactly as the generator does, compare to the + # recorded value. + # * EXTERNAL (kind="external")— a verified pointer to a spec whose SSOT is + # another repo. Re-fetch canonical_url and + # recompute with source_hash_algo (sha256+; + # md5/sha1 are rejected as UNVERIFIED), compare + # to the recorded source_hash. This is the + # network-side check the offline generator and + # the in-repo registry-verify.yml cannot do. + steps: + - parse_registry: ".machine_readable/REGISTRY.a2ml" + extract: + - key: "home" + as: home + - key: "kind" + as: kind + - key: "canonical_url" + as: canonical_url + - key: "source_hash_algo" + as: algo + - key: "sync_status" + as: sync_status + - key: "source_hash" + as: recorded_hash + # --- LOCAL specs ------------------------------------------------------- + - for_each_spec where "kind != external": + recompute: "sha256(git ls-files -s ${home})" + compare_to: recorded_hash + emit_if: "recompute != recorded_hash" + finding_kind: registry-hash-stale + - check_home_exists where "kind != external": + emit_if: "home directory absent" + finding_kind: registry-dead-home + # --- EXTERNAL specs (verified pointers; SSOT in another repo) ---------- + - reject_weak_algo where "kind == external": + emit_if: "algo in [md5, sha1]" # security policy: no MD5/SHA1 + finding_kind: registry-weak-algo + - for_each_spec where "kind == external && recorded_hash != 'PENDING-FIRST-SYNC'": + fetch: canonical_url + recompute: "${algo}(fetched_content)" + compare_to: recorded_hash + emit_if: "recompute != recorded_hash" + finding_kind: registry-pointer-stale + - for_each_spec where "kind == external && recorded_hash == 'PENDING-FIRST-SYNC'": + # Not drift — upstream has not landed yet. Surface as info, and as a + # low finding only once it has sat unsynced beyond the grace window. + fetch: canonical_url + emit_if: "fetch succeeds" + finding_kind: registry-pointer-ready # ready for first sync (info) + emit_if: "still PENDING beyond ${stale_after_days}d" + finding_kind: registry-pointer-unsynced # low + # --- DERIVED docs ------------------------------------------------------ + - check_derived_docs: + command: "bash scripts/build-registry.sh --check" + emit_if: "non-zero exit" + finding_kind: derived-doc-stale + @end + + # --------------------------------------------------------------------------- + # Hybrid automation router strategy. + # The router decides whether a finding is auto-executed or held for review. + # Doc/registry drift is mechanical and safe to regenerate, EXCEPT where the + # drifted content touches licence/SPDX — those are FLAG-ONLY per the estate + # Manual-Only licence guardrail (.claude/CLAUDE.md) and hypatia + # license_finding_strategy/0. The router MUST honour the cap below. + # --------------------------------------------------------------------------- + @router: + default_strategy: auto_execute # regenerate REGISTRY.a2ml + TOPOLOGY.md + recipe: rebuild-registry + # Hard cap: any finding whose drift overlaps a licence/SPDX token is demoted + # to :review and never auto-applied, mirroring license_finding_strategy/0. + strategy_caps: + - when: "finding touches /SPDX-License-Identifier|PMPL|MPL-2\\.0|AGPL|Palimpsest|licen[cs]e/i" + cap: review + reason: "Manual-Only licence guardrail — agents flag, owner edits (neurophone#99)" + - when: "finding_kind == registry-dead-home" + cap: review + reason: "A missing home is a structural change, not a regen — needs human triage" + - when: "finding_kind in [registry-pointer-stale, registry-pointer-unsynced, registry-weak-algo]" + cap: review + reason: "External pointers reference another repo's SSOT — re-pinning version_pin/source_hash is an owner decision, never an auto-regen (rebuild-registry cannot recompute a cross-repo hash offline)." + @end + + @action: + emit_signal: doc.drift + message_template: >- + Registry drift: {finding_kind} for spec '{id}' (home={home} url={canonical_url}). + Recorded {recorded_hash}, fresh compute/fetch differs. For LOCAL drift run + 'just registry' to regenerate; for EXTERNAL pointers re-pin is an owner + decision (capped :review). ({age_days}d since generated) + recipe: rebuild-registry + severity_escalates_at: 60 + halt_on_violation: false + dedupe_window_days: 7 + @end + + @recipe(id="rebuild-registry"): + description: "Regenerate the registry + derived topology from the file tree" + command: "bash scripts/build-registry.sh" + auto_applicable: true + # NOTE: auto_applicable is gated by @router strategy_caps above — a licence- + # overlapping drift is capped to :review and will NOT auto-run this recipe. + @end + + @sibling_rules: + - HYP-S003 proof-freshness — same staleness shape, for proof artefacts + - HYP-S004 rsr-self-compliance — structural self-dogfooding gate + - HYP-S005 crg-overclaim-detector — grade-honesty gate + @end + + @end + """, + "rsr-self-compliance.a2ml" => ~S""" + # SPDX-License-Identifier: MPL-2.0 + # HYP-S004 — RSR Self-Compliance + # Validates the standards repo against its own RSR (Rhodium Standard + # Repositories) definition. A constitution that exempts itself from its + # own laws has no authority — this rule enforces self-dogfooding. + + @rule(version="1.0"): + id: HYP-S004 + name: "RSR self-compliance" + description: "Standards repo must satisfy every requirement it imposes on others" + severity: critical + category: Dogfooding + auto_fixable: false + source: standards/hypatia-rules + + @scanner(type="file-tree"): + target_repo: "standards" + reference: "rhodium-standard-repositories/RSR.adoc" + @end + + @required_files: + # RSR-mandated files that standards itself must have + - path: "README.adoc" + reason: "RSR R-001" + - path: "SECURITY.md" + reason: "RSR R-002" + - path: "CONTRIBUTING.md" + reason: "RSR R-003" + - path: "LICENSE" + reason: "RSR R-004" + - path: "CODE_OF_CONDUCT.md" + reason: "RSR R-005" + - path: ".editorconfig" + reason: "RSR R-010" + - path: "Justfile" + reason: "RSR R-020 (no Makefiles)" + - path: "guix.scm" + reason: "RSR R-030 (primary pkg manager)" + - path: "flake.nix" + reason: "RSR R-031 (fallback pkg manager)" + - path: ".machine_readable/" + reason: "RSR R-040 (A2ML metadata)" + @end + + @required_workflows: + - name: "hypatia-scan.yml" + reason: "RSR R-050 (self-scan)" + - name: "mirror.yml" + reason: "RSR R-051 (forge mirroring)" + - name: "scorecard.yml" + reason: "RSR R-052 (OpenSSF Scorecard)" + - name: "rsr-antipattern.yml" + reason: "RSR R-053 (antipattern check)" + @end + + @forbidden_files: + - glob: "**/*.ts" + reason: "TypeScript banned — use AffineScript (RS/TS/JS → AffineScript → typed-wasm per estate language defaults)" + - glob: "**/*.res" + reason: "ReScript banned — use AffineScript (RS/TS/JS → AffineScript → typed-wasm per estate language defaults)" + - glob: "**/*.py" + reason: "Python banned" + - glob: "**/*.go" + reason: "Go banned — use Rust" + - glob: "Dockerfile" + reason: "Use Containerfile (Podman)" + - glob: "Makefile" + reason: "Use Justfile" + - glob: "STATE.a2ml" + at: "/" + reason: "A2ML files go in .machine_readable/ only" + @end + + @action: + emit_signal: compliance.finding.new + message_template: "RSR self-compliance violation: {reason} ({path})" + recipe: none + halt_on_violation: true + @end + + @end + """ + } + + setup_all do + dir = + Path.join(System.tmp_dir!(), "hypatia-rule-loader-#{System.unique_integer([:positive])}") + + File.mkdir_p!(dir) + Enum.each(@rule_files, fn {name, text} -> File.write!(Path.join(dir, name), text) end) + on_exit(fn -> File.rm_rf!(dir) end) + %{fixtures: dir} + end describe "load_dir/1" do - test "loads every .a2ml rule definition, sorted by id" do - assert {:ok, rules} = RuleLoader.load_dir(@fixtures) + test "loads every .a2ml rule definition, sorted by id", %{fixtures: fixtures} do + assert {:ok, rules} = RuleLoader.load_dir(fixtures) assert Enum.map(rules, & &1.id) == ["HYP-S004", "HYP-S006", "HYP-S007"] assert Enum.all?(rules, &match?(%RuleDef{}, &1)) end @@ -23,8 +349,8 @@ defmodule Hypatia.Rules.RuleLoaderTest do end describe "parse/1 — metadata extraction" do - setup do - {:ok, rules} = RuleLoader.load_dir(@fixtures) + setup %{fixtures: fixtures} do + {:ok, rules} = RuleLoader.load_dir(fixtures) %{by_id: Map.new(rules, &{&1.id, &1})} end @@ -65,8 +391,8 @@ defmodule Hypatia.Rules.RuleLoaderTest do end describe "strategy caps — the Manual-Only licence guardrail" do - setup do - {:ok, rules} = RuleLoader.load_dir(@fixtures) + setup %{fixtures: fixtures} do + {:ok, rules} = RuleLoader.load_dir(fixtures) %{rules: rules, by_id: Map.new(rules, &{&1.id, &1})} end From e1935eb129083a8de0de148fbfc408cec47e9766 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 14 Nov 2026 18:36:18 +0000 Subject: [PATCH 05/10] feat(rules): read the deed-era carriers of STATE, META, ECOSYSTEM and ANCHOR A7 M5: shared readers read the new input first and keep the A2ML only as a fallback. Hypatia's own descriptiles now live in hypatia_chora.deed, and the oracle scored them as missing. RsrConformance (the RSR oracle): - 3.1.2 STATE accepts a top-level (status) clause (state-v1-decision, option B: the one lifecycle claim is that clause); - 3.1.3 META and 3.1.4 ECOSYSTEM accept (meta) and (ecosystem) (meta-ecosystem-to-repo-deed), as 3.1.5-3.1.7 and 3.1.9 already did for their clauses; - 3.1.8 accepts the (anchor) clause (A7 ruling S1: there is no ANCHOR.deed); - 3.2.1 with no record-dialect .a2ml left passes when the repo deed parses, and still fails when there is neither. The legacy .a2ml carriers still count. Nested clauses never do. HonestCompletion: a repo has state when its chora deed carries a top-level (status) clause or it has a STATE.deed; STATE.a2ml and STATE.scm still count. The finding no longer tells a repo to add an .a2ml file. Hypatia's self-score against the bundled criteria: 3.1.2-3.1.4 and 3.2.1 pass from the deed. 3.1.1 (a descriptiles/ directory) now fails: the criterion names the directory, and hypatia has none left. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_0136P7ZoBy5xGnGDLk7wQ8jC --- lib/rules/honest_completion.ex | 33 ++++++++++---- lib/rules/rsr_conformance.ex | 70 +++++++++++++++++++++-------- test/honest_completion_test.exs | 35 +++++++++++++++ test/rules/rsr_conformance_test.exs | 60 ++++++++++++++++++++++++- 4 files changed, 170 insertions(+), 28 deletions(-) diff --git a/lib/rules/honest_completion.ex b/lib/rules/honest_completion.ex index 42f21c62..5582d86e 100644 --- a/lib/rules/honest_completion.ex +++ b/lib/rules/honest_completion.ex @@ -94,17 +94,35 @@ defmodule Hypatia.Rules.HonestCompletion do end) end + # A2ML is retired. The deed-era carriers of state come first: a STATE.deed + # descriptile (A7 J15), or the top-level (status) clause of the repo's chora + # deed (state-v1-decision option B: the lifecycle claim is that clause). The + # legacy STATE.a2ml / STATE.scm still count for repos not yet migrated. defp state_file_exists?(repo_path) do + chora_status_clause?(repo_path) or state_named_file_exists?(repo_path) + end + + @state_names ~w(STATE.deed STATE.a2ml STATE.scm) + + defp chora_status_clause?(repo_path) do + with {:ok, path} <- Hypatia.Deed.repo_deed_path(repo_path), + {:ok, text} <- File.read(path), + {:ok, {"repo-deed", items}} <- Hypatia.Deed.parse(text) do + Enum.any?(items, &match?({:clause, "status", _}, &1)) + else + _ -> false + end + end + + defp state_named_file_exists?(repo_path) do mr = Path.join(repo_path, ".machine_readable") - direct = - File.exists?(Path.join(mr, "STATE.a2ml")) or - File.exists?(Path.join(mr, "STATE.scm")) + direct = Enum.any?(@state_names, &File.exists?(Path.join(mr, &1))) if direct do true else - # Look for STATE.{a2ml,scm} in any direct subdirectory of + # Look for STATE.{deed,a2ml,scm} in any direct subdirectory of # .machine_readable/. Bounded search (one level deep) so a # malicious repo can't tarpit us via deep nesting. case File.ls(mr) do @@ -112,9 +130,7 @@ defmodule Hypatia.Rules.HonestCompletion do Enum.any?(entries, fn entry -> sub = Path.join(mr, entry) - File.dir?(sub) and - (File.exists?(Path.join(sub, "STATE.a2ml")) or - File.exists?(Path.join(sub, "STATE.scm"))) + File.dir?(sub) and Enum.any?(@state_names, &File.exists?(Path.join(sub, &1))) end) _ -> @@ -365,7 +381,8 @@ defmodule Hypatia.Rules.HonestCompletion do [ %{ type: :no_state_file, - detail: "No STATE.a2ml or STATE.scm found", + detail: + "No state: no (status) clause in the repo deed, and no STATE.deed (or legacy STATE.a2ml or STATE.scm)", severity: :low, deduction: 5 } diff --git a/lib/rules/rsr_conformance.ex b/lib/rules/rsr_conformance.ex index e072b0d3..12f8b621 100644 --- a/lib/rules/rsr_conformance.ex +++ b/lib/rules/rsr_conformance.ex @@ -391,13 +391,13 @@ defmodule Hypatia.Rules.RsrConformance do ]), "2.3.1" => any_of(["0-AI-MANIFEST.a2ml", "0-AI-MANIFEST.deed"]), "3.1.1" => present_mr("descriptiles"), - "3.1.2" => descriptile("STATE"), - "3.1.3" => descriptile("META"), - "3.1.4" => descriptile("ECOSYSTEM"), + "3.1.2" => descriptile("STATE", "status"), + "3.1.3" => descriptile("META", "meta"), + "3.1.4" => descriptile("ECOSYSTEM", "ecosystem"), "3.1.5" => descriptile("AGENTIC", "agentic"), "3.1.6" => descriptile("NEUROSYM", "neurosym"), "3.1.7" => descriptile("PLAYBOOK", "playbook"), - "3.1.8" => any_of_mr(["descriptiles/ANCHOR.a2ml", "descriptiles/anchors/ANCHOR.a2ml"]), + "3.1.8" => anchor_present(), "3.1.9" => descriptile("CLADE", "clade"), "3.2.1" => &descriptiles_parse/1, "3.2.2" => profile_present(), @@ -462,16 +462,23 @@ defmodule Hypatia.Rules.RsrConformance do defp descriptile(name), do: present_mr(Path.join(["descriptiles", name <> ".a2ml"])) - # A descriptile whose family has a ruled mapping spec into the repo deed - # (metadatastician/standards 1-formats/deed/mappings/, ruled 2026-10-27: - # AGENTIC / NEUROSYM / PLAYBOOK -> (agentic) (neurosym) (playbook), and - # CLADE -> (clade), the estate clade the chora deed carries) is satisfied - # by either carrier: the legacy .a2ml, or that clause at the top level of the - # repo's one `_chora.deed`. A2ML is retired, so the deed is the - # successor and the .a2ml the transition form; 2.3.1 accepts its two - # carriers the same way. The deed must parse (Hypatia.Deed is the reader - # that agrees with the standards gate): a deed that does not parse declares - # nothing, and a clause nested inside another clause is not the descriptile. + # A descriptile whose family has a mapping spec into the repo deed + # (metadatastician/standards 1-formats/deed/mappings/) is satisfied by either + # carrier: the legacy .a2ml, or that clause at the top level of the repo's + # one `_chora.deed`. The families and their clauses: + # + # AGENTIC / NEUROSYM / PLAYBOOK -> (agentic) (neurosym) (playbook), and + # CLADE -> (clade), the estate clade the chora deed carries (ruled + # 2026-10-27); META / ECOSYSTEM -> (meta) (ecosystem) + # (meta-ecosystem-to-repo-deed.adoc); STATE -> (status) + # (state-v1-decision.adoc, option B, ruled 2026-11-10: the one lifecycle + # claim is the (status) clause, and the journal is not translated). + # + # A2ML is retired, so the deed is the successor and the .a2ml the transition + # form; 2.3.1 accepts its two carriers the same way. The deed must parse + # (Hypatia.Deed is the reader that agrees with the standards gate): a deed + # that does not parse declares nothing, and a clause nested inside another + # clause is not the descriptile. defp descriptile(name, clause) do a2ml = descriptile(name) @@ -501,6 +508,30 @@ defmodule Hypatia.Rules.RsrConformance do end end + # 3.1.8: the anchor. The legacy ANCHOR.a2ml still counts; its successor is + # the (anchor …) clause at the top level of the chora deed (standards A7 + # ruling S1; grammar clauses/anchor.abnf). There is no ANCHOR.deed file. + defp anchor_present do + legacy = any_of_mr(["descriptiles/ANCHOR.a2ml", "descriptiles/anchors/ANCHOR.a2ml"]) + + fn repo -> + case legacy.(repo) do + :pass -> :pass + _ -> if deed_clause?(repo, "anchor"), do: :pass, else: :fail + end + end + end + + defp deed_parses?(repo) do + with {:ok, path} <- Hypatia.Deed.repo_deed_path(repo), + {:ok, text} <- File.read(path), + {:ok, {"repo-deed", _items}} <- Hypatia.Deed.parse(text) do + true + else + _ -> false + end + end + defp deed_clause?(repo, clause) do with {:ok, path} <- Hypatia.Deed.repo_deed_path(repo), {:ok, text} <- File.read(path), @@ -515,9 +546,12 @@ defmodule Hypatia.Rules.RsrConformance do # files (the 0-AI-MANIFEST manifest and friends, which open with `@directive` # / prose rather than a `[section]` header) are a DIFFERENT A2ML surface and # are not validated by the record-dialect reader — requiring them to parse as - # record dialect would false-fail every conformant repo. An absent substrate, - # or no record-dialect file at all, is :fail — nothing to validate is not - # valid. + # record dialect would false-fail every conformant repo. With no + # record-dialect file at all, the successor carrier decides: a repo whose + # descriptiles moved into its chora deed passes when that deed parses + # (Hypatia.Deed, the reader that agrees with the standards gate). Neither a + # record-dialect file nor a parseable deed is :fail — nothing to validate is + # not valid. defp descriptiles_parse(repo) do candidates = Path.wildcard(Hypatia.Paths.machine_tree_join(repo, ["descriptiles", "*.a2ml"])) ++ @@ -530,7 +564,7 @@ defmodule Hypatia.Rules.RsrConformance do cond do record_files == [] -> - :fail + if deed_parses?(repo), do: :pass, else: :fail Enum.all?(record_files, fn f -> match?({:ok, _}, with({:ok, t} <- File.read(f), do: RecordDialect.parse(t))) diff --git a/test/honest_completion_test.exs b/test/honest_completion_test.exs index 38ba2756..a796da3b 100644 --- a/test/honest_completion_test.exs +++ b/test/honest_completion_test.exs @@ -130,4 +130,39 @@ defmodule Hypatia.Rules.HonestCompletionTest do assert findings == [] end end + + describe "collect_evidence/1 — where state is found" do + @describetag :tmp_dir + + @deed """ + ;; SPDX-License-Identifier: MPL-2.0 + (repo-deed + :schema-version "1.0.0" + :canonical-name "x" + :repo-uuid #u8"gv-clade-index:github.com/o/x" + :beholding-chora #uuid"0889b37b-defb-831f-973c-e119500db00e" + (status :phase active)) + """ + + test "the chora deed's top-level (status) clause is the state", %{tmp_dir: tmp} do + File.write!(Path.join(tmp, "x_chora.deed"), @deed) + assert HonestCompletion.collect_evidence(tmp).has_state_file + end + + test "a STATE.deed descriptile is the state", %{tmp_dir: tmp} do + dir = Path.join(tmp, ".machine_readable/descriptiles") + File.mkdir_p!(dir) + File.write!(Path.join(dir, "STATE.deed"), "") + assert HonestCompletion.collect_evidence(tmp).has_state_file + end + + test "a deed without (status), and no state file, is no state", %{tmp_dir: tmp} do + File.write!( + Path.join(tmp, "x_chora.deed"), + String.replace(@deed, "(status :phase active)", "(meta)") + ) + + refute HonestCompletion.collect_evidence(tmp).has_state_file + end + end end diff --git a/test/rules/rsr_conformance_test.exs b/test/rules/rsr_conformance_test.exs index 18542ad7..16f2461d 100644 --- a/test/rules/rsr_conformance_test.exs +++ b/test/rules/rsr_conformance_test.exs @@ -392,6 +392,61 @@ defmodule Hypatia.Rules.RsrConformanceTest do assert agentic_verdicts(tmp) == %{"3.1.5" => :fail, "3.1.6" => :fail, "3.1.7" => :fail} end + defp deed_era_verdicts(tmp) do + {:ok, catalogue} = RsrCriteria.load(@ssot) + {:ok, sc} = RsrConformance.score(catalogue, tmp) + sc.results |> Map.new(&{&1.id, &1.verdict}) |> Map.take(~w(3.1.2 3.1.3 3.1.4 3.1.8 3.2.1)) + end + + # STATE -> (status) (state-v1-decision option B), META -> (meta), + # ECOSYSTEM -> (ecosystem) (meta-ecosystem-to-repo-deed), ANCHOR -> + # (anchor) (A7 ruling S1); with no .a2ml left, 3.2.1 is the deed parsing. + test "top-level (status) (meta) (ecosystem) (anchor) clauses satisfy 3.1.2-3.1.4, 3.1.8 and 3.2.1", + %{tmp_dir: tmp} do + mk!( + tmp, + "x_chora.deed", + @deed_head <> + """ + (status :phase active) + (meta :last-updated "2026-11-14") + (ecosystem :project "x" :ecosystem "hyperpolymath") + (anchor :schema "hyperpolymath.anchor/2" :authority "upstream-canonical")) + """ + ) + + assert deed_era_verdicts(tmp) == %{ + "3.1.2" => :pass, + "3.1.3" => :pass, + "3.1.4" => :pass, + "3.1.8" => :pass, + "3.2.1" => :pass + } + end + + test "nested clauses do not, and a deed that does not parse fails 3.2.1", %{tmp_dir: tmp} do + mk!( + tmp, + "x_chora.deed", + @deed_head <> " (notes (status) (meta) (ecosystem) (anchor)))\n" + ) + + assert deed_era_verdicts(tmp) == %{ + "3.1.2" => :fail, + "3.1.3" => :fail, + "3.1.4" => :fail, + "3.1.8" => :fail, + "3.2.1" => :pass + } + + File.write!(Path.join(tmp, "x_chora.deed"), @deed_head <> " (meta) ; )\n") + assert deed_era_verdicts(tmp)["3.2.1"] == :fail + end + + test "with neither a record-dialect .a2ml nor a deed, 3.2.1 fails", %{tmp_dir: tmp} do + assert deed_era_verdicts(tmp)["3.2.1"] == :fail + end + # 3.1.9 is the ESTATE clade (registers into gv-clade-index), which the # chora deed's (clade) clause carries. In-repo clade organisation (the # subtrees a repo groups its own content into, e.g. boj-server's @@ -496,8 +551,9 @@ defmodule Hypatia.Rules.RsrConformanceTest do repo_root = Path.expand("../..", __DIR__) assert {:ok, %Scorecard{} = sc} = RsrConformance.score(catalogue, repo_root) - # hypatia predates the descriptiles migration (still 6a2/) — the oracle - # must report that honestly rather than crash or invent a pass. + # hypatia carries its descriptiles as chora-deed clauses (A2ML retired + # 2026-11-14) and has no descriptiles/ directory, which 3.1.1 still names: + # the oracle must report that honestly rather than crash or invent a pass. verdicts = Map.new(sc.results, &{&1.id, &1.verdict}) assert verdicts["3.1.1"] in [:pass, :fail] assert sc.provisional == true From 009bb150bd4c8c4f108cd50d02d20c234b69e0dc Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 14 Nov 2026 18:37:33 +0000 Subject: [PATCH 06/10] docs: point agents and readers at the deeds, not the retired .a2ml files - .claude/CLAUDE.md: the "Machine-Readable Artefacts" section told agents to read six descriptiles/*.a2ml files that no longer exist. It now names 0-AI-MANIFEST.deed, hypatia_chora.deed and its clauses, the rules praxis deed and the removal ledger, says A2ML must not be created, and lists the two .a2ml files that remain and why. - README.adoc "Project status" points at hypatia_chora.deed instead of STATE.a2ml and PLAYBOOK.a2ml. - docs/quickstart/llm-warmup-dev.adoc no longer lists .machine_readable/6a2/ *.a2ml as the metadata home. scripts/check-readme-claims.sh and tests/readme-claims-test.sh pass. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_0136P7ZoBy5xGnGDLk7wQ8jC --- .claude/CLAUDE.md | 26 ++++++++++++++++++-------- README.adoc | 6 +++--- docs/quickstart/llm-warmup-dev.adoc | 8 +++----- 3 files changed, 24 insertions(+), 16 deletions(-) diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index eb560f6a..f0609432 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -69,14 +69,24 @@ see Known Gaps 3 before quoting a green suite. ## Machine-Readable Artefacts -Files in `.machine_readable/` contain structured project metadata: - -- `.machine_readable/descriptiles/STATE.a2ml` - Current project state and progress -- `.machine_readable/descriptiles/META.a2ml` - Architecture decisions and development practices -- `.machine_readable/descriptiles/ECOSYSTEM.a2ml` - Position in the ecosystem and related projects -- `.machine_readable/descriptiles/AGENTIC.a2ml` - AI agent interaction patterns -- `.machine_readable/descriptiles/NEUROSYM.a2ml` - Neurosymbolic integration config -- `.machine_readable/descriptiles/PLAYBOOK.a2ml` - Operational runbook +A2ML is retired (standards rulings D99, D269c, D312, D313). Hypatia was migrated off it on +2026-11-14: never create, restore or extend a `.a2ml` file here. Repository facts are deed +clauses (grammar: standards `1-formats/deed/spec/abnf/deed.abnf`; lint with +`bun /1-formats/deed/tools/deed_lint.js FILE.deed`): + +- `0-AI-MANIFEST.deed` - the machine front door, pointer-only +- `hypatia_chora.deed` - the repo deed: `(identity)` `(clade)` `(forges)` `(lineage)` `(status)` + (lifecycle), `(maturity)`, `(meta)` (ADRs), `(ecosystem)`, `(agentic)` (agent permissions and + integrity axioms), `(neurosym)` (scan config), `(playbook)`, `(egress)` (ADR-009) +- `hypatia_rules_praxis.deed` - the A5 rule registry, generated by `scripts/gen-rules-praxis.sh` +- `docs/history/A2ML-REMOVED.adoc` - each removed `.a2ml` file, its git blob id, and where its + content went + +Two `.a2ml` files remain, each for a reader outside this repo (see the ledger): +`audits/assail-classifications.a2ml` (panic-attack reads only that name) and +`test/fixtures/a2ml/rsr-criteria-v2.a2ml` (a copy of the standards RSR criteria, still A2ML). +The rules that *detect* `.a2ml` in scanned repos, and the shared readers that fall back to it +(`RsrConformance`, `RsrCriteria`, `RuleLoader`), are deliberate. ## Safety Triangle Pipeline (OPERATIONAL) diff --git a/README.adoc b/README.adoc index ee83c9ee..073764ed 100644 --- a/README.adoc +++ b/README.adoc @@ -190,10 +190,10 @@ auto-quarantine. == Project status -Development state, milestones and known gaps live in machine-readable form: +Development state, milestones and known gaps: -* `.machine_readable/descriptiles/STATE.a2ml` — current state and milestone status -* `.machine_readable/descriptiles/PLAYBOOK.a2ml` — operational runbook +* link:hypatia_chora.deed[hypatia_chora.deed] — the repo deed: lifecycle `(status)`, `(maturity)`, + ADRs in `(meta)`, `(ecosystem)`, `(agentic)`, `(neurosym)` and `(playbook)` * link:ROADMAP.adoc[ROADMAP.adoc] — milestone history **Before trusting any metric or green board, read link:docs/DEBT-REGISTER.adoc[docs/DEBT-REGISTER.adoc].** diff --git a/docs/quickstart/llm-warmup-dev.adoc b/docs/quickstart/llm-warmup-dev.adoc index 71ee7f77..8881ec1a 100644 --- a/docs/quickstart/llm-warmup-dev.adoc +++ b/docs/quickstart/llm-warmup-dev.adoc @@ -246,11 +246,9 @@ Pattern recipes live in `+patterns/+`. To add a new pattern: === Machine-Readable Metadata -All in `+.machine_readable/6a2/+`: - `+STATE.a2ml+`, `+META.a2ml+`, -`+ECOSYSTEM.a2ml+` - `+AGENTIC.a2ml+`, `+NEUROSYM.a2ml+`, -`+PLAYBOOK.a2ml+` - -*NEVER* create these in the root directory. +Repository facts (state, meta, ecosystem, agentic, neurosym, playbook) are +clauses of `+hypatia_chora.deed+` at the root; `+0-AI-MANIFEST.deed+` is the +pointer-only front door. A2ML is retired: *NEVER* create a `+.a2ml+` file. === License From 7d1059aa9c290c02b7249dacdf4d6b8514b82135 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 14 Nov 2026 18:37:33 +0000 Subject: [PATCH 07/10] chore(tools): remove scm-to-a2ml.sh, a producer of A2ML files The script converted STATE/META/ECOSYSTEM .scm checkpoints into new .a2ml files. A2ML is retired and nothing may create one (standards rulings D99, D269c, D312, D313; A7 Part 1 stops the producers). Nothing in the tree called it. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_0136P7ZoBy5xGnGDLk7wQ8jC --- tools/scm-to-a2ml.sh | 419 ------------------------------------------- 1 file changed, 419 deletions(-) delete mode 100755 tools/scm-to-a2ml.sh diff --git a/tools/scm-to-a2ml.sh b/tools/scm-to-a2ml.sh deleted file mode 100755 index 829060ec..00000000 --- a/tools/scm-to-a2ml.sh +++ /dev/null @@ -1,419 +0,0 @@ -#!/usr/bin/env bash -# SPDX-License-Identifier: MPL-2.0 -# scm-to-a2ml.sh — Convert SCM checkpoint files to A2ML format -# -# Scans a repo's .machine_readable/ directory for checkpoint .scm files -# (STATE, META, ECOSYSTEM, AGENTIC, NEUROSYM, PLAYBOOK, LANGUAGES) -# and creates corresponding .a2ml versions using TOML-like A2ML format. -# -# Does NOT delete original .scm files — user reviews conversions first. -# -# Usage: -# scm-to-a2ml.sh -# scm-to-a2ml.sh --scan # scan mode: report only, no conversion -# -# Author: Jonathan D.A. Jewell -# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) - -set -euo pipefail - -# --- Constants --- -readonly CHECKPOINT_NAMES="STATE META ECOSYSTEM AGENTIC NEUROSYM PLAYBOOK LANGUAGES" -readonly TODAY="$(date +%Y-%m-%d)" -readonly SCRIPT_NAME="$(basename "$0")" - -# --- Color output (if terminal) --- -if [[ -t 1 ]]; then - readonly C_GREEN='\033[0;32m' - readonly C_YELLOW='\033[0;33m' - readonly C_RED='\033[0;31m' - readonly C_CYAN='\033[0;36m' - readonly C_RESET='\033[0m' -else - readonly C_GREEN='' C_YELLOW='' C_RED='' C_CYAN='' C_RESET='' -fi - -# --- Utility functions --- - -info() { printf "${C_CYAN}[INFO]${C_RESET} %s\n" "$*"; } -ok() { printf "${C_GREEN}[OK]${C_RESET} %s\n" "$*"; } -warn() { printf "${C_YELLOW}[WARN]${C_RESET} %s\n" "$*"; } -error() { printf "${C_RED}[ERROR]${C_RESET} %s\n" "$*" >&2; } - -usage() { - cat < Convert .scm checkpoint files in a single repo - $SCRIPT_NAME --scan Scan repos and report migration status (no changes) - $SCRIPT_NAME --help Show this help - -Options: - --dry-run Show what would be converted without writing files - --force Overwrite existing .a2ml files (default: skip if exists) - -Examples: - $SCRIPT_NAME ~/Documents/hyperpolymath-repos/my-repo - $SCRIPT_NAME --scan ~/Documents/hyperpolymath-repos/ - $SCRIPT_NAME --dry-run ~/Documents/hyperpolymath-repos/my-repo -EOF - exit 0 -} - -# --- SCM to A2ML conversion --- -# Parses S-expression checkpoint files and emits TOML-like A2ML. -# -# Conversion rules: -# - ;; comments -> # comments -# - (section ...) -> [section] -# - (key "value") -> key = "value" -# - (key value) -> key = "value" (unquoted atoms get quoted) -# - (key (items ...)) -> key = ["item1", "item2", ...] -# - Nested (sub ...) -> [section.sub] -# - Empty lists () -> omitted or key = [] - -convert_scm_to_a2ml() { - local scm_file="$1" - local a2ml_file="$2" - local basename_noext="$3" - local project_name="$4" - - # Extract the file purpose from the basename - local file_desc="" - case "$basename_noext" in - STATE) file_desc="Project state checkpoint" ;; - META) file_desc="Project meta-information" ;; - ECOSYSTEM) file_desc="Ecosystem position and relationships" ;; - AGENTIC) file_desc="Agentic contract and automation rules" ;; - NEUROSYM) file_desc="Neurosymbolic integration manifest" ;; - PLAYBOOK) file_desc="Operational playbook" ;; - LANGUAGES) file_desc="Language configuration" ;; - *) file_desc="Checkpoint file" ;; - esac - - # Write A2ML header - { - echo "# SPDX-License-Identifier: MPL-2.0" - echo "# ${basename_noext}.a2ml — ${file_desc}" - echo "# Converted from ${basename_noext}.scm by scm-to-a2ml.sh on ${TODAY}" - echo "" - } > "$a2ml_file" - - # Parse the SCM file and convert to A2ML - # Strategy: line-by-line parsing with state tracking - local current_section="" - local in_list=0 - local list_items="" - - while IFS= read -r line; do - # Skip empty lines - if [[ -z "${line// /}" ]]; then - echo "" >> "$a2ml_file" - continue - fi - - # Convert comments: ;; -> # - if [[ "$line" =~ ^[[:space:]]*\;\; ]]; then - local comment_text - comment_text="${line#*;;}" - # Skip SPDX and Media-Type lines (we already wrote our header) - if [[ "$comment_text" =~ SPDX-License-Identifier ]] || \ - [[ "$comment_text" =~ Media-Type ]]; then - continue - fi - echo "#${comment_text}" >> "$a2ml_file" - continue - fi - - # Strip leading/trailing whitespace for parsing - local trimmed - trimmed="$(echo "$line" | sed 's/^[[:space:]]*//' | sed 's/[[:space:]]*$//')" - - # Top-level form opener: (state, (meta, (ecosystem, etc. - # These are the root wrappers — skip them - if [[ "$trimmed" =~ ^\(([a-z_-]+)[[:space:]]*$ ]]; then - local form_name="${BASH_REMATCH[1]}" - # Root forms like (state, (meta, (ecosystem — skip - local lc_basename - lc_basename="$(echo "$basename_noext" | tr '[:upper:]' '[:lower:]')" - if [[ "$form_name" == "$lc_basename" ]]; then - continue - fi - # Section opener - current_section="$form_name" - echo "[$form_name]" >> "$a2ml_file" - continue - fi - - # Section with content on same line: (section-name - if [[ "$trimmed" =~ ^\(([a-z_-]+)$ ]]; then - current_section="${BASH_REMATCH[1]}" - echo "[${current_section}]" >> "$a2ml_file" - continue - fi - - # Key-value: (key "value") - if [[ "$trimmed" =~ ^\(([a-z_-]+)[[:space:]]+\"([^\"]*)\"\)$ ]]; then - local key="${BASH_REMATCH[1]}" - local val="${BASH_REMATCH[2]}" - echo "${key} = \"${val}\"" >> "$a2ml_file" - continue - fi - - # Key-value with unquoted atom: (key value) - if [[ "$trimmed" =~ ^\(([a-z_-]+)[[:space:]]+([^()\"[:space:]]+)\)$ ]]; then - local key="${BASH_REMATCH[1]}" - local val="${BASH_REMATCH[2]}" - # Keep numbers unquoted - if [[ "$val" =~ ^[0-9]+(\.[0-9]+)?$ ]]; then - echo "${key} = ${val}" >> "$a2ml_file" - else - echo "${key} = \"${val}\"" >> "$a2ml_file" - fi - continue - fi - - # Key with empty list: (key ()) - if [[ "$trimmed" =~ ^\(([a-z_-]+)[[:space:]]+\(\)\)$ ]]; then - local key="${BASH_REMATCH[1]}" - echo "${key} = []" >> "$a2ml_file" - continue - fi - - # Bare section-like key with no value, just a label: (key) - if [[ "$trimmed" =~ ^\(([a-z_-]+)\)$ ]]; then - local key="${BASH_REMATCH[1]}" - echo "${key} = []" >> "$a2ml_file" - continue - fi - - # Quoted string item in a list: ("some string") - if [[ "$trimmed" =~ ^\(\"([^\"]*)\"\)$ ]]; then - echo " - \"${BASH_REMATCH[1]}\"" >> "$a2ml_file" - continue - fi - - # Bare quoted string in a list context: "some string" - if [[ "$trimmed" =~ ^\"([^\"]*)\"$ ]]; then - echo " - \"${BASH_REMATCH[1]}\"" >> "$a2ml_file" - continue - fi - - # Closing parens — skip - if [[ "$trimmed" =~ ^\)+$ ]]; then - continue - fi - - # Key-value where value has parens/complex content: (key "value with (parens)") - # Fallback: emit as comment for manual review - if [[ "$trimmed" =~ ^\( ]]; then - local cleaned - cleaned="$(echo "$trimmed" | sed 's/^(//;s/)$//')" - echo "# [REVIEW] ${cleaned}" >> "$a2ml_file" - continue - fi - - # Anything else: preserve as comment for review - echo "# [REVIEW] ${trimmed}" >> "$a2ml_file" - - done < "$scm_file" - - # Clean up multiple blank lines - sed -i '/^$/N;/^\n$/d' "$a2ml_file" 2>/dev/null || true - - return 0 -} - -# --- Derive project name from repo path --- -get_project_name() { - local repo_path="$1" - basename "$repo_path" -} - -# --- Convert a single repo --- -convert_repo() { - local repo_path="$1" - local dry_run="${2:-false}" - local force="${3:-false}" - - local mr_dir="${repo_path}/.machine_readable" - - if [[ ! -d "$mr_dir" ]]; then - warn "No .machine_readable/ directory in: ${repo_path}" - return 1 - fi - - local project_name - project_name="$(get_project_name "$repo_path")" - local converted=0 - local skipped=0 - local failed=0 - - for name in $CHECKPOINT_NAMES; do - local scm_file="${mr_dir}/${name}.scm" - local a2ml_file="${mr_dir}/${name}.a2ml" - - # Skip if no .scm file - if [[ ! -f "$scm_file" ]]; then - continue - fi - - # Skip if .a2ml already exists (unless --force) - if [[ -f "$a2ml_file" ]] && [[ "$force" != "true" ]]; then - info "Skipping ${name}.scm (${name}.a2ml already exists) in ${project_name}" - skipped=$((skipped + 1)) - continue - fi - - if [[ "$dry_run" == "true" ]]; then - info "[DRY RUN] Would convert: ${scm_file} -> ${a2ml_file}" - converted=$((converted + 1)) - continue - fi - - # Perform conversion - if convert_scm_to_a2ml "$scm_file" "$a2ml_file" "$name" "$project_name"; then - ok "Converted: ${name}.scm -> ${name}.a2ml in ${project_name}" - converted=$((converted + 1)) - else - error "Failed to convert: ${scm_file}" - failed=$((failed + 1)) - fi - done - - # Also check 6scm/ subdirectory - local scm6_dir="${mr_dir}/6scm" - if [[ -d "$scm6_dir" ]]; then - info "Found 6scm/ archive directory in ${project_name} — skipping (archived originals)" - fi - - echo "" - info "Results for ${project_name}:" - info " Converted: ${converted}" - info " Skipped: ${skipped} (already have .a2ml)" - info " Failed: ${failed}" - - return 0 -} - -# --- Scan mode --- -scan_repos() { - local repos_root="$1" - - info "Scanning repos under: ${repos_root}" - echo "" - - local total_repos=0 - local repos_with_scm=0 - local repos_with_a2ml=0 - local repos_with_both=0 - local repos_scm_only=0 - local total_scm_files=0 - local total_a2ml_files=0 - - # Find all .machine_readable dirs - while IFS= read -r mr_dir; do - local repo_dir - repo_dir="$(dirname "$mr_dir")" - total_repos=$((total_repos + 1)) - - local has_scm=false - local has_a2ml=false - local scm_count=0 - local a2ml_count=0 - - for name in $CHECKPOINT_NAMES; do - [[ -f "${mr_dir}/${name}.scm" ]] && { has_scm=true; scm_count=$((scm_count + 1)); } - [[ -f "${mr_dir}/${name}.a2ml" ]] && { has_a2ml=true; a2ml_count=$((a2ml_count + 1)); } - done - - total_scm_files=$((total_scm_files + scm_count)) - total_a2ml_files=$((total_a2ml_files + a2ml_count)) - - if $has_scm; then repos_with_scm=$((repos_with_scm + 1)); fi - if $has_a2ml; then repos_with_a2ml=$((repos_with_a2ml + 1)); fi - if $has_scm && $has_a2ml; then repos_with_both=$((repos_with_both + 1)); fi - if $has_scm && ! $has_a2ml; then repos_scm_only=$((repos_scm_only + 1)); fi - - done < <(find "$repos_root" -type d -name '.machine_readable' 2>/dev/null | sort) - - echo "============================================" - echo " SCM -> A2ML Migration Report" - echo "============================================" - echo "" - echo " Directories with .machine_readable/: ${total_repos}" - echo " Repos with .scm checkpoint files: ${repos_with_scm}" - echo " Repos with .a2ml checkpoint files: ${repos_with_a2ml}" - echo " Repos with BOTH (partially migrated): ${repos_with_both}" - echo " Repos with SCM only (need migration): ${repos_scm_only}" - echo "" - echo " Total .scm checkpoint files: ${total_scm_files}" - echo " Total .a2ml checkpoint files: ${total_a2ml_files}" - echo " Files still needing conversion: $((total_scm_files - total_a2ml_files))" - echo "" - echo "============================================" - - return 0 -} - -# --- Main --- -main() { - local mode="convert" - local dry_run="false" - local force="false" - local target_path="" - - # Parse arguments - while [[ $# -gt 0 ]]; do - case "$1" in - --help|-h) - usage - ;; - --scan) - mode="scan" - shift - ;; - --dry-run) - dry_run="true" - shift - ;; - --force) - force="true" - shift - ;; - -*) - error "Unknown option: $1" - usage - ;; - *) - target_path="$1" - shift - ;; - esac - done - - if [[ -z "$target_path" ]]; then - error "No path specified." - usage - fi - - # Resolve to absolute path - target_path="$(cd "$target_path" 2>/dev/null && pwd)" || { - error "Path does not exist: $target_path" - exit 1 - } - - case "$mode" in - scan) - scan_repos "$target_path" - ;; - convert) - info "Converting SCM checkpoint files in: ${target_path}" - [[ "$dry_run" == "true" ]] && info "DRY RUN mode — no files will be written" - [[ "$force" == "true" ]] && warn "FORCE mode — existing .a2ml files will be overwritten" - echo "" - convert_repo "$target_path" "$dry_run" "$force" - ;; - esac -} - -main "$@" From 1f4e22fbe06f5a9c288374bec238f387e367d531 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 14 Nov 2026 19:05:29 +0000 Subject: [PATCH 08/10] chore(audits): translate assail-classifications.a2ml into a deed MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The last A2ML registry this repo kept for an outside reader. panic-attack now reads audits/assail-classifications_praxis.deed before the A2ML names (panic-attack branch feat/deed-classifications), so the file moves to deed form and the .a2ml goes. - audits/assail-classifications_praxis.deed: all 14 entries, entry for entry. (file "…"), (audit "…") and (rationale "…") are the :file, :audit and :rationale fields; (category "…") is the symbol :category. praxis-deed with :profile assail-classifications; :beholding-chora is the estate chora id hypatia_chora.deed already carries. - audits/assail-classifications.a2ml: deleted. - docs/history/A2ML-REMOVED.adoc: the file moves from Retained to Removed. - dogfood-gate.yml: the carve-outs for the A2ML registry go; the deed is an ordinary deed and is counted and validated (detection test updated). - .claude/CLAUDE.md: lists the deed; one .a2ml file remains. Lands only after panic-attack with the deed reader is the pinned scanner: until then the pinned panic-attack reads no registry here and the 14 audited findings come back unsuppressed. Checked: deed_lint.js (standards 490b952) OK; panic-attack feat/deed-classifications suppresses exactly the same findings on this tree as on the A2ML tree (123 suppressed of 306; 14 from the registry). Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_0136P7ZoBy5xGnGDLk7wQ8jC --- .claude/CLAUDE.md | 5 +- .github/workflows/dogfood-gate.yml | 11 +-- audits/assail-classifications.a2ml | 102 -------------------- audits/assail-classifications_praxis.deed | 112 ++++++++++++++++++++++ docs/history/A2ML-REMOVED.adoc | 18 ++-- test/dogfood_manifest_detection_test.rb | 5 +- 6 files changed, 129 insertions(+), 124 deletions(-) delete mode 100644 audits/assail-classifications.a2ml create mode 100644 audits/assail-classifications_praxis.deed diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index f0609432..96874878 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -81,9 +81,10 @@ clauses (grammar: standards `1-formats/deed/spec/abnf/deed.abnf`; lint with - `hypatia_rules_praxis.deed` - the A5 rule registry, generated by `scripts/gen-rules-praxis.sh` - `docs/history/A2ML-REMOVED.adoc` - each removed `.a2ml` file, its git blob id, and where its content went +- `audits/assail-classifications_praxis.deed` - panic-attack's user-classification registry + (audited findings it flips to suppressed), read deed-first by panic-attack -Two `.a2ml` files remain, each for a reader outside this repo (see the ledger): -`audits/assail-classifications.a2ml` (panic-attack reads only that name) and +One `.a2ml` file remains, for a reader outside this repo (see the ledger): `test/fixtures/a2ml/rsr-criteria-v2.a2ml` (a copy of the standards RSR criteria, still A2ML). The rules that *detect* `.a2ml` in scanned repos, and the shared readers that fall back to it (`RsrConformance`, `RsrCriteria`, `RuleLoader`), are deliberate. diff --git a/.github/workflows/dogfood-gate.yml b/.github/workflows/dogfood-gate.yml index 9539469e..a242e22e 100644 --- a/.github/workflows/dogfood-gate.yml +++ b/.github/workflows/dogfood-gate.yml @@ -35,11 +35,7 @@ jobs: - name: Check for A2ML and DEED files id: detect run: | - # audits/assail-classifications.a2ml is panic-attack's user-classification - # registry — an S-expression dialect by that tool's spec (see panic-attack - # CLAUDE.md), not the TOML-like manifest A2ML this gate validates. Exclude - # it rather than feeding it to a validator for a different dialect. - COUNT=$(find . -type f \( -name '*.a2ml' -o -name '*.deed' \) -not -path './.git/*' -not -name 'assail-classifications.a2ml' -printf '.' | wc -c) + COUNT=$(find . -type f \( -name '*.a2ml' -o -name '*.deed' \) -not -path './.git/*' -printf '.' | wc -c) echo "count=$COUNT" >> "$GITHUB_OUTPUT" if [ "$COUNT" -eq 0 ]; then echo "::warning::No .a2ml/.deed manifest files found. Every RSR repo should have a repo deed (_chora.deed); legacy 0-AI-MANIFEST.a2ml accepted mid-migration — standards #837" @@ -52,9 +48,7 @@ jobs: path: '.' strict: 'false' # Re-state the action's default carve-outs (a custom value REPLACES - # the default list), plus panic-attack's user-classification - # registry: that file is an S-expression dialect by panic-attack's - # spec, not the TOML-like manifest A2ML this action validates. + # the default list). paths-ignore: | vendor/ vendored/ @@ -63,7 +57,6 @@ jobs: integration/fixtures/ test/fixtures/ tests/fixtures/ - assail-classifications.a2ml - name: Write summary run: | diff --git a/audits/assail-classifications.a2ml b/audits/assail-classifications.a2ml deleted file mode 100644 index eba4c4e6..00000000 --- a/audits/assail-classifications.a2ml +++ /dev/null @@ -1,102 +0,0 @@ -;; SPDX-License-Identifier: MPL-2.0 -;; Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -;; assail-classifications.a2ml — audited panic-attack findings for hypatia. -;; -;; Read by panic-attack >= 2.5.5 (load_user_classifications): findings -;; matching (file, category) are flipped to suppressed = true AFTER the -;; structural kanren suppression pass. Entries here are AUDITED-SOUND -;; residuals, not exemptions of convenience — every entry must cite its -;; rationale, and the registry lives apart from the source so a code -;; edit cannot self-suppress (see panic-attack CLAUDE.md, User- -;; Classification Registry). -;; -;; Audit trail: 2026-06-11 estate-loop session — fresh panic-attack -;; 2.5.5 scan of hypatia; every entry below was inspected at source. - -(assail-classifications - ;; ── Soundness-gate negative fixtures ───────────────────────────── - ;; test/soundness/fixtures/code_safety/ exists to PROVE the scanner - ;; catches these constructs; the findings are the fixtures working - ;; as designed. Mirrors lib/hypatia/scanner_suppression.ex, which - ;; already exempts these paths for hypatia's own scanner. - (classification - (file "test/soundness/fixtures/code_safety/transmute.rs") - (category "UnsafeCode") - (audit "test/soundness — deliberate negative fixture") - (rationale "fixture asserting the scanner detects mem::transmute")) - (classification - (file "test/soundness/fixtures/code_safety/admitted.v") - (category "ProofDrift") - (audit "test/soundness — deliberate negative fixture") - (rationale "fixture asserting the scanner detects Admitted")) - (classification - (file "test/soundness/fixtures/code_safety/believe_me.idr") - (category "ProofDrift") - (audit "test/soundness — deliberate negative fixture") - (rationale "fixture asserting the scanner detects believe_me")) - (classification - (file "test/soundness/fixtures/code_safety/sorry.lean") - (category "ProofDrift") - (audit "test/soundness — deliberate negative fixture") - (rationale "fixture asserting the scanner detects sorry")) - (classification - (file "test/soundness/fixtures/code_safety/obj_magic_ocaml.ml") - (category "UnsafeTypeCoercion") - (audit "test/soundness — deliberate negative fixture") - (rationale "fixture asserting the scanner detects Obj.magic")) - (classification - (file "test/soundness/fixtures/code_safety/unsafe_coerce.hs") - (category "UnsafeTypeCoercion") - (audit "test/soundness — deliberate negative fixture") - (rationale "fixture asserting the scanner detects unsafeCoerce")) - (classification - (file "test/soundness/fixtures/code_safety/elixir_code_eval.ex") - (category "DynamicCodeExecution") - (audit "test/soundness — deliberate negative fixture") - (rationale "fixture asserting the scanner detects Code.eval_string")) - (classification - (file "test/soundness/fixtures/code_safety/zig_ptr_cast.zig") - (category "UnsafeCode") - (audit "test/soundness — deliberate negative fixture") - (rationale "fixture asserting the scanner detects Zig pointer casts")) - - ;; ── Remediation scripts: pattern strings, not vulnerabilities ──── - (classification - (file "scripts/fix-scripts/fix-deno-permissions.sh") - (category "ExcessivePermissions") - (audit "remediation tool — replaces `deno -A` with scoped permission flags; scripts/fix-scripts/ is already exempt in scanner_suppression.ex") - (rationale "contains -A as the SEARCH pattern it removes from other repos")) - - ;; ── FFI boundary unsafe: documented, load-bearing ──────────────── - (classification - (file "clients/rust/hypatia-client/src/ffi.rs") - (category "UnsafeCode") - (audit "in-file # Safety section (ffi.rs:7-30) enumerates the invariant for every unsafe block; carries hypatia allow pragmas") - (rationale "libloading C-ABI boundary calls against libhypatia_ffi.so; each block's invariant documented at source")) - - ;; ── Test harnesses ─────────────────────────────────────────────── - (classification - (file "tests/e2e.sh") - (category "CommandInjection") - (audit "tests/e2e.sh:88-93 — heredoc writes a deliberately insecure fixture") - (rationale "the eval is fixture CONTENT generated for the scanner-detection test, not executed by the harness")) - (classification - (file "integration/run-tests.sh") - (category "HardcodedSecret") - (audit "integration/run-tests.sh:268 — ARANGODB_PASSWORD=testpassword") - (rationale "throwaway credential for the ephemeral integration-test database container")) - - ;; ── Env-var binding misread as a secret ────────────────────────── - (classification - (file "hooks/lib/cache.sh") - (category "HardcodedSecret") - (audit "hooks/lib/cache.sh:17-22 — CICD_CACHE_PASSWORD=\"${CICD_CACHE_PASSWORD:-}\"") - (rationale "empty-default env-var binding, documented in-file; no literal secret present")) - - ;; ── Rule definitions detecting themselves ──────────────────────── - (classification - (file "lib/hypatia/scanner_suppression.ex") - (category "HardcodedSecret") - (audit "scanner suppression rule definitions contain secret-shaped pattern strings") - (rationale "detector/suppression pattern table, not credentials — same class as the scripts/fix-* carve-out in scanner_suppression.ex")) -) diff --git a/audits/assail-classifications_praxis.deed b/audits/assail-classifications_praxis.deed new file mode 100644 index 00000000..02854916 --- /dev/null +++ b/audits/assail-classifications_praxis.deed @@ -0,0 +1,112 @@ +;; SPDX-License-Identifier: MPL-2.0 +;; SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) +;; +;; assail-classifications_praxis.deed — audited panic-attack findings for +;; hypatia. Translated entry for entry from audits/assail-classifications.a2ml +;; (removed; see docs/history/A2ML-REMOVED.adoc): (file "…") is :file, +;; (category "…") is the symbol :category, (audit "…") is :audit and +;; (rationale "…") is :rationale. Nothing was added or dropped. +;; +;; Read by panic-attack's deed-first registry reader (load_user_classifications, +;; src/assail/classifications.rs): findings matching (:file, :category) are +;; flipped to suppressed = true AFTER the structural kanren suppression pass. +;; A malformed file fails the scan; it is never read as an empty registry. +;; Entries here are AUDITED-SOUND residuals, not exemptions of convenience: +;; every entry must cite its rationale, and the registry lives apart from the +;; source so a code edit cannot self-suppress (see panic-attack CLAUDE.md, +;; User-Classification Registry). +;; +;; Audit trail: 2026-06-11 estate-loop session — fresh panic-attack +;; 2.5.5 scan of hypatia; every entry below was inspected at source. +(praxis-deed + :schema-version "1.0.0" + :canonical-name "hypatia-assail-classifications" + :beholding-chora #uuid"0889b37b-defb-831f-973c-e119500db00e" + :profile assail-classifications + + ;; ── Soundness-gate negative fixtures ───────────────────────────── + ;; test/soundness/fixtures/code_safety/ exists to PROVE the scanner + ;; catches these constructs; the findings are the fixtures working + ;; as designed. Mirrors lib/hypatia/scanner_suppression.ex, which + ;; already exempts these paths for hypatia's own scanner. + (classification + :file "test/soundness/fixtures/code_safety/transmute.rs" + :category UnsafeCode + :audit "test/soundness — deliberate negative fixture" + :rationale "fixture asserting the scanner detects mem::transmute") + (classification + :file "test/soundness/fixtures/code_safety/admitted.v" + :category ProofDrift + :audit "test/soundness — deliberate negative fixture" + :rationale "fixture asserting the scanner detects Admitted") + (classification + :file "test/soundness/fixtures/code_safety/believe_me.idr" + :category ProofDrift + :audit "test/soundness — deliberate negative fixture" + :rationale "fixture asserting the scanner detects believe_me") + (classification + :file "test/soundness/fixtures/code_safety/sorry.lean" + :category ProofDrift + :audit "test/soundness — deliberate negative fixture" + :rationale "fixture asserting the scanner detects sorry") + (classification + :file "test/soundness/fixtures/code_safety/obj_magic_ocaml.ml" + :category UnsafeTypeCoercion + :audit "test/soundness — deliberate negative fixture" + :rationale "fixture asserting the scanner detects Obj.magic") + (classification + :file "test/soundness/fixtures/code_safety/unsafe_coerce.hs" + :category UnsafeTypeCoercion + :audit "test/soundness — deliberate negative fixture" + :rationale "fixture asserting the scanner detects unsafeCoerce") + (classification + :file "test/soundness/fixtures/code_safety/elixir_code_eval.ex" + :category DynamicCodeExecution + :audit "test/soundness — deliberate negative fixture" + :rationale "fixture asserting the scanner detects Code.eval_string") + (classification + :file "test/soundness/fixtures/code_safety/zig_ptr_cast.zig" + :category UnsafeCode + :audit "test/soundness — deliberate negative fixture" + :rationale "fixture asserting the scanner detects Zig pointer casts") + + ;; ── Remediation scripts: pattern strings, not vulnerabilities ──── + (classification + :file "scripts/fix-scripts/fix-deno-permissions.sh" + :category ExcessivePermissions + :audit "remediation tool — replaces `deno -A` with scoped permission flags; scripts/fix-scripts/ is already exempt in scanner_suppression.ex" + :rationale "contains -A as the SEARCH pattern it removes from other repos") + + ;; ── FFI boundary unsafe: documented, load-bearing ──────────────── + (classification + :file "clients/rust/hypatia-client/src/ffi.rs" + :category UnsafeCode + :audit "in-file # Safety section (ffi.rs:7-30) enumerates the invariant for every unsafe block; carries hypatia allow pragmas" + :rationale "libloading C-ABI boundary calls against libhypatia_ffi.so; each block's invariant documented at source") + + ;; ── Test harnesses ─────────────────────────────────────────────── + (classification + :file "tests/e2e.sh" + :category CommandInjection + :audit "tests/e2e.sh:88-93 — heredoc writes a deliberately insecure fixture" + :rationale "the eval is fixture CONTENT generated for the scanner-detection test, not executed by the harness") + (classification + :file "integration/run-tests.sh" + :category HardcodedSecret + :audit "integration/run-tests.sh:268 — ARANGODB_PASSWORD=testpassword" + :rationale "throwaway credential for the ephemeral integration-test database container") + + ;; ── Env-var binding misread as a secret ────────────────────────── + (classification + :file "hooks/lib/cache.sh" + :category HardcodedSecret + :audit "hooks/lib/cache.sh:17-22 — CICD_CACHE_PASSWORD=\"${CICD_CACHE_PASSWORD:-}\"" + :rationale "empty-default env-var binding, documented in-file; no literal secret present") + + ;; ── Rule definitions detecting themselves ──────────────────────── + (classification + :file "lib/hypatia/scanner_suppression.ex" + :category HardcodedSecret + :audit "scanner suppression rule definitions contain secret-shaped pattern strings" + :rationale "detector/suppression pattern table, not credentials — same class as the scripts/fix-* carve-out in scanner_suppression.ex") +) diff --git a/docs/history/A2ML-REMOVED.adoc b/docs/history/A2ML-REMOVED.adoc index 225d1f5b..ccba49a4 100644 --- a/docs/history/A2ML-REMOVED.adoc +++ b/docs/history/A2ML-REMOVED.adoc @@ -223,24 +223,24 @@ Size is in bytes. The sha256 is of the file as it was tracked. | RuleLoader fixture (HYP-S007). | Inlined into `test/rules/rule_loader_test.exs`. +| `audits/assail-classifications.a2ml` +| 5623 +| `7d9c7b14419f6a597a9be87e5828ee7aff53648d5edc1175204494205d1bcb24` +| `eba4c4e6c4ed29dbbc7e1c9ca733f91e54e114f7` +| panic-attack's user-classification registry: 14 audited findings (file, category, audit, rationale) that panic-attack flips to suppressed. Removed later than the rest (it was retained until panic-attack had a deed reader); last held at `7d1059aa`. +| `audits/assail-classifications_praxis.deed`, entry for entry, all 14 kept: `(file …)`, `(audit …)` and `(rationale …)` became the `:file`, `:audit` and `:rationale` fields and `(category "…")` the symbol `:category`. No mapping spec covers it; its reader is panic-attack's deed-first `load_user_classifications`, which reads this name before the legacy A2ML ones. + |=== == Retained, with the reason -Two `.a2ml` files stay, each because a live reader outside this repository's -control still needs exactly that input. Neither has a deed form to move to. +One `.a2ml` file stays, because a live reader outside this repository's +control still needs exactly that input, and it has no deed form to move to. [cols="3,5",options="header"] |=== | Path | Why it stays -| `audits/assail-classifications.a2ml` -| panic-attack (>= 2.5.5, `load_user_classifications` in its -`src/assail/mod.rs`) reads only `audits/assail-classifications.a2ml` or -`.panic-attack-classifications.a2ml`. No mapping spec covers it and -panic-attack has no deed reader, so deleting it would unsuppress the audited -findings it records. It goes when panic-attack reads a deed form first. - | `test/fixtures/a2ml/rsr-criteria-v2.a2ml` | A dogfood copy of the RSR v2.0 criteria, whose canon (`0-canon/rsr/rsr-criteria-v2.a2ml` in standards) is still A2ML: A7 section diff --git a/test/dogfood_manifest_detection_test.rb b/test/dogfood_manifest_detection_test.rb index 23eefc44..37e7b3d3 100644 --- a/test/dogfood_manifest_detection_test.rb +++ b/test/dogfood_manifest_detection_test.rb @@ -11,7 +11,8 @@ [['manifest.deed'], 1], [['manifest.a2ml'], 1], [["line\nbreak.deed", 'legacy.a2ml'], 2], - [['.git/ignored.deed', 'audits/assail-classifications.a2ml'], 0] + [['.git/ignored.deed'], 0], + [['audits/assail-classifications_praxis.deed'], 1] ].each do |files, expected| Dir.mktmpdir('dogfood-detect-') do |dir| files.each do |file| @@ -25,4 +26,4 @@ abort "wrong candidate count for #{files.inspect}" unless File.read(output) == "count=#{expected}\n" end end -puts 'PASS: empty, DEED-only, A2ML-only, mixed, newline filenames, and excluded manifests' +puts 'PASS: empty, DEED-only, A2ML-only, mixed, newline filenames, .git excluded, classification deed counted' From f87fd9da658abf287d2a78cd68da7fad99d9127e Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 14 Nov 2026 19:11:56 +0000 Subject: [PATCH 09/10] docs(a2ml ledger): name panic-attack's assail module, not a path hypatia lacks Hypatia's structural_drift rule SD022 reads a backticked path as a path in this tree. src/assail/ is panic-attack's, so the ledger now names the module and the repository instead. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_0136P7ZoBy5xGnGDLk7wQ8jC --- docs/history/A2ML-REMOVED.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/history/A2ML-REMOVED.adoc b/docs/history/A2ML-REMOVED.adoc index 225d1f5b..348da473 100644 --- a/docs/history/A2ML-REMOVED.adoc +++ b/docs/history/A2ML-REMOVED.adoc @@ -235,8 +235,8 @@ control still needs exactly that input. Neither has a deed form to move to. | Path | Why it stays | `audits/assail-classifications.a2ml` -| panic-attack (>= 2.5.5, `load_user_classifications` in its -`src/assail/mod.rs`) reads only `audits/assail-classifications.a2ml` or +| panic-attack (>= 2.5.5, `load_user_classifications` in its assail module, +in the panic-attack repository) reads only `audits/assail-classifications.a2ml` or `.panic-attack-classifications.a2ml`. No mapping spec covers it and panic-attack has no deed reader, so deleting it would unsuppress the audited findings it records. It goes when panic-attack reads a deed form first. From c117f6d5d3950022afef19c010bbf5a94608d793 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 14 Nov 2026 23:59:42 +0000 Subject: [PATCH 10/10] ci(estate-rescan): pin panic-attack at cbf2b93, the deed-first classification reader Part of the lane-wide scanner pin move for #1118: standards b2aaeb0 (#1585) already defaults panic-ref to this commit. Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_0136P7ZmSuTPtG4zjRCN2UaY --- .github/workflows/estate-rescan.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/estate-rescan.yml b/.github/workflows/estate-rescan.yml index 5f44785c..0c69e937 100644 --- a/.github/workflows/estate-rescan.yml +++ b/.github/workflows/estate-rescan.yml @@ -130,7 +130,7 @@ jobs: # Kept equal to the standards Hypatia lane (hypatia-scan-reusable.yml # panic-ref) and every other lane; owner ruling 2026-11-13. Check with # `mix hypatia.ci_triage pins` (scanner_pin_drift, hypatia#1064). - PA_SHA: 410a8f821ea8297833162565b50a298f787815da + PA_SHA: cbf2b935ef4260cc3ae66010f4ffc91385ff8f8c steps: - name: Cache built panic-attack