diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index eb560f6a..90b17cfb 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -69,14 +69,25 @@ 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)`, `(anchor)` (semantic authority), + `(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/.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/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/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/.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/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/.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/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/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/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/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..9f80fad6 --- /dev/null +++ b/docs/history/A2ML-REMOVED.adoc @@ -0,0 +1,251 @@ +// 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. +| The `(anchor)` clause of `hypatia_chora.deed`, under A7 6.4 (`anchor.abnf` v2.0.0, `:schema "hyperpolymath.anchor/2"`): `version` to `(metadata :version "1.0.0")`. The source had no `authority`, which the clause requires and a translator never invents; the owner supplied it on 2026-11-14: boj-server, written as its chora id `6c7f9305-2a47-8f96-a1ed-bd0940e4d4e6` (boj-server_chora.deed `:repo-uuid #u8"gv-clade-index:github.com/hyperpolymath/boj-server"`, the registry's `uuid_v8` for that repo). Dropped under 6.4: the reverse-DNS id, clade and status. Not translated: the SSG config, which belongs to `META.deed` (J29), and the parent, which belongs to `ECOSYSTEM.deed` `(related :uuid … :relationship parent)` (J26); neither module is adopted here yet. + +| `.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. + +| `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 + +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 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. + +| `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/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 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/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/hypatia_chora.deed b/hypatia_chora.deed index 887a25bd..23dde955 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,90 @@ :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)) + ; ANCHOR.a2ml under A7 6.4 (anchor.abnf v2.0.0): its version is + ; (metadata :version). The source had no authority, which a translator + ; never invents; the owner supplied it on 2026-11-14: boj-server, written + ; as boj-server's chora id. That id is boj-server_chora.deed's :repo-uuid + ; #u8"gv-clade-index:github.com/hyperpolymath/boj-server" (a pre-V9 id, + ; kept in its gv-clade-index domain), and the registry records the same + ; uuid_v8 for hyperpolymath/boj-server. Dropped under 6.4: the reverse-DNS + ; id, clade and status. Not adopted here: the ssg block (META.deed, J29) + ; and the parents list (ECOSYSTEM.deed (related … :relationship parent), + ; J26). + (anchor + :schema "hyperpolymath.anchor/2" + :authority "6c7f9305-2a47-8f96-a1ed-bd0940e4d4e6" + (metadata :version "1.0.0")) (egress :policy "standards ADR-009" (job 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/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/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/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/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/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 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 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. -- 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 "$@" 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.