diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index a628bbb..ce5e768 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -96,7 +96,7 @@ Both are FOSS with independent governance (no Big Tech). ### Package Management - **Primary**: Guix (guix.scm) -- **Fallback**: Nix (flake.nix) +- **Fallback**: Guix (flake.guix) - **JS deps**: Deno (deno.json imports) ### Security Requirements diff --git a/.github/dependabot.yml b/.github/dependabot.yml index a210af4..940b2d0 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -13,7 +13,7 @@ updates: directory: "/" schedule: interval: "weekly" - - package-ecosystem: "nix" + - package-ecosystem: "guix" directory: "/" schedule: interval: "weekly" diff --git a/.machine_readable/contractiles/Justfile b/.machine_readable/contractiles/Justfile index 5fad4f1..ce5e743 100644 --- a/.machine_readable/contractiles/Justfile +++ b/.machine_readable/contractiles/Justfile @@ -1,4 +1,4 @@ -# feedback-a-tron - Nix Development Tasks +# feedback-a-tron - Guix Development Tasks set shell := ["bash", "-uc"] set dotenv-load := true @@ -10,35 +10,35 @@ project := "feedback-a-tron" default: @just --list --unsorted -# Build with nix +# Build with guix build: - nix build + guix build # Build and show output path build-show: - nix build --print-out-paths + guix build --print-out-paths # Enter dev shell develop: - nix develop + guix develop # Check flake check: - nix flake check + guix flake check # Update flake inputs update: - nix flake update + guix flake update # Show flake info info: - nix flake info + guix flake info -# Format nix files +# Format guix files fmt: - nixfmt *.nix || nix fmt + nixfmt *.guix || guix fmt -# Run nix linter +# Run guix linter lint: statix check . || true @@ -48,7 +48,7 @@ clean: # Show derivation show-drv: - nix derivation show + guix derivation show # All checks before commit pre-commit: check diff --git a/ABI-FFI-README.adoc b/ABI-FFI-README.adoc new file mode 100644 index 0000000..e78b6d5 --- /dev/null +++ b/ABI-FFI-README.adoc @@ -0,0 +1,178 @@ +== feedback-o-tron ABI/FFI Documentation + +This file describes what actually exists, honestly. Three layers, three +different maturity levels: + +[width="100%",cols="34%,33%,33%",options="header",] +|=== +|Layer |Path |Status +|Verified contract spec (Idris2) |`+src/abi/FeedbackOTron/Contract.idr+` +|*REAL* — compiles, proofs machine-checked, CI-gated + +|Runtime implementation (Elixir) +|`+elixir-mcp/lib/feedback_a_tron/synthesis/form_validator.ex+` |*REAL* +— the validator on the live dispatch path + +|C-ABI FFI (Zig) |`+ffi/zig/src/main.zig+` |*STUB* — scaffolding only, +not wired to anything +|=== + +=== 1. The verified contract spec (Idris2) — REAL + +`+src/abi/FeedbackOTron/Contract.idr+` (package +`+src/abi/feedback-o-tron.ipkg+`, depends on `+base+` only) states the +form-validation contract once, totally, and proves that its `+validate+` +function enforces it. It is type-checked in CI by +`+.github/workflows/proofs.yml+` on every push/PR touching +`+src/abi/**+`, under pinned Idris2 0.7.0. + +The model: + +* `+Field+` — `+fieldId+`, `+label+`, `+required : Bool+`, +`+options : List String+`, `+fieldKind+` +(`+Input | Textarea | Dropdown | Checkboxes | Markdown+`) +* `+Form+` — a list of `+Field+`s +* `+Answers+` — `+List (String, String)+` (field id ↦ answer text) +* `+Violation+` — +`+RequiredMissing fieldId | UnknownField key | InvalidOption fieldId value+` +* `+validate : Form -> Answers -> Either (List Violation) ValidPayload+` + +The central safety device is `+ValidPayload+`: its data constructor is +*private* (the type is `+export+`, the constructor is not), so the only +way to obtain a `+ValidPayload+` is to get `+validate+` to say +`+Right+`. Holding one is machine-checked evidence the gate passed. +`+getAnswers : ValidPayload -> Answers+` reads the validated answers +back out. + +==== Proved lemmas (no `+believe_me+`, no `+postulate+`, no `+assert_total+`) + +Everything is `+%default total+`; the trusted base is *empty* and CI +enforces that with a source audit (`+trusted-base+` job in +`+proofs.yml+`). + +[width="100%",cols="50%,50%",options="header",] +|=== +|Lemma |Statement +|`+validCompleteness+` |`+IsRight (validate f a)+` → +`+AllRequiredAnswered f a+` (Bool-reflection: +`+allRequiredAnswered f a = True+`) — a successful validate means every +required non-markdown field was answered + +|`+validNoUnknownFields+` |`+IsRight (validate f a)+` → +`+noUnknownFields f a = True+` — no answer key outside the form’s +non-markdown field ids + +|`+validOptionsValid+` |`+IsRight (validate f a)+` → +`+allOptionsValid f a = True+` — every dropdown answer is one of its +field’s options + +|`+validGate+` |`+IsRight (validate f a)+` → `+checksPass f a = True+` +(the master gate; the three above are its `+&&+`-eliminations) + +|`+checksPassValidates+` |converse: `+checksPass f a = True+` → +`+IsRight (validate f a)+` — validate is pinned to the boolean spec in +both directions + +|`+validateAnswersPreserved+` |`+validate f a = Right vp+` → +`+getAnswers vp = a+` — validate never invents or drops answers + +|`+emptyFormEmptyAnswersOk+` |sanity witness: the empty form with no +answers validates +|=== + +The proofs are deliberately by-inspection: `+validate+` is _defined via_ +the boolean reflection +(`+validateGo (checksPass f a) (violations f a) a+`), so the lemmas +follow by case analysis and `+&&+`-elimination, not heroics. + +Check locally: + +[source,bash] +---- +cd src/abi +idris2 --typecheck feedback-o-tron.ipkg +---- + +=== 2. The runtime implementation (Elixir) — REAL + +`+FeedbackATron.Synthesis.FormValidator.validate/2+` is the runtime +implementation of the same contract, on the live synthesis/dispatch +path. The correspondence, field by field: + +[width="100%",cols="34%,33%,33%",options="header",] +|=== +|Contract (Idris2) |Runtime (Elixir) |Meaning +|`+RequiredMissing fieldId+` |`+%{error: :required_missing}+` |a +required field is unanswered (Elixir also treats a whitespace-only +answer, or an empty checkbox list, as missing) + +|`+UnknownField key+` |`+%{error: :unknown_field}+` |an answer key that +is not a non-markdown field id of the form + +|`+InvalidOption fieldId value+` |`+%{error: :invalid_option}+` |a +dropdown answer that is not one of the field’s declared options + +|— (unrepresentable: `+Answers+` is typed `+List (String, String)+`) +|`+%{error: :not_a_string}+` |a non-string answer value; the Idris +contract rules this out by type, the dynamically-typed runtime must +check it + +|markdown fields excluded from `+knownFields+` |markdown fields rejected +from `+known_fields+`, answers to them are `+:unknown_field+` |markdown +blocks are display-only + +|`+Left+` collects *all* violations (required first in form order, then +options, then unknown keys) |`+{:error, errors}+` collects all +violations (form-order field errors, then sorted unknown keys) |nothing +fails fast; the caller sees the whole picture + +|`+Right ValidPayload+` (private constructor) |`+:ok+` |gate passed +|=== + +Divergences to know about (deliberate, documented rather than hidden): + +* The Elixir validator trims whitespace before deciding blankness; the +Idris spec models blankness as `+v /= ""+` without trimming. +* Checkbox answers are lists in Elixir; the Idris spec models all +answers as strings, so checkbox-list type checks live only in the +runtime. +* Nothing _mechanically_ connects the two today — the Elixir module +mirrors the spec by construction and code review, not by extraction. See +§4. + +=== 3. The Zig FFI — STUB + +`+ffi/zig/src/main.zig+` is *scaffolding, not a working FFI*. It exports +generic `+feedback_o_tron_init/free/process+`-style lifecycle functions +and refers in comments to `+src/abi/Types.idr+` and +`+src/abi/Foreign.idr+`, which *do not exist* — the real Idris module is +`+FeedbackOTron/Contract.idr+` and no C headers are generated from it. +Nothing in the running system calls this library. It is kept as the +intended shape of a future C-ABI surface and must not be described as +functional until it is. + +=== 4. What full enforcement would look like (not built yet) + +The honest end state is an Idris-derived validator on the dispatch path +— either code generated from `+Contract.idr+` (via a C library that the +Zig FFI wraps and Elixir calls through a NIF/port), or a conformance +test suite generated from the spec that the Elixir validator must pass +in CI. Until then, the guarantee chain is: spec proved (Idris, CI-gated) +→ implementation mirrors spec (review + unit tests). Full FFI +enforcement is tracked in a follow-up issue: (follow-up issue: filed at +PR time). + +=== License + +* Code: MPL-2.0 +* This document: CC-BY-SA-4.0 + +=== See Also + +* `+src/abi/FeedbackOTron/Contract.idr+` — the contract, with per-lemma +docs +* `+.github/workflows/proofs.yml+` — the CI gate (type-check + +trusted-base audit) +* `+elixir-mcp/lib/feedback_a_tron/synthesis/form_validator.ex+` — the +runtime validator +* https://idris2.readthedocs.io[Idris2 documentation] diff --git a/ABI-FFI-README.md b/ABI-FFI-README.md deleted file mode 100644 index 111a6ab..0000000 --- a/ABI-FFI-README.md +++ /dev/null @@ -1,121 +0,0 @@ - - -# feedback-o-tron ABI/FFI Documentation - -This file describes what actually exists, honestly. Three layers, three -different maturity levels: - -| Layer | Path | Status | -|---|---|---| -| Verified contract spec (Idris2) | `src/abi/FeedbackOTron/Contract.idr` | **REAL** — compiles, proofs machine-checked, CI-gated | -| Runtime implementation (Elixir) | `elixir-mcp/lib/feedback_a_tron/synthesis/form_validator.ex` | **REAL** — the validator on the live dispatch path | -| C-ABI FFI (Zig) | `ffi/zig/src/main.zig` | **STUB** — scaffolding only, not wired to anything | - -## 1. The verified contract spec (Idris2) — REAL - -`src/abi/FeedbackOTron/Contract.idr` (package `src/abi/feedback-o-tron.ipkg`, -depends on `base` only) states the form-validation contract once, totally, -and proves that its `validate` function enforces it. It is type-checked in -CI by `.github/workflows/proofs.yml` on every push/PR touching `src/abi/**`, -under pinned Idris2 0.7.0. - -The model: - -- `Field` — `fieldId`, `label`, `required : Bool`, `options : List String`, - `fieldKind` (`Input | Textarea | Dropdown | Checkboxes | Markdown`) -- `Form` — a list of `Field`s -- `Answers` — `List (String, String)` (field id ↦ answer text) -- `Violation` — `RequiredMissing fieldId | UnknownField key | InvalidOption fieldId value` -- `validate : Form -> Answers -> Either (List Violation) ValidPayload` - -The central safety device is `ValidPayload`: its data constructor is -**private** (the type is `export`, the constructor is not), so the only way -to obtain a `ValidPayload` is to get `validate` to say `Right`. Holding one -is machine-checked evidence the gate passed. `getAnswers : ValidPayload -> -Answers` reads the validated answers back out. - -### Proved lemmas (no `believe_me`, no `postulate`, no `assert_total`) - -Everything is `%default total`; the trusted base is **empty** and CI enforces -that with a source audit (`trusted-base` job in `proofs.yml`). - -| Lemma | Statement | -|---|---| -| `validCompleteness` | `IsRight (validate f a)` → `AllRequiredAnswered f a` (Bool-reflection: `allRequiredAnswered f a = True`) — a successful validate means every required non-markdown field was answered | -| `validNoUnknownFields` | `IsRight (validate f a)` → `noUnknownFields f a = True` — no answer key outside the form's non-markdown field ids | -| `validOptionsValid` | `IsRight (validate f a)` → `allOptionsValid f a = True` — every dropdown answer is one of its field's options | -| `validGate` | `IsRight (validate f a)` → `checksPass f a = True` (the master gate; the three above are its `&&`-eliminations) | -| `checksPassValidates` | converse: `checksPass f a = True` → `IsRight (validate f a)` — validate is pinned to the boolean spec in both directions | -| `validateAnswersPreserved` | `validate f a = Right vp` → `getAnswers vp = a` — validate never invents or drops answers | -| `emptyFormEmptyAnswersOk` | sanity witness: the empty form with no answers validates | - -The proofs are deliberately by-inspection: `validate` is *defined via* the -boolean reflection (`validateGo (checksPass f a) (violations f a) a`), so the -lemmas follow by case analysis and `&&`-elimination, not heroics. - -Check locally: - -```bash -cd src/abi -idris2 --typecheck feedback-o-tron.ipkg -``` - -## 2. The runtime implementation (Elixir) — REAL - -`FeedbackATron.Synthesis.FormValidator.validate/2` is the runtime -implementation of the same contract, on the live synthesis/dispatch path. -The correspondence, field by field: - -| Contract (Idris2) | Runtime (Elixir) | Meaning | -|---|---|---| -| `RequiredMissing fieldId` | `%{error: :required_missing}` | a required field is unanswered (Elixir also treats a whitespace-only answer, or an empty checkbox list, as missing) | -| `UnknownField key` | `%{error: :unknown_field}` | an answer key that is not a non-markdown field id of the form | -| `InvalidOption fieldId value` | `%{error: :invalid_option}` | a dropdown answer that is not one of the field's declared options | -| — (unrepresentable: `Answers` is typed `List (String, String)`) | `%{error: :not_a_string}` | a non-string answer value; the Idris contract rules this out by type, the dynamically-typed runtime must check it | -| markdown fields excluded from `knownFields` | markdown fields rejected from `known_fields`, answers to them are `:unknown_field` | markdown blocks are display-only | -| `Left` collects **all** violations (required first in form order, then options, then unknown keys) | `{:error, errors}` collects all violations (form-order field errors, then sorted unknown keys) | nothing fails fast; the caller sees the whole picture | -| `Right ValidPayload` (private constructor) | `:ok` | gate passed | - -Divergences to know about (deliberate, documented rather than hidden): - -- The Elixir validator trims whitespace before deciding blankness; the Idris - spec models blankness as `v /= ""` without trimming. -- Checkbox answers are lists in Elixir; the Idris spec models all answers as - strings, so checkbox-list type checks live only in the runtime. -- Nothing *mechanically* connects the two today — the Elixir module mirrors - the spec by construction and code review, not by extraction. See §4. - -## 3. The Zig FFI — STUB - -`ffi/zig/src/main.zig` is **scaffolding, not a working FFI**. It exports -generic `feedback_o_tron_init/free/process`-style lifecycle functions and -refers in comments to `src/abi/Types.idr` and `src/abi/Foreign.idr`, which -**do not exist** — the real Idris module is `FeedbackOTron/Contract.idr` and -no C headers are generated from it. Nothing in the running system calls this -library. It is kept as the intended shape of a future C-ABI surface and must -not be described as functional until it is. - -## 4. What full enforcement would look like (not built yet) - -The honest end state is an Idris-derived validator on the dispatch path — -either code generated from `Contract.idr` (via a C library that the Zig FFI -wraps and Elixir calls through a NIF/port), or a conformance test suite -generated from the spec that the Elixir validator must pass in CI. Until -then, the guarantee chain is: spec proved (Idris, CI-gated) → implementation -mirrors spec (review + unit tests). Full FFI enforcement is tracked in a -follow-up issue: (follow-up issue: filed at PR time). - -## License - -- Code: MPL-2.0 -- This document: CC-BY-SA-4.0 - -## See Also - -- `src/abi/FeedbackOTron/Contract.idr` — the contract, with per-lemma docs -- `.github/workflows/proofs.yml` — the CI gate (type-check + trusted-base audit) -- `elixir-mcp/lib/feedback_a_tron/synthesis/form_validator.ex` — the runtime validator -- [Idris2 documentation](https://idris2.readthedocs.io) diff --git a/ARCHITECTURE.adoc b/ARCHITECTURE.adoc new file mode 100644 index 0000000..1c0a7a6 --- /dev/null +++ b/ARCHITECTURE.adoc @@ -0,0 +1,48 @@ +== Architecture + +=== Overview + +This repository follows a modular, maintainable architecture designed +for clarity, scalability, and long-term sustainability. + +=== Directory Structure + +.... +. +├── src/ # Source code +├── tests/ # Test suites +├── docs/ # Documentation +├── scripts/ # Utility scripts +├── config/ # Configuration files +├── LICENSE # License file +├── LICENSES/ # Full license texts +└── README.adoc # Project documentation +.... + +=== Design Principles + +* *Separation of Concerns*: Each module has a single responsibility +* *Testability*: Code is written to be easily testable +* *Documentation*: All public APIs are documented +* *Configuration*: Environment-specific settings are externalized + +=== Dependencies + +* External dependencies are minimized and clearly declared +* Version pinning is used for reproducibility + +=== Security Considerations + +* Sensitive data is never committed to the repository +* Secrets are managed through environment variables or secure vaults +* Regular dependency audits are performed + +=== Maintainability + +* Code follows consistent style guidelines +* Pull requests require review and CI checks +* Issues and discussions are tracked transparently + +''''' + +_Last updated: 2026-07-18_ diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md deleted file mode 100644 index 607e3d8..0000000 --- a/ARCHITECTURE.md +++ /dev/null @@ -1,47 +0,0 @@ -# Architecture - -## Overview - -This repository follows a modular, maintainable architecture designed for clarity, scalability, and long-term sustainability. - -## Directory Structure - -``` -. -├── src/ # Source code -├── tests/ # Test suites -├── docs/ # Documentation -├── scripts/ # Utility scripts -├── config/ # Configuration files -├── LICENSE # License file -├── LICENSES/ # Full license texts -└── README.adoc # Project documentation -``` - -## Design Principles - -- **Separation of Concerns**: Each module has a single responsibility -- **Testability**: Code is written to be easily testable -- **Documentation**: All public APIs are documented -- **Configuration**: Environment-specific settings are externalized - -## Dependencies - -- External dependencies are minimized and clearly declared -- Version pinning is used for reproducibility - -## Security Considerations - -- Sensitive data is never committed to the repository -- Secrets are managed through environment variables or secure vaults -- Regular dependency audits are performed - -## Maintainability - -- Code follows consistent style guidelines -- Pull requests require review and CI checks -- Issues and discussions are tracked transparently - ---- - -*Last updated: 2026-07-18* diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc new file mode 100644 index 0000000..8550bd0 --- /dev/null +++ b/CHANGELOG.adoc @@ -0,0 +1,78 @@ +== Changelog + +All notable changes to `+feedback-o-tron+` will be documented in this +file. + +This file is generated from conventional commits by the +https://github.com/hyperpolymath/standards/blob/main/.github/workflows/changelog-reusable.yml[`+changelog-reusable.yml+`] +workflow (`+hyperpolymath/standards#206+`). Adopt the workflow in this +repo’s CI to keep this file in sync automatically — see +https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml[`+templates/cliff.toml+`] +for the canonical config. + +The format follows https://keepachangelog.com/en/1.1.0/[Keep a +Changelog]; this project aims to follow +https://semver.org/spec/v2.0.0.html[Semantic Versioning]. + +=== [Unreleased] + +==== Added + +* feat: comprehensive repo improvements — error types, rate limiting, +retry, BGP/RPKI, tests, CI +* feat: comprehensive repo improvements — tests, docs, credential +persistence +* feat(crg): add crg-grade and crg-badge justfile recipes +* feat: add soft Groove manifest with passive mode and dogfood-feedback +capability +* feat: add stapeln.toml container definition +* feat: deploy UX Manifesto infrastructure +* feat: add Discord and Reddit channels +* feat: add Discord and Reddit channels +* feat: add CLADE.a2ml — clade taxonomy declaration +* feat: add AI-native installation experience + +==== Fixed + +* fix(ci): bump a2ml/k9-validate-action pins to canonical (#11) +* fix(ci): sync hypatia-scan.yml to canonical (#10) +* fix(ci): adopt canonical hypatia-scan.yml (#9) +* fix: replace String.to_atom with String.to_existing_atom +* fix(scorecard): enforce granular permissions and add fuzzing +placeholder +* fix(ci): Resolve workflow-linter self-matching and metadata issues +* fix(scorecard): enforce granular permissions and add fuzzing +placeholder +* fix(ci): Resolve workflow-linter self-matching and metadata issues +* fix: correct email jonathan.jewell → j.d.a.jewell +* fix: global MPL-2.0 → MPL-2.0-or-later replacement + +==== Changed + +* refactor: migrate 6SCM → 6A2 (.scm → .a2ml format) + +==== Documentation + +* docs: substantive CRG C annotation (EXPLAINME.adoc) +* docs: add EXPLAINME.adoc — prove-it file backing README claims +* docs: update to v1.0.0 production status with comprehensive guides +* docs: update license from AGPL to PMPL + +==== CI + +* ci: redistribute concurrency-cancel guard to read-only check workflows +(#13) +* ci: bump actions/upload-artifact SHA to current v4 (#7) +* ci: SHA-pin hyperpolymath validate-actions in dogfood-gate +* ci: wire hypatia-scan.yml to query own Dependabot alerts +* ci: deploy missing standard workflows (1 added) + +=== Pre-history + +Prior commits to this file’s introduction are recorded in git history +but not formally classified into Keep-a-Changelog sections. To backfill, +run `+git cliff -o CHANGELOG.md+` locally using the canonical +https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml[`+cliff.toml+`] +— this is one-shot mechanical work. + +''''' diff --git a/CHANGELOG.md b/CHANGELOG.md deleted file mode 100644 index a37f67e..0000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,71 +0,0 @@ - -# Changelog - -All notable changes to `feedback-o-tron` will be documented in this file. - -This file is generated from conventional commits by the -[`changelog-reusable.yml`](https://github.com/hyperpolymath/standards/blob/main/.github/workflows/changelog-reusable.yml) -workflow (`hyperpolymath/standards#206`). Adopt the workflow in this repo's CI to keep this file in sync automatically — see -[`templates/cliff.toml`](https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml) -for the canonical config. - -The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); -this project aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - -## [Unreleased] - -### Added - -- feat: comprehensive repo improvements — error types, rate limiting, retry, BGP/RPKI, tests, CI -- feat: comprehensive repo improvements — tests, docs, credential persistence -- feat(crg): add crg-grade and crg-badge justfile recipes -- feat: add soft Groove manifest with passive mode and dogfood-feedback capability -- feat: add stapeln.toml container definition -- feat: deploy UX Manifesto infrastructure -- feat: add Discord and Reddit channels -- feat: add Discord and Reddit channels -- feat: add CLADE.a2ml — clade taxonomy declaration -- feat: add AI-native installation experience - -### Fixed - -- fix(ci): bump a2ml/k9-validate-action pins to canonical (#11) -- fix(ci): sync hypatia-scan.yml to canonical (#10) -- fix(ci): adopt canonical hypatia-scan.yml (#9) -- fix: replace String.to_atom with String.to_existing_atom -- fix(scorecard): enforce granular permissions and add fuzzing placeholder -- fix(ci): Resolve workflow-linter self-matching and metadata issues -- fix(scorecard): enforce granular permissions and add fuzzing placeholder -- fix(ci): Resolve workflow-linter self-matching and metadata issues -- fix: correct email jonathan.jewell → j.d.a.jewell -- fix: global MPL-2.0 → MPL-2.0-or-later replacement - -### Changed - -- refactor: migrate 6SCM → 6A2 (.scm → .a2ml format) - -### Documentation - -- docs: substantive CRG C annotation (EXPLAINME.adoc) -- docs: add EXPLAINME.adoc — prove-it file backing README claims -- docs: update to v1.0.0 production status with comprehensive guides -- docs: update license from AGPL to PMPL - -### CI - -- ci: redistribute concurrency-cancel guard to read-only check workflows (#13) -- ci: bump actions/upload-artifact SHA to current v4 (#7) -- ci: SHA-pin hyperpolymath validate-actions in dogfood-gate -- ci: wire hypatia-scan.yml to query own Dependabot alerts -- ci: deploy missing standard workflows (1 added) - -## Pre-history - -Prior commits to this file's introduction are recorded in git history but not formally classified into Keep-a-Changelog sections. To backfill, run `git cliff -o CHANGELOG.md` locally using the canonical [`cliff.toml`](https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml) — this is one-shot mechanical work. - ---- - - diff --git a/CODE_OF_CONDUCT.adoc b/CODE_OF_CONDUCT.adoc new file mode 100644 index 0000000..f39d9ca --- /dev/null +++ b/CODE_OF_CONDUCT.adoc @@ -0,0 +1,132 @@ +== Contributor Covenant Code of Conduct + +=== Our Pledge + +We as members, contributors, and leaders pledge to make participation in +our community a harassment-free experience for everyone, regardless of +age, body size, visible or invisible disability, ethnicity, sex +characteristics, gender identity and expression, level of experience, +education, socio-economic status, nationality, personal appearance, +race, religion, or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, +welcoming, diverse, inclusive, and healthy community. + +=== Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our +mistakes, and learning from the experience +* Focusing on what is best not just for us as individuals, but for the +overall community + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or +advances of any kind +* Trolling, insulting or derogatory comments, and personal or political +attacks +* Public or private harassment +* Publishing others’ private information, such as a physical or email +address, without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a +professional setting + +=== Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our +standards of acceptable behavior and will take appropriate and fair +corrective action in response to any behavior that they deem +inappropriate, threatening, offensive, or harmful. + +Community leaders have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other +contributions that are not aligned to this Code of Conduct, and will +communicate reasons for moderation decisions when appropriate. + +=== Scope + +This Code of Conduct applies within all community spaces, and also +applies when an individual is officially representing the community in +public spaces. Examples of representing our community include using an +official e-mail address, posting via an official social media account, +or acting as an appointed representative at an online or offline event. + +=== Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may +be reported to the community leaders responsible for enforcement at . +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security +of the reporter of any incident. + +=== Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in +determining the consequences for any action they deem in violation of +this Code of Conduct: + +==== 1. Correction + +*Community Impact*: Use of inappropriate language or other behavior +deemed unprofessional or unwelcome in the community. + +*Consequence*: A private, written warning from community leaders, +providing clarity around the nature of the violation and an explanation +of why the behavior was inappropriate. A public apology may be +requested. + +==== 2. Warning + +*Community Impact*: A violation through a single incident or series of +actions. + +*Consequence*: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, for a specified period of +time. This includes avoiding interactions in community spaces as well as +external channels like social media. Violating these terms may lead to a +temporary or permanent ban. + +==== 3. Temporary Ban + +*Community Impact*: A serious violation of community standards, +including sustained inappropriate behavior. + +*Consequence*: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No +public or private interaction with the people involved, including +unsolicited interaction with those enforcing the Code of Conduct, is +allowed during this period. Violating these terms may lead to a +permanent ban. + +==== 4. Permanent Ban + +*Community Impact*: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of +individuals. + +*Consequence*: A permanent ban from any sort of public interaction +within the community. + +=== Attribution + +This Code of Conduct is adapted from the +https://www.contributor-covenant.org[Contributor Covenant], version 2.0, +available at +https://www.contributor-covenant.org/version/2/0/code_of_conduct.html. + +Community Impact Guidelines were inspired by +https://github.com/mozilla/diversity[Mozilla’s code of conduct +enforcement ladder]. + +For answers to common questions about this code of conduct, see the FAQ +at https://www.contributor-covenant.org/faq. Translations are available +at https://www.contributor-covenant.org/translations. diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md deleted file mode 100644 index e06b1e3..0000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,132 +0,0 @@ - -# Contributor Covenant Code of Conduct - -## Our Pledge - -We as members, contributors, and leaders pledge to make participation in our -community a harassment-free experience for everyone, regardless of age, body -size, visible or invisible disability, ethnicity, sex characteristics, gender -identity and expression, level of experience, education, socio-economic status, -nationality, personal appearance, race, religion, or sexual identity -and orientation. - -We pledge to act and interact in ways that contribute to an open, welcoming, -diverse, inclusive, and healthy community. - -## Our Standards - -Examples of behavior that contributes to a positive environment for our -community include: - -* Demonstrating empathy and kindness toward other people -* Being respectful of differing opinions, viewpoints, and experiences -* Giving and gracefully accepting constructive feedback -* Accepting responsibility and apologizing to those affected by our mistakes, - and learning from the experience -* Focusing on what is best not just for us as individuals, but for the - overall community - -Examples of unacceptable behavior include: - -* The use of sexualized language or imagery, and sexual attention or - advances of any kind -* Trolling, insulting or derogatory comments, and personal or political attacks -* Public or private harassment -* Publishing others' private information, such as a physical or email - address, without their explicit permission -* Other conduct which could reasonably be considered inappropriate in a - professional setting - -## Enforcement Responsibilities - -Community leaders are responsible for clarifying and enforcing our standards of -acceptable behavior and will take appropriate and fair corrective action in -response to any behavior that they deem inappropriate, threatening, offensive, -or harmful. - -Community leaders have the right and responsibility to remove, edit, or reject -comments, commits, code, wiki edits, issues, and other contributions that are -not aligned to this Code of Conduct, and will communicate reasons for moderation -decisions when appropriate. - -## Scope - -This Code of Conduct applies within all community spaces, and also applies when -an individual is officially representing the community in public spaces. -Examples of representing our community include using an official e-mail address, -posting via an official social media account, or acting as an appointed -representative at an online or offline event. - -## Enforcement - -Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported to the community leaders responsible for enforcement at -. -All complaints will be reviewed and investigated promptly and fairly. - -All community leaders are obligated to respect the privacy and security of the -reporter of any incident. - -## Enforcement Guidelines - -Community leaders will follow these Community Impact Guidelines in determining -the consequences for any action they deem in violation of this Code of Conduct: - -### 1. Correction - -**Community Impact**: Use of inappropriate language or other behavior deemed -unprofessional or unwelcome in the community. - -**Consequence**: A private, written warning from community leaders, providing -clarity around the nature of the violation and an explanation of why the -behavior was inappropriate. A public apology may be requested. - -### 2. Warning - -**Community Impact**: A violation through a single incident or series -of actions. - -**Consequence**: A warning with consequences for continued behavior. No -interaction with the people involved, including unsolicited interaction with -those enforcing the Code of Conduct, for a specified period of time. This -includes avoiding interactions in community spaces as well as external channels -like social media. Violating these terms may lead to a temporary or -permanent ban. - -### 3. Temporary Ban - -**Community Impact**: A serious violation of community standards, including -sustained inappropriate behavior. - -**Consequence**: A temporary ban from any sort of interaction or public -communication with the community for a specified period of time. No public or -private interaction with the people involved, including unsolicited interaction -with those enforcing the Code of Conduct, is allowed during this period. -Violating these terms may lead to a permanent ban. - -### 4. Permanent Ban - -**Community Impact**: Demonstrating a pattern of violation of community -standards, including sustained inappropriate behavior, harassment of an -individual, or aggression toward or disparagement of classes of individuals. - -**Consequence**: A permanent ban from any sort of public interaction within -the community. - -## Attribution - -This Code of Conduct is adapted from the [Contributor Covenant][homepage], -version 2.0, available at -https://www.contributor-covenant.org/version/2/0/code_of_conduct.html. - -Community Impact Guidelines were inspired by [Mozilla's code of conduct -enforcement ladder](https://github.com/mozilla/diversity). - -[homepage]: https://www.contributor-covenant.org - -For answers to common questions about this code of conduct, see the FAQ at -https://www.contributor-covenant.org/faq. Translations are available at -https://www.contributor-covenant.org/translations. diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc index 40cdb64..93cfef9 100644 --- a/CONTRIBUTING.adoc +++ b/CONTRIBUTING.adoc @@ -1,122 +1,109 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -// Copyright (c) Jonathan D.A. Jewell -= Contributing to feedback-o-tron -:toc: +== Clone the repository -Thank you for your interest in contributing to feedback-o-tron! +git clone https://github.com/hyperpolymath/feedback-o-tron.git cd +feedback-o-tron -== Language Policy +== Using Guix (recommended for reproducibility) -This project follows the **Hyperpolymath RSR 2026** language standard. Before contributing, review the allowed and banned languages in `CLAUDE.md`. +guix develop -**Allowed:** +== Or using toolbox/distrobox -* **Elixir** — primary application code (all `elixir-mcp/` modules) -* **Zig** — FFI bridge (`ffi/zig/`) -* **Rust** — performance-critical components -* **Bash/POSIX Shell** — scripts and automation -* **Julia** — statistics (`julia-stats/`) +toolbox create feedback-o-tron-dev toolbox enter feedback-o-tron-dev # +Install dependencies manually -**Banned:** TypeScript, Node.js, npm, Python, Go, Java, Kotlin, Swift. See `CLAUDE.md` for the full list and rationale. +== Verify setup -== Getting Started +just check # or: cargo check / mix compile / etc. just test # Run test +suite -=== Prerequisites +.... -* Elixir >= 1.15 with OTP >= 26 -* Zig (for FFI development) -* Nix or Guix (optional, for reproducible environments) +### Repository Structure +.... -=== Setup +feedback-o-tron/ ├── src/ # Source code (Perimeter 1-2) ├── lib/ # +Library code (Perimeter 1-2) ├── extensions/ # Extensions (Perimeter 2) +├── plugins/ # Plugins (Perimeter 2) ├── tools/ # Tooling (Perimeter 2) +├── docs/ # Documentation (Perimeter 3) │ ├── architecture/ # ADRs, +specs (Perimeter 2) │ └── proposals/ # RFCs (Perimeter 3) ├── examples/ +# Examples (Perimeter 3) ├── spec/ # Spec tests (Perimeter 3) ├── tests/ +# Test suite (Perimeter 2-3) ├── .well-known/ # Protocol files +(Perimeter 1-3) ├── .github/ # GitHub config (Perimeter 1) │ ├── +ISSUE_TEMPLATE/ │ └── workflows/ ├── CHANGELOG.md ├── CODE_OF_CONDUCT.md +├── CONTRIBUTING.md # This file ├── GOVERNANCE.md ├── LICENSE ├── +MAINTAINERS.md ├── README.adoc ├── SECURITY.md ├── flake.guix # Guix +flake (Perimeter 1) └── Justfile # Task runner (Perimeter 1) -[source,bash] ----- -# Using Nix flake -nix develop +.... -# Or manually -cd elixir-mcp -mix deps.get -mix compile ----- +--- -=== Running Tests +## How to Contribute -[source,bash] ----- -cd elixir-mcp -mix test # Run all tests -mix test --trace # With verbose output ----- +### Reporting Bugs -== Development Guidelines +**Before reporting**: +1. Search existing issues +2. Check if it's already fixed in `main` +3. Determine which perimeter the bug affects -=== Code Style +**When reporting**: -* Run `mix format` before committing — CI enforces formatting -* Follow existing patterns in the codebase -* All channel adapters must implement the `FeedbackATron.Channel` behaviour -* All transports must be encrypted (HTTPS, NNTPS, SMTPS, Matrix) +Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) and include: -=== Security Requirements +- Clear, descriptive title +- Environment details (OS, versions, toolchain) +- Steps to reproduce +- Expected vs actual behaviour +- Logs, screenshots, or minimal reproduction -* No MD5 or SHA1 for security purposes (use SHA-256+) -* HTTPS only — no plaintext HTTP URLs -* No hardcoded secrets or credentials -* All dependencies must be SHA-pinned -* SPDX license headers on all source files +### Suggesting Features -=== Error Handling +**Before suggesting**: +1. Check the [roadmap](ROADMAP.md) if available +2. Search existing issues and discussions +3. Consider which perimeter the feature belongs to -Use the structured error types in `FeedbackATron.Error`: +**When suggesting**: -* `AuthenticationError` — credential failures -* `RateLimitError` — platform rate limits -* `NetworkError` — connectivity issues -* `ValidationError` — bad input -* `PlatformError` — unexpected API responses +Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) and include: -=== Adding a New Channel +- Problem statement (what pain point does this solve?) +- Proposed solution +- Alternatives considered +- Which perimeter this affects -1. Create `lib/feedback_a_tron/channels/your_platform.ex` -2. Implement `@behaviour FeedbackATron.Channel` -3. Add the platform to `Channel.registry/0` -4. Add credential loading to `Credentials` -5. Add rate limit config to `RateLimiter` -6. Add tests in `test/` -7. Update the CLI help text +### Your First Contribution -=== Commit Messages +Look for issues labelled: -* Use present tense: "Add feature" not "Added feature" -* Keep the first line under 72 characters -* Reference issues where applicable +- [`good first issue`](https://github.com/hyperpolymath/feedback-o-tron/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://github.com/hyperpolymath/feedback-o-tron/labels/help%20wanted) — Community help needed +- [`documentation`](https://github.com/hyperpolymath/feedback-o-tron/labels/documentation) — Docs improvements +- [`perimeter-3`](https://github.com/hyperpolymath/feedback-o-tron/labels/perimeter-3) — Community sandbox scope -== Architecture +--- -See `TOPOLOGY.md` for the full architecture diagram. +## Development Workflow -Key modules: +### Branch Naming +.... -* `Submitter` — orchestrates multi-platform submission with retry and rate limiting -* `Channel` — behaviour and registry for platform adapters -* `Deduplicator` — fuzzy matching to prevent duplicate filings -* `RateLimiter` — per-platform token bucket rate limiting -* `Retry` — exponential backoff for transient failures -* `AuditLog` — JSON-lines audit trail -* `NetworkVerifier` — pre/post-submission network safety checks -* `Credentials` — multi-source credential loading with rotation +docs/short-description # Documentation (P3) test/what-added # Test +additions (P3) feat/short-description # New features (P2) +fix/issue-number-description # Bug fixes (P2) refactor/what-changed # +Code improvements (P2) security/what-fixed # Security fixes (P1-2) -== Licensing +.... -All contributions must be licensed under MPL-2.0. -Add the SPDX header to all new files: +### Commit Messages -[source,elixir] ----- -# SPDX-License-Identifier: CC-BY-SA-4.0 ----- +We follow [Conventional Commits](https://www.conventionalcommits.org/): +.... -== Reporting Issues +(): -Use feedback-o-tron itself to report issues! Or open an issue on the GitHub repository. +{empty}[optional body] + +{empty}[optional footer] diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 3c7aaa2..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,120 +0,0 @@ - -# Clone the repository -git clone https://github.com/hyperpolymath/feedback-o-tron.git -cd feedback-o-tron - -# Using Nix (recommended for reproducibility) -nix develop - -# Or using toolbox/distrobox -toolbox create feedback-o-tron-dev -toolbox enter feedback-o-tron-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure -``` -feedback-o-tron/ -├── src/ # Source code (Perimeter 1-2) -├── lib/ # Library code (Perimeter 1-2) -├── extensions/ # Extensions (Perimeter 2) -├── plugins/ # Plugins (Perimeter 2) -├── tools/ # Tooling (Perimeter 2) -├── docs/ # Documentation (Perimeter 3) -│ ├── architecture/ # ADRs, specs (Perimeter 2) -│ └── proposals/ # RFCs (Perimeter 3) -├── examples/ # Examples (Perimeter 3) -├── spec/ # Spec tests (Perimeter 3) -├── tests/ # Test suite (Perimeter 2-3) -├── .well-known/ # Protocol files (Perimeter 1-3) -├── .github/ # GitHub config (Perimeter 1) -│ ├── ISSUE_TEMPLATE/ -│ └── workflows/ -├── CHANGELOG.md -├── CODE_OF_CONDUCT.md -├── CONTRIBUTING.md # This file -├── GOVERNANCE.md -├── LICENSE -├── MAINTAINERS.md -├── README.adoc -├── SECURITY.md -├── flake.nix # Nix flake (Perimeter 1) -└── Justfile # Task runner (Perimeter 1) -``` - ---- - -## How to Contribute - -### Reporting Bugs - -**Before reporting**: -1. Search existing issues -2. Check if it's already fixed in `main` -3. Determine which perimeter the bug affects - -**When reporting**: - -Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) and include: - -- Clear, descriptive title -- Environment details (OS, versions, toolchain) -- Steps to reproduce -- Expected vs actual behaviour -- Logs, screenshots, or minimal reproduction - -### Suggesting Features - -**Before suggesting**: -1. Check the [roadmap](ROADMAP.md) if available -2. Search existing issues and discussions -3. Consider which perimeter the feature belongs to - -**When suggesting**: - -Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) and include: - -- Problem statement (what pain point does this solve?) -- Proposed solution -- Alternatives considered -- Which perimeter this affects - -### Your First Contribution - -Look for issues labelled: - -- [`good first issue`](https://github.com/hyperpolymath/feedback-o-tron/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://github.com/hyperpolymath/feedback-o-tron/labels/help%20wanted) — Community help needed -- [`documentation`](https://github.com/hyperpolymath/feedback-o-tron/labels/documentation) — Docs improvements -- [`perimeter-3`](https://github.com/hyperpolymath/feedback-o-tron/labels/perimeter-3) — Community sandbox scope - ---- - -## Development Workflow - -### Branch Naming -``` -docs/short-description # Documentation (P3) -test/what-added # Test additions (P3) -feat/short-description # New features (P2) -fix/issue-number-description # Bug fixes (P2) -refactor/what-changed # Code improvements (P2) -security/what-fixed # Security fixes (P1-2) -``` - -### Commit Messages - -We follow [Conventional Commits](https://www.conventionalcommits.org/): -``` -(): - -[optional body] - -[optional footer] diff --git a/GOVERNANCE.adoc b/GOVERNANCE.adoc index e41020d..9b836fb 100644 --- a/GOVERNANCE.adoc +++ b/GOVERNANCE.adoc @@ -1,162 +1,60 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell -= Governance Model -:toc: preamble +== Governance -This document describes the governance model for this repository. +=== Overview -== Overview +This project is governed by the following principles and structures to +ensure transparent, inclusive, and effective decision-making. -This repository follows a **Sole Maintainer Governance Model**: +=== Roles and Responsibilities -* Single maintainer (@hyperpolymath) has full authority over the project -* All contributions are welcome and reviewed by the maintainer -* Decisions are made transparently through GitHub issues and discussions -* The project adheres to the hyperpolymath estate policies where applicable +==== Maintainers -== Core Principles +Maintainers are responsible for: - Reviewing and merging pull requests - +Managing releases and versioning - Ensuring code quality and standards - +Triaging issues and bug reports - Community engagement and support -[cols="1,2"] -|=== -| Principle | Description +==== Contributors -| **Benevolent Dictatorship** | Maintainer has final decision authority but seeks community input +Contributors are expected to: - Follow the code of conduct - Submit +well-documented pull requests - Write tests for new functionality - +Maintain existing tests - Update documentation as needed -| **Meritocracy** | Contributions are judged on technical merit, not contributor identity +=== Decision Making -| **Transparency** | All significant decisions are documented publicly +==== Minor Changes -| **Consensus-Seeking** | Maintainer prefers consensus but will decide when necessary +* Can be made by any maintainer +* Include bug fixes, documentation updates, dependency updates -| **Open Contribution** | Anyone can contribute via fork and pull request +==== Major Changes -|=== +* Require discussion in issues or pull requests +* Include new features, architectural changes, API changes +* Need approval from at least 2 maintainers -== Roles and Permissions +==== Breaking Changes -[cols="1,2,2"] -|=== -| Role | Permissions | Assignment +* Require RFC (Request for Comments) process +* Need approval from majority of maintainers +* Must include migration guide -| **Maintainer** | Write access, merge rights, admin | @hyperpolymath -| **Contributors** | Read access, fork, submit PRs | All GitHub users -| **Users** | Use the software, report issues | All GitHub users +=== Code of Conduct -|=== +All participants are expected to follow our Code of Conduct. Violations +can be reported to the maintainers. -== Decision Making Framework +=== Communication -=== Routine Decisions +* *Issues*: For bug reports and feature requests +* *Discussions*: For questions and general discussion +* *Pull Requests*: For code contributions -* Bug fixes -* Documentation improvements -* Minor feature additions -* Dependency updates +=== Licensing -**Process**: Maintainer reviews and merges PRs that meet quality standards. +All contributions are made under the terms of the repository’s LICENSE +file. By submitting a pull request, you agree to license your +contributions accordingly. -=== Significant Changes +''''' -* New major features -* API changes -* Architecture modifications -* Breaking changes - -**Process**: -. Open issue describing the change -. Discuss with community (minimum 72 hours) -. Maintainer makes final decision -. Document rationale in issue/PR - -=== Structural Decisions - -* Repository purpose/renaming -* License changes -* Ownership transfer -* Deprecation/archival - -**Process**: -. Extended discussion (minimum 1 week) -. Maintainer makes final decision -. Document in CHANGELOG and governance docs - -== Contribution Lifecycle - -[cols="1,2"] -|=== -| Stage | Process - -| **Ideation** | Open issue, discuss feasibility - -| **Development** | Fork, implement, test thoroughly - -| **Review** | Submit PR, maintainer reviews within 7 days - -| **Merge** | Maintainer merges or requests changes - -| **Release** | Maintainer publishes according to project conventions - -|=== - -== Conflict Resolution - -In case of disagreements: - -. Discuss in the relevant GitHub issue or PR -. Provide technical justification for positions -. Maintainer mediates and makes final decision -. Decision is documented and can be revisited later - -== Project Policies - -This repository adheres to hyperpolymath estate-wide policies: - -* **License**: MPL-2.0 for code, CC-BY-SA-4.0 for prose (per standards/LICENCE-POLICY.adoc) -* **Code of Conduct**: Follows hyperpolymath CODE_OF_CONDUCT.md -* **Security**: Follows hyperpolymath SECURITY.md -* **Contributing**: Follows hyperpolymath CONTRIBUTING.adoc conventions - -== Repository-Specific Conventions - -[cols="1,2"] -|=== -| Convention | Description - -| **Signing** | All commits must be signed (SSH or GPG) - -| **SPDX Headers** | All source files must have SPDX license identifiers - -| **Contractiles** | Mustfile, Trustfile, Intendfile, Adjustfile in root - -| **Machine Readable** | META.a2ml in .machine_readable/6a2/ - -| **CI/CD** | GitHub Actions workflows in .github/workflows/ - -|=== - -== Governance Evolution - -As the project grows, this governance model may evolve: - -* **Adding Co-Maintainers**: When contribution volume warrants it -* **Forming a Team**: For complex multi-maintainer projects -* **Adopting TPCF**: For large, multi-repository projects (see rhodium-standard-repositories) - -Changes to this document require the same process as Significant Changes above. - -== See Also - -* link:MAINTAINERS.adoc[Maintainers] -* link:CODE_OF_CONDUCT.md[Code of Conduct] -* link:CONTRIBUTING.adoc[Contributing Guide] -* link:https://github.com/hyperpolymath/standards/blob/main/LICENCE-POLICY.adoc[Estate License Policy] -* link:https://github.com/hyperpolymath/standards[rhodium-standard-repositories (TPCF)] - -== Changelog - -[cols="1,1,1"] -|=== -| Date | Change | By - -| 2026-06-07 | Initial governance model established | @hyperpolymath -|=== +_Last updated: 2026-07-18_ diff --git a/GOVERNANCE.md b/GOVERNANCE.md deleted file mode 100644 index e27364c..0000000 --- a/GOVERNANCE.md +++ /dev/null @@ -1,60 +0,0 @@ -# Governance - -## Overview - -This project is governed by the following principles and structures to ensure transparent, inclusive, and effective decision-making. - -## Roles and Responsibilities - -### Maintainers - -Maintainers are responsible for: -- Reviewing and merging pull requests -- Managing releases and versioning -- Ensuring code quality and standards -- Triaging issues and bug reports -- Community engagement and support - -### Contributors - -Contributors are expected to: -- Follow the code of conduct -- Submit well-documented pull requests -- Write tests for new functionality -- Maintain existing tests -- Update documentation as needed - -## Decision Making - -### Minor Changes -- Can be made by any maintainer -- Include bug fixes, documentation updates, dependency updates - -### Major Changes -- Require discussion in issues or pull requests -- Include new features, architectural changes, API changes -- Need approval from at least 2 maintainers - -### Breaking Changes -- Require RFC (Request for Comments) process -- Need approval from majority of maintainers -- Must include migration guide - -## Code of Conduct - -All participants are expected to follow our Code of Conduct. Violations can be reported to the maintainers. - -## Communication - -- **Issues**: For bug reports and feature requests -- **Discussions**: For questions and general discussion -- **Pull Requests**: For code contributions - -## Licensing - -All contributions are made under the terms of the repository's LICENSE file. -By submitting a pull request, you agree to license your contributions accordingly. - ---- - -*Last updated: 2026-07-18* diff --git a/Justfile b/Justfile index 5fad4f1..ce5e743 100644 --- a/Justfile +++ b/Justfile @@ -1,4 +1,4 @@ -# feedback-a-tron - Nix Development Tasks +# feedback-a-tron - Guix Development Tasks set shell := ["bash", "-uc"] set dotenv-load := true @@ -10,35 +10,35 @@ project := "feedback-a-tron" default: @just --list --unsorted -# Build with nix +# Build with guix build: - nix build + guix build # Build and show output path build-show: - nix build --print-out-paths + guix build --print-out-paths # Enter dev shell develop: - nix develop + guix develop # Check flake check: - nix flake check + guix flake check # Update flake inputs update: - nix flake update + guix flake update # Show flake info info: - nix flake info + guix flake info -# Format nix files +# Format guix files fmt: - nixfmt *.nix || nix fmt + nixfmt *.guix || guix fmt -# Run nix linter +# Run guix linter lint: statix check . || true @@ -48,7 +48,7 @@ clean: # Show derivation show-drv: - nix derivation show + guix derivation show # All checks before commit pre-commit: check diff --git a/PROOF-NEEDS.adoc b/PROOF-NEEDS.adoc new file mode 100644 index 0000000..c1c6aa6 --- /dev/null +++ b/PROOF-NEEDS.adoc @@ -0,0 +1,42 @@ +== Proof Requirements + +=== Current state + +* `+src/abi/Types.idr+` — Feedback types +* `+src/abi/Layout.idr+` — Memory layout +* `+src/abi/Foreign.idr+` — FFI declarations +* No dangerous patterns in ABI layer +* Claims: "`formal verification via Idris2 for critical ABI definitions +and memory safety proofs`", "`Production Ready`" +* 92K lines of source + +=== What needs proving + +* *Deduplication correctness*: Prove the deduplicator never drops unique +feedback entries and never allows true duplicates through +* *Submission atomicity*: Prove feedback submissions either fully +succeed or fully fail (no partial submissions that corrupt state) +* *Memory layout proofs*: The README claims "`memory safety proofs`" — +these should be materialized in the ABI layer with actual dependent type +proofs for layout correctness +* *Rate limiting fairness*: Prove rate limiting does not permanently +block legitimate users + +=== Recommended prover + +* *Idris2* — Already used for ABI; the claim of "`memory safety proofs`" +needs to be substantiated with actual proofs in the existing `+.idr+` +files + +=== Priority + +* *MEDIUM* — The README explicitly claims formal verification and memory +safety proofs. If those proofs do not exist in substance, the claim is +misleading. Priority is to either write the proofs or soften the claims. + +=== Template ABI Cleanup (2026-03-29) + +Template ABI removed – was creating false impression of formal +verification. The removed files (Types.idr, Layout.idr, Foreign.idr) +contained only RSR template scaffolding with unresolved +\{\{PROJECT}}/\{\{AUTHOR}} placeholders and no domain-specific proofs. diff --git a/PROOF-NEEDS.md b/PROOF-NEEDS.md deleted file mode 100644 index df668bc..0000000 --- a/PROOF-NEEDS.md +++ /dev/null @@ -1,31 +0,0 @@ - -# Proof Requirements - -## Current state -- `src/abi/Types.idr` — Feedback types -- `src/abi/Layout.idr` — Memory layout -- `src/abi/Foreign.idr` — FFI declarations -- No dangerous patterns in ABI layer -- Claims: "formal verification via Idris2 for critical ABI definitions and memory safety proofs", "Production Ready" -- 92K lines of source - -## What needs proving -- **Deduplication correctness**: Prove the deduplicator never drops unique feedback entries and never allows true duplicates through -- **Submission atomicity**: Prove feedback submissions either fully succeed or fully fail (no partial submissions that corrupt state) -- **Memory layout proofs**: The README claims "memory safety proofs" — these should be materialized in the ABI layer with actual dependent type proofs for layout correctness -- **Rate limiting fairness**: Prove rate limiting does not permanently block legitimate users - -## Recommended prover -- **Idris2** — Already used for ABI; the claim of "memory safety proofs" needs to be substantiated with actual proofs in the existing `.idr` files - -## Priority -- **MEDIUM** — The README explicitly claims formal verification and memory safety proofs. If those proofs do not exist in substance, the claim is misleading. Priority is to either write the proofs or soften the claims. - -## Template ABI Cleanup (2026-03-29) - -Template ABI removed -- was creating false impression of formal verification. -The removed files (Types.idr, Layout.idr, Foreign.idr) contained only RSR template -scaffolding with unresolved {{PROJECT}}/{{AUTHOR}} placeholders and no domain-specific proofs. diff --git a/RSR_OUTLINE.adoc b/RSR_OUTLINE.adoc index 2d07b49..6cd04f2 100644 --- a/RSR_OUTLINE.adoc +++ b/RSR_OUTLINE.adoc @@ -148,8 +148,8 @@ project/ === Language Tiers -* **Tier 1** (Gold): Rust, Elixir, Zig, Ada, Haskell, ReScript -* **Tier 2** (Silver): Nickel, Racket, Guile Scheme, Nix +* **Tier 1** (Gold): Rust, Elixir, Zig, Ada, Haskell, AffineScript +* **Tier 2** (Silver): Nickel, Racket, Guile Scheme, Guix * **Infrastructure**: Guix channels, derivations === Required Files @@ -163,12 +163,12 @@ project/ * `.well-known/security.txt` * `.well-known/ai.txt` * `.well-known/humans.txt` -* `guix.scm` OR `flake.nix` +* `guix.scm` OR `flake.guix` === Prohibited * Python outside `salt/` directory -* TypeScript/JavaScript (use ReScript) +* TypeScript/JavaScript (use AffineScript) * CUE (use Guile/Nickel) * `Dockerfile` (use `Containerfile`) diff --git a/SECURITY.adoc b/SECURITY.adoc new file mode 100644 index 0000000..1288150 --- /dev/null +++ b/SECURITY.adoc @@ -0,0 +1,23 @@ +== Security Policy + +=== Supported Versions + +Use this section to tell people about which versions of your project are +currently being supported with security updates. + +[cols=",",options="header",] +|=== +|Version |Supported +|5.1.x |:white_check_mark: +|5.0.x |:x: +|4.0.x |:white_check_mark: +|< 4.0 |:x: +|=== + +=== Reporting a Vulnerability + +Use this section to tell people how to report a vulnerability. + +Tell them where to go, how often they can expect to get an update on a +reported vulnerability, what to expect if the vulnerability is accepted +or declined, etc. diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index 062acbd..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,25 +0,0 @@ - -# Security Policy - -## Supported Versions - -Use this section to tell people about which versions of your project are -currently being supported with security updates. - -| Version | Supported | -| ------- | ------------------ | -| 5.1.x | :white_check_mark: | -| 5.0.x | :x: | -| 4.0.x | :white_check_mark: | -| < 4.0 | :x: | - -## Reporting a Vulnerability - -Use this section to tell people how to report a vulnerability. - -Tell them where to go, how often they can expect to get an update on a -reported vulnerability, what to expect if the vulnerability is accepted or -declined, etc. diff --git a/TEST-NEEDS.adoc b/TEST-NEEDS.adoc new file mode 100644 index 0000000..e096cc2 --- /dev/null +++ b/TEST-NEEDS.adoc @@ -0,0 +1,99 @@ +== Test & Benchmark Requirements + +=== CRG Grade: C — ACHIEVED 2026-04-04 + +=== Current State + +* Unit tests: NONE (0 test files found) +* Integration tests: NONE +* E2E tests: NONE +* Benchmarks: NONE +* panic-attack scan: NEVER RUN + +=== What’s Missing + +==== Point-to-Point (P2P) + +34 Elixir source files with ZERO test files: - +feedback_a_tron/application.ex — no tests - +feedback_a_tron/deduplicator.ex — no tests - +feedback_a_tron/mcp/tools/submit_feedback.ex — no tests - +feedback_a_tron/mcp/tools/migration_observe.ex — no tests - +feedback_a_tron/mcp/server.ex — no tests - +feedback_a_tron/network_verifier.ex — no tests - +feedback_a_tron/submitter.ex — no tests - feedback_a_tron/audit_log.ex — +no tests - feedback_a_tron/cli.ex — no tests - +feedback_a_tron/migration_observer.ex — no tests - +feedback_a_tron/verisim_writer.ex — no tests - +feedback_a_tron/batch_reviewer.ex — no tests - +feedback_a_tron/report_generator.ex — no tests - +feedback_a_tron/pipeline/supervisor.ex — no tests - +feedback_a_tron/pipeline/producer.ex — no tests - +feedback_a_tron/pipeline/verisim_consumer.ex — no tests - +feedback_a_tron/pipeline/review_consumer.ex — no tests - +feedback_a_tron/secure_dns.ex — no tests - +feedback_a_tron/channels/nntp.ex — no tests - +feedback_a_tron/channels/discourse.ex — no tests - Plus ~14 more modules +- 3 Idris2 ABI files — no tests - 1 Julia file — no tests + +==== End-to-End (E2E) + +* Submit feedback -> deduplicate -> review -> write to VeriSimDB +* MCP server: receive tool call -> process -> respond +* Batch review: load batch -> review all -> generate report +* Pipeline: produce events -> consume -> write to VeriSimDB +* Migration observation: detect migration -> observe -> record +* NNTP channel: receive -> process -> forward +* Discourse channel: receive -> process -> forward +* CLI: submit/review/report commands + +==== Aspect Tests + +* [ ] Security (MCP tool injection, network verifier bypass, NNTP +injection, audit log tampering) +* [ ] Performance (batch review throughput, pipeline backpressure, +VeriSimDB write latency) +* [ ] Concurrency (GenStage pipeline, concurrent submissions, supervisor +restart) +* [ ] Error handling (VeriSimDB unavailable, network failures, malformed +feedback) +* [ ] Accessibility (N/A) + +==== Build & Execution + +* [ ] mix compile — not verified +* [ ] mix test — not verified (no test files to run) +* [ ] MCP server starts — not verified +* [ ] CLI –help works — not verified +* [ ] Self-diagnostic — none + +==== Benchmarks Needed + +* Feedback submission throughput +* Deduplication speed and accuracy +* Pipeline end-to-end latency +* VeriSimDB write performance +* Batch review performance at scale + +==== Self-Tests + +* [ ] panic-attack assail on own repo +* [ ] MCP server health check +* [ ] Pipeline self-test + +=== Priority + +* *HIGH* — 34 Elixir source files with ZERO tests. This is a feedback +processing system with MCP integration, GenStage pipeline, multi-channel +input (NNTP, Discourse), VeriSimDB integration, and audit logging. Not a +single module has a test file. The pipeline supervisor/producer/consumer +pattern especially needs testing for correctness under load and failure +conditions. + +=== FAKE-FUZZ ALERT + +* `+tests/fuzz/placeholder.txt+` is a scorecard placeholder inherited +from rsr-template-repo — it does NOT provide real fuzz testing +* Replace with an actual fuzz harness (see +rsr-template-repo/tests/fuzz/README.adoc) or remove the file +* Priority: P2 — creates false impression of fuzz coverage diff --git a/TEST-NEEDS.md b/TEST-NEEDS.md deleted file mode 100644 index db99a34..0000000 --- a/TEST-NEEDS.md +++ /dev/null @@ -1,86 +0,0 @@ - -# Test & Benchmark Requirements - -## CRG Grade: C — ACHIEVED 2026-04-04 - -## Current State -- Unit tests: NONE (0 test files found) -- Integration tests: NONE -- E2E tests: NONE -- Benchmarks: NONE -- panic-attack scan: NEVER RUN - -## What's Missing -### Point-to-Point (P2P) -34 Elixir source files with ZERO test files: -- feedback_a_tron/application.ex — no tests -- feedback_a_tron/deduplicator.ex — no tests -- feedback_a_tron/mcp/tools/submit_feedback.ex — no tests -- feedback_a_tron/mcp/tools/migration_observe.ex — no tests -- feedback_a_tron/mcp/server.ex — no tests -- feedback_a_tron/network_verifier.ex — no tests -- feedback_a_tron/submitter.ex — no tests -- feedback_a_tron/audit_log.ex — no tests -- feedback_a_tron/cli.ex — no tests -- feedback_a_tron/migration_observer.ex — no tests -- feedback_a_tron/verisim_writer.ex — no tests -- feedback_a_tron/batch_reviewer.ex — no tests -- feedback_a_tron/report_generator.ex — no tests -- feedback_a_tron/pipeline/supervisor.ex — no tests -- feedback_a_tron/pipeline/producer.ex — no tests -- feedback_a_tron/pipeline/verisim_consumer.ex — no tests -- feedback_a_tron/pipeline/review_consumer.ex — no tests -- feedback_a_tron/secure_dns.ex — no tests -- feedback_a_tron/channels/nntp.ex — no tests -- feedback_a_tron/channels/discourse.ex — no tests -- Plus ~14 more modules -- 3 Idris2 ABI files — no tests -- 1 Julia file — no tests - -### End-to-End (E2E) -- Submit feedback -> deduplicate -> review -> write to VeriSimDB -- MCP server: receive tool call -> process -> respond -- Batch review: load batch -> review all -> generate report -- Pipeline: produce events -> consume -> write to VeriSimDB -- Migration observation: detect migration -> observe -> record -- NNTP channel: receive -> process -> forward -- Discourse channel: receive -> process -> forward -- CLI: submit/review/report commands - -### Aspect Tests -- [ ] Security (MCP tool injection, network verifier bypass, NNTP injection, audit log tampering) -- [ ] Performance (batch review throughput, pipeline backpressure, VeriSimDB write latency) -- [ ] Concurrency (GenStage pipeline, concurrent submissions, supervisor restart) -- [ ] Error handling (VeriSimDB unavailable, network failures, malformed feedback) -- [ ] Accessibility (N/A) - -### Build & Execution -- [ ] mix compile — not verified -- [ ] mix test — not verified (no test files to run) -- [ ] MCP server starts — not verified -- [ ] CLI --help works — not verified -- [ ] Self-diagnostic — none - -### Benchmarks Needed -- Feedback submission throughput -- Deduplication speed and accuracy -- Pipeline end-to-end latency -- VeriSimDB write performance -- Batch review performance at scale - -### Self-Tests -- [ ] panic-attack assail on own repo -- [ ] MCP server health check -- [ ] Pipeline self-test - -## Priority -- **HIGH** — 34 Elixir source files with ZERO tests. This is a feedback processing system with MCP integration, GenStage pipeline, multi-channel input (NNTP, Discourse), VeriSimDB integration, and audit logging. Not a single module has a test file. The pipeline supervisor/producer/consumer pattern especially needs testing for correctness under load and failure conditions. - -## FAKE-FUZZ ALERT - -- `tests/fuzz/placeholder.txt` is a scorecard placeholder inherited from rsr-template-repo — it does NOT provide real fuzz testing -- Replace with an actual fuzz harness (see rsr-template-repo/tests/fuzz/README.adoc) or remove the file -- Priority: P2 — creates false impression of fuzz coverage diff --git a/TOPOLOGY.md b/TOPOLOGY.adoc similarity index 92% rename from TOPOLOGY.md rename to TOPOLOGY.adoc index fdfea2e..519958d 100644 --- a/TOPOLOGY.md +++ b/TOPOLOGY.adoc @@ -1,15 +1,8 @@ - - - +== feedback-o-tron — Project Topology -# feedback-o-tron — Project Topology +=== System Architecture -## System Architecture - -``` +.... ┌─────────────────────────────────────────┐ │ AI AGENTS / USERS │ │ (Claude, Gemini, ChatGPT) │ @@ -79,11 +72,11 @@ Copyright (c) Jonathan D.A. Jewell │ │ Codeberg │ │ Bitbucket │ │ Email ││ │ └───────────┘ └───────────┘ └───────┘│ └─────────────────────────────────────────┘ -``` +.... -## Completion Dashboard +=== Completion Dashboard -``` +.... COMPONENT STATUS NOTES ───────────────────────────────── ────────────────── ───────────────────────────────── INTERFACE LAYER @@ -128,11 +121,11 @@ REPO INFRASTRUCTURE ───────────────────────────────────────────────────────────────────────────── OVERALL: ████████░░ ~75% Core validated; synthesis new; FFI enforcement not built -``` +.... -## Key Dependencies +=== Key Dependencies -``` +.... Idris2 contract spec ──(mirrored by)──► Elixir FormValidator │ │ └──(Zig FFI bridge: STUB, ──► planned enforcement path) @@ -146,19 +139,20 @@ Idris2 contract spec ──(mirrored by)──► Elixir FormValidator └──────────┴────────────┬──────────────┴──────────┘ ▼ EXTERNAL APIs -``` +.... -## Update Protocol +=== Update Protocol This file is maintained by both humans and AI agents. When updating: -1. **After completing a component**: Change its bar and percentage -2. **After adding a component**: Add a new row in the appropriate section -3. **After architectural changes**: Update the ASCII diagram -4. **Date**: Update the `Last updated` comment at the top of this file -5. **Honesty rule**: a bar only reaches 100% when the code exists, is wired - in, and does what the row says. "Aspirational" boxes get a low bar and a - note — never a full bar. No universal "100% Production Ready" rows. - -Progress bars use: `█` (filled) and `░` (empty), 10 characters wide. -Percentages: 0%, 10%, 20%, ... 100% (in 10% increments). +[arabic] +. *After completing a component*: Change its bar and percentage +. *After adding a component*: Add a new row in the appropriate section +. *After architectural changes*: Update the ASCII diagram +. *Date*: Update the `+Last updated+` comment at the top of this file +. *Honesty rule*: a bar only reaches 100% when the code exists, is wired +in, and does what the row says. "`Aspirational`" boxes get a low bar and +a note — never a full bar. No universal "`100% Production Ready`" rows. + +Progress bars use: `+█+` (filled) and `+░+` (empty), 10 characters wide. +Percentages: 0%, 10%, 20%, … 100% (in 10% increments). diff --git a/docs/AUTONOMOUS-BUG-PIPELINE.adoc b/docs/AUTONOMOUS-BUG-PIPELINE.adoc index 0629caf..0ad0d28 100644 --- a/docs/AUTONOMOUS-BUG-PIPELINE.adoc +++ b/docs/AUTONOMOUS-BUG-PIPELINE.adoc @@ -228,7 +228,7 @@ Ground-truthed against the code in both local repos. Statuses: *BUILT* (real wor | Migration-observation subsystem | PARTIAL -| Real but off by default; observes ReScript *code*-migrations, not LLM trajectories. Likely the +| Real but off by default; observes AffineScript *code*-migrations, not LLM trajectories. Likely the origin of the diagram's "gather logs" box, but it does not do what the diagram claims. |=== diff --git a/docs/tech-debt-2026-05-26.adoc b/docs/tech-debt-2026-05-26.adoc new file mode 100644 index 0000000..500a295 --- /dev/null +++ b/docs/tech-debt-2026-05-26.adoc @@ -0,0 +1,71 @@ +== Tech-Debt Audit — feedback-o-tron — 2026-05-26 + +*Source:* estate-wide automated scan 2026-05-26. *Companion:* +https://github.com/hyperpolymath/standards/tree/main/docs/audits[`+hyperpolymath/standards+` +2026-05-26-estate-*-debt audits]. *Combined severity:* `+MEDIUM+`. + +This file records the _raw findings_ — it does not by itself fix the +debt. Each section ends with a '`Recommended next move`' line; closing +the debt is follow-up work. + +=== 1. Proof debt + +No proof-bearing files (`+*.v+`, `+*.lean+`, `+*.agda+`, `+*.idr+`, +`+*.idr2+`, `+*.fst+`, `+*.dfy+`, `+*.tla+`, `+*.ads+`, `+*.adb+`) found +in this repo. + +*Recommended next move:* none. + +=== 2. Licence debt + +[cols=",",options="header",] +|=== +|Field |Value +|LICENSE file |`+LICENSE+` +|SPDX header |`+MPL-2.0+` +|Manifest licence |`+NONE+` +|Body classifier |`+Palimp-MPL-2.0+` +|Severity |`+ok+` +|=== + +*Recommended next move:* none for licence. + +=== 3. Documentation debt + +[cols=",",options="header",] +|=== +|Field |Value +|README lines |787 +|`+docs/+` files |3 +|`+docs/+` LoC |764 +|CHANGELOG.md |N +|CONTRIBUTING.md |Y +|CODE_OF_CONDUCT.md |Y +|SECURITY.md |Y +|Severity |`+MEDIUM+` +|=== + +*Recommended next move:* introduce a `+docs/+` directory. The README at +787 lines has likely grown to do the work of `+docs/+` — split it into a +thin README + `+docs/architecture.md+`, `+docs/usage.md+`, etc. +Heavy-wiki exemplars to copy from: `+affinescript+`, `+boj-server+`, +`+echidna+`, `+hypatia+`. + +Additionally: *CHANGELOG.md is missing.* 65% of estate repos lack one — +adopting a CHANGELOG (or auto-generating via `+git-cliff+`) is a +recommended estate-wide follow-up. + +=== Cross-references + +* Estate proof-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-proof-debt.md+` +* Estate licence-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-licence-debt.md+` +* Estate documentation-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-documentation-debt.md+` + +''''' + +🤖 Generated by Claude Code estate-wide tech-debt scan (2026-05-26). +This file is informational — closing the debt is follow-up work owned by +the maintainer. diff --git a/docs/tech-debt-2026-05-26.md b/docs/tech-debt-2026-05-26.md deleted file mode 100644 index 253fb3c..0000000 --- a/docs/tech-debt-2026-05-26.md +++ /dev/null @@ -1,56 +0,0 @@ - -# Tech-Debt Audit — feedback-o-tron — 2026-05-26 - -**Source:** estate-wide automated scan 2026-05-26. -**Companion:** [`hyperpolymath/standards` 2026-05-26-estate-*-debt audits](https://github.com/hyperpolymath/standards/tree/main/docs/audits). -**Combined severity:** `MEDIUM`. - -This file records the *raw findings* — it does not by itself fix the debt. Each section ends with a 'Recommended next move' line; closing the debt is follow-up work. - -## 1. Proof debt - -No proof-bearing files (`*.v`, `*.lean`, `*.agda`, `*.idr`, `*.idr2`, `*.fst`, `*.dfy`, `*.tla`, `*.ads`, `*.adb`) found in this repo. - -**Recommended next move:** none. - -## 2. Licence debt - -| Field | Value | -|---|---| -| LICENSE file | `LICENSE` | -| SPDX header | `MPL-2.0` | -| Manifest licence | `NONE` | -| Body classifier | `Palimp-MPL-2.0` | -| Severity | `ok` | - -**Recommended next move:** none for licence. - -## 3. Documentation debt - -| Field | Value | -|---|---| -| README lines | 787 | -| `docs/` files | 3 | -| `docs/` LoC | 764 | -| CHANGELOG.md | N | -| CONTRIBUTING.md | Y | -| CODE_OF_CONDUCT.md | Y | -| SECURITY.md | Y | -| Severity | `MEDIUM` | - -**Recommended next move:** introduce a `docs/` directory. The README at 787 lines has likely grown to do the work of `docs/` — split it into a thin README + `docs/architecture.md`, `docs/usage.md`, etc. Heavy-wiki exemplars to copy from: `affinescript`, `boj-server`, `echidna`, `hypatia`. - -Additionally: **CHANGELOG.md is missing.** 65% of estate repos lack one — adopting a CHANGELOG (or auto-generating via `git-cliff`) is a recommended estate-wide follow-up. - -## Cross-references - -- Estate proof-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-proof-debt.md` -- Estate licence-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-licence-debt.md` -- Estate documentation-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-documentation-debt.md` - ---- - -🤖 Generated by Claude Code estate-wide tech-debt scan (2026-05-26). This file is informational — closing the debt is follow-up work owned by the maintainer. diff --git a/elixir-mcp/ARCHITECTURE.md b/elixir-mcp/ARCHITECTURE.adoc similarity index 81% rename from elixir-mcp/ARCHITECTURE.md rename to elixir-mcp/ARCHITECTURE.adoc index 8fe0b94..be6a06c 100644 --- a/elixir-mcp/ARCHITECTURE.md +++ b/elixir-mcp/ARCHITECTURE.adoc @@ -1,22 +1,28 @@ - -# feedback-o-tron Architecture +== feedback-o-tron Architecture -> **Note**: This document was originally authored for a planned "Observatory" GitHub Intelligence Platform. Much of the component analysis below (Oxigraph, Julia analytics, Nickel config) describes **aspirational/future** capabilities that are not part of the current feedback-o-tron implementation. The current implementation is an autonomous multi-platform bug reporting system. See [README.adoc](../README.adoc) for the actual feature set. +____ +*Note*: This document was originally authored for a planned +"`Observatory`" GitHub Intelligence Platform. Much of the component +analysis below (Oxigraph, Julia analytics, Nickel config) describes +*aspirational/future* capabilities that are not part of the current +feedback-o-tron implementation. The current implementation is an +autonomous multi-platform bug reporting system. See +link:../README.adoc[README.adoc] for the actual feature set. +____ -## Original Vision (Observatory — Future) +=== Original Vision (Observatory — Future) -A comprehensive system for tracking, analyzing, and visualizing GitHub activity across repositories — with local-first data sovereignty, semantic querying, and real-time change tracking. +A comprehensive system for tracking, analyzing, and visualizing GitHub +activity across repositories — with local-first data sovereignty, +semantic querying, and real-time change tracking. -## Architecture Overview +=== Architecture Overview -``` +.... ┌─────────────────────────────────────────────────────────────────────────────┐ │ User Interfaces │ ├─────────────────────────────────────────────────────────────────────────────┤ -│ ReScript-Tea Web UI │ CLI (Elixir escript) │ Claude MCP Integration │ +│ AffineScript-Tea Web UI │ CLI (Elixir escript) │ Claude MCP Integration │ └─────────────────────────────────────────────────────────────────────────────┘ │ ┌─────────────────────────────────────────────────────────────────────────────┐ @@ -39,42 +45,39 @@ A comprehensive system for tracking, analyzing, and visualizing GitHub activity ┌─────────────────────────────────────────────────────────────────────────────┐ │ Configuration Layer │ ├─────────────────────────────────────────────────────────────────────────────┤ -│ Nickel schemas → JSON, TOML, Nix, Guix SCM outputs │ +│ Nickel schemas → JSON, TOML, Guix, Guix SCM outputs │ └─────────────────────────────────────────────────────────────────────────────┘ │ ┌─────────────────────────────────────────────────────────────────────────────┐ │ Packaging │ ├─────────────────────────────────────────────────────────────────────────────┤ -│ nerdctl + Wolfi OCI │ Guix channel (primary) │ Nix flake (fallback) │ +│ nerdctl + Wolfi OCI │ Guix channel (primary) │ Guix flake (fallback) │ └─────────────────────────────────────────────────────────────────────────────┘ -``` +.... -## Component Decisions +=== Component Decisions -### 1. Core Engine: Elixir (keep) +==== 1. Core Engine: Elixir (keep) -**Rationale:** -- OTP supervision for reliability -- Native pattern matching suits Datalog -- Excellent HTTP clients (Req), JSON (Jason) -- You know it (NeuroPhone) -- Hot code reload for live updates +*Rationale:* - OTP supervision for reliability - Native pattern matching +suits Datalog - Excellent HTTP clients (Req), JSON (Jason) - You know it +(NeuroPhone) - Hot code reload for live updates -**Alternative considered:** Rust with Tokio — faster, but loses OTP ergonomics and hot reload. +*Alternative considered:* Rust with Tokio — faster, but loses OTP +ergonomics and hot reload. -### 2. RDF Store: Oxigraph (instead of Virtuoso) +==== 2. RDF Store: Oxigraph (instead of Virtuoso) -**Rationale:** -- Pure Rust, single binary, embeddable -- Full SPARQL 1.1 support -- Lighter than Virtuoso (no Java, no complex setup) -- Fits your Rust preference -- Can run as subprocess or embedded via NIF +*Rationale:* - Pure Rust, single binary, embeddable - Full SPARQL 1.1 +support - Lighter than Virtuoso (no Java, no complex setup) - Fits your +Rust preference - Can run as subprocess or embedded via NIF -**Virtuoso would require:** Java runtime, complex config, more resources. +*Virtuoso would require:* Java runtime, complex config, more resources. -**Schema:** We map GitHub concepts to RDF: -```turtle +*Schema:* We map GitHub concepts to RDF: + +[source,turtle] +---- @prefix gh: . @prefix schema: . @@ -85,61 +88,54 @@ gh:issue/12114 a gh:Issue ; gh:label "bug", "memory" ; gh:relatedTo gh:issue/10839 ; gh:affectsComponent gh:component/session_management . -``` +---- -### 3. Configuration: Nickel +==== 3. Configuration: Nickel -**Rationale:** -- Typed configuration language -- Can output JSON, TOML, Nix, and with adapters: Guix SCM -- Contracts for validation -- Merging/inheritance for repo-specific overrides +*Rationale:* - Typed configuration language - Can output JSON, TOML, +Guix, and with adapters: Guix SCM - Contracts for validation - +Merging/inheritance for repo-specific overrides -### 4. Analytics: Julia +==== 4. Analytics: Julia -**Rationale:** -- Excellent for statistical analysis -- DataFrames.jl for tabular data -- Plots.jl / Makie.jl for visualization -- Can generate static reports or run as HTTP service +*Rationale:* - Excellent for statistical analysis - DataFrames.jl for +tabular data - Plots.jl / Makie.jl for visualization - Can generate +static reports or run as HTTP service -**Interface:** Elixir calls Julia via: -- Option A: HTTP (Julia runs as Genie.jl service) -- Option B: Subprocess with JSON stdin/stdout -- Option C: Ports with MessagePack (faster) +*Interface:* Elixir calls Julia via: - Option A: HTTP (Julia runs as +Genie.jl service) - Option B: Subprocess with JSON stdin/stdout - Option +C: Ports with MessagePack (faster) -### 5. Frontend: ReScript-Tea +==== 5. Frontend: AffineScript-Tea -**Rationale:** -- Type-safe -- Elm architecture (TEA) for predictable state -- Compiles to small JS bundles -- You specified it +*Rationale:* - Type-safe - Elm architecture (TEA) for predictable state +- Compiles to small JS bundles - You specified it -**Alternative considered:** Elm itself — but ReScript has better JS interop. +*Alternative considered:* Elm itself — but AffineScript has better JS +interop. -### 6. Change Tracking: GitHub Webhooks + Polling Hybrid +==== 6. Change Tracking: GitHub Webhooks + Polling Hybrid -**Mechanism:** -1. **Webhooks** for repos you control (instant) -2. **Polling** with ETags for external repos (rate-limit friendly) -3. **GraphQL subscriptions** where available +*Mechanism:* 1. *Webhooks* for repos you control (instant) 2. *Polling* +with ETags for external repos (rate-limit friendly) 3. *GraphQL +subscriptions* where available Elixir GenServer manages subscription state, debounces, deduplicates. -### 7. Packaging: nerdctl + Wolfi (primary), Guix channel, Nix fallback +==== 7. Packaging: nerdctl + Wolfi (primary), Guix channel, Guix fallback -**Why this order:** -- **Wolfi** is security-focused, minimal, apk-based — good for OCI -- **nerdctl** is rootless containerd (Podman-like, your preference) -- **Guix** for reproducible, auditable builds (your preference for provenance) -- **Nix** as fallback for ecosystems where Guix packages lag +*Why this order:* - *Wolfi* is security-focused, minimal, apk-based — +good for OCI - *nerdctl* is rootless containerd (Podman-like, your +preference) - *Guix* for reproducible, auditable builds (your preference +for provenance) - *Guix* as fallback for ecosystems where Guix packages +lag -## Detailed Component Specs +=== Detailed Component Specs -### Nickel Configuration Schema +==== Nickel Configuration Schema -```nickel +[source,nickel] +---- # observatory.ncl let Config = { github : { @@ -208,11 +204,12 @@ in # Generate Guix service definition ..., } -``` +---- -### Julia Analytics Module +==== Julia Analytics Module -```julia +[source,julia] +---- # analytics/src/Observatory.jl module Observatory @@ -299,11 +296,12 @@ function serve(port::Int=8787) end end # module -``` +---- -### ReScript-Tea Frontend Structure +==== AffineScript-Tea Frontend Structure -```rescript +[source,affinescript] +---- // src/App.res module App = { type model = { @@ -385,11 +383,12 @@ module App = { } } -``` +---- -### Multi-Repo Scraper +==== Multi-Repo Scraper -```elixir +[source,elixir] +---- # lib/gh_manage/scraper.ex defmodule GhManage.Scraper do @moduledoc """ @@ -595,11 +594,12 @@ defmodule GhManage.Scraper do end end end -``` +---- -### Subscription Manager (Webhooks + Polling) +==== Subscription Manager (Webhooks + Polling) -```elixir +[source,elixir] +---- # lib/gh_manage/subscriptions.ex defmodule GhManage.Subscriptions do @moduledoc """ @@ -745,13 +745,14 @@ defmodule GhManage.Subscriptions do event_atom in subscribed_events end end -``` +---- -## Packaging +=== Packaging -### Wolfi/nerdctl Container +==== Wolfi/nerdctl Container -```dockerfile +[source,dockerfile] +---- # Dockerfile.wolfi FROM cgr.dev/chainguard/wolfi-base @@ -785,11 +786,12 @@ VOLUME ["/app/config", "/app/data"] EXPOSE 4000 8080 8787 CMD ["./bin/gh_manage", "start"] -``` +---- -### Guix Channel +==== Guix Channel -```scheme +[source,scheme] +---- ;; guix/observatory/packages.scm (define-module (observatory packages) #:use-module (guix packages) @@ -844,12 +846,13 @@ change tracking.") observatory-shepherd-service))) (default-value (observatory-configuration)) (description "Run the Observatory GitHub intelligence platform."))) -``` +---- -### Nix Flake (Fallback) +==== Guix Flake (Fallback) -```nix -# flake.nix +[source,guix] +---- +# flake.guix { description = "Observatory - GitHub Intelligence Platform"; @@ -880,12 +883,12 @@ change tracking.") pname = "observatory"; version = "0.1.0"; src = ./.; - mixNixDeps = import ./deps.nix { inherit pkgs; }; + mixNixDeps = import ./deps.guix { inherit pkgs; }; }; devShells.default = pkgs.mkShell { buildInputs = observatoryDeps ++ [ - pkgs.nodePackages.npm # For ReScript build + pkgs.nodePackages.npm # For AffineScript build pkgs.nerdctl ]; @@ -925,57 +928,66 @@ change tracking.") } ); } -``` - -## What's Built vs TODO - -### ✅ Complete (this session) - -| Component | Status | -|-----------|--------| -| Elixir MCP Server | Core structure, tool definitions | -| Elixir GitHub Client | Full CRUD for issues, PRs, branches, releases | -| Elixir Datalog Store | ETS-backed with indexing | -| Elixir Datalog Evaluator | Bottom-up with unification | -| Elixir Datalog Rules | Relationship, pattern, component rules | -| Elixir Analysis Module | Ingestion, similarity, all analysis types | -| Elixir Scraper | Multi-repo with rate limiting | -| Elixir Subscriptions | Webhook + polling hybrid | -| Architecture Document | This file | - -### 🔧 TODO (implementation needed) - -| Component | Effort | Notes | -|-----------|--------|-------| -| Nickel config schema | 2h | Write full schema with outputs | -| Oxigraph integration | 4h | NIF or HTTP bridge to Rust binary | -| Julia analytics module | 3h | Implement Observatory.jl | -| ReScript-Tea frontend | 8h | Full UI with charts | -| Elixir HTTP API | 2h | Bandit + REST endpoints | -| Container build | 2h | Wolfi Dockerfile | -| Guix channel | 3h | Package definitions | -| Nix flake | 2h | Module + overlay | -| Ada integration | 4h | Keep for SPARK-verified core types if desired | - -### 🤔 Open Design Questions - -1. **Oxigraph vs in-memory Datalog**: Do you want full RDF/SPARQL, or is the Elixir Datalog sufficient? Oxigraph adds complexity but enables standard semantic web tooling. - -2. **Julia integration method**: HTTP service (always running) or subprocess (on-demand)? HTTP is faster for repeated queries but uses more resources. - -3. **Ada role**: Keep Ada for SPARK-verified types that Elixir calls via ports? Or consolidate everything in Elixir? - -4. **GitLab support**: You prefer GitLab — should we abstract the VCS layer to support both GitHub and GitLab APIs? - -5. **Local-first vs cloud**: Should the frontend be a local Tauri app, or a web service? - -## Recommended Next Steps - -1. **Finish Elixir core** - Add HTTP API, test MCP integration -2. **Nickel config** - Define schema, test outputs -3. **Julia analytics** - Implement contribution stats -4. **Container** - Build Wolfi image, test locally -5. **Frontend** - Scaffold ReScript-Tea, connect to API -6. **Guix/Nix** - Package for reproducible deployment +---- + +=== What’s Built vs TODO + +==== ✅ Complete (this session) + +[cols=",",options="header",] +|=== +|Component |Status +|Elixir MCP Server |Core structure, tool definitions +|Elixir GitHub Client |Full CRUD for issues, PRs, branches, releases +|Elixir Datalog Store |ETS-backed with indexing +|Elixir Datalog Evaluator |Bottom-up with unification +|Elixir Datalog Rules |Relationship, pattern, component rules +|Elixir Analysis Module |Ingestion, similarity, all analysis types +|Elixir Scraper |Multi-repo with rate limiting +|Elixir Subscriptions |Webhook + polling hybrid +|Architecture Document |This file +|=== + +==== 🔧 TODO (implementation needed) + +[cols=",,",options="header",] +|=== +|Component |Effort |Notes +|Nickel config schema |2h |Write full schema with outputs +|Oxigraph integration |4h |NIF or HTTP bridge to Rust binary +|Julia analytics module |3h |Implement Observatory.jl +|AffineScript-Tea frontend |8h |Full UI with charts +|Elixir HTTP API |2h |Bandit + REST endpoints +|Container build |2h |Wolfi Dockerfile +|Guix channel |3h |Package definitions +|Guix flake |2h |Module + overlay +|Ada integration |4h |Keep for SPARK-verified core types if desired +|=== + +==== 🤔 Open Design Questions + +[arabic] +. *Oxigraph vs in-memory Datalog*: Do you want full RDF/SPARQL, or is +the Elixir Datalog sufficient? Oxigraph adds complexity but enables +standard semantic web tooling. +. *Julia integration method*: HTTP service (always running) or +subprocess (on-demand)? HTTP is faster for repeated queries but uses +more resources. +. *Ada role*: Keep Ada for SPARK-verified types that Elixir calls via +ports? Or consolidate everything in Elixir? +. *GitLab support*: You prefer GitLab — should we abstract the VCS layer +to support both GitHub and GitLab APIs? +. *Local-first vs cloud*: Should the frontend be a local Tauri app, or a +web service? + +=== Recommended Next Steps + +[arabic] +. *Finish Elixir core* - Add HTTP API, test MCP integration +. *Nickel config* - Define schema, test outputs +. *Julia analytics* - Implement contribution stats +. *Container* - Build Wolfi image, test locally +. *Frontend* - Scaffold AffineScript-Tea, connect to API +. *Guix/Guix* - Package for reproducible deployment Want me to continue with any specific component? diff --git a/elixir-mcp/README.md b/elixir-mcp/README.adoc similarity index 73% rename from elixir-mcp/README.md rename to elixir-mcp/README.adoc index 459a747..5f766c7 100644 --- a/elixir-mcp/README.md +++ b/elixir-mcp/README.adoc @@ -1,26 +1,25 @@ - -# Observatory +== Observatory -**GitHub Intelligence Platform** — Track, analyze, and visualize GitHub activity with local-first data sovereignty. +*GitHub Intelligence Platform* — Track, analyze, and visualize GitHub +activity with local-first data sovereignty. -## Features +=== Features -- **MCP Integration** — Use with Claude for intelligent issue management -- **Elixir MCP Server** — JSON-RPC 2.0 over stdio via elixir-mcp-server -- **Datalog Analysis** — Derive relationships, detect patterns, find regressions -- **Multi-Repo Scraping** — Track many repositories with rate limiting -- **Change Subscriptions** — Webhooks + polling for real-time updates -- **Julia Analytics** — Statistical analysis of contribution patterns -- **ReScript-Tea Frontend** — Type-safe web visualization (planned) -- **Semantic Storage** — Oxigraph RDF/SPARQL (optional) -- **Reproducible Builds** — Guix channel + Nix flake + Wolfi containers +* *MCP Integration* — Use with Claude for intelligent issue management +* *Elixir MCP Server* — JSON-RPC 2.0 over stdio via elixir-mcp-server +* *Datalog Analysis* — Derive relationships, detect patterns, find +regressions +* *Multi-Repo Scraping* — Track many repositories with rate limiting +* *Change Subscriptions* — Webhooks + polling for real-time updates +* *Julia Analytics* — Statistical analysis of contribution patterns +* *AffineScript-Tea Frontend* — Type-safe web visualization (planned) +* *Semantic Storage* — Oxigraph RDF/SPARQL (optional) +* *Reproducible Builds* — Guix channel + Guix flake + Wolfi containers -## Quick Start +=== Quick Start -```bash +[source,bash] +---- # Clone git clone https://gitlab.com/jdajewell/observatory cd observatory @@ -50,15 +49,16 @@ FEEDBACK_A_TRON_MCP=1 FEEDBACK_A_TRON_MCP_TCP=1 \ # TCP smoke test (defaults to 127.0.0.1:844) MCP_PORT=844 scripts/mcp_tcp_smoke_test.sh -``` +---- -## Usage +=== Usage -### With Claude (MCP) +==== With Claude (MCP) Add to your Claude Code MCP configuration: -```json +[source,json] +---- { "mcpServers": { "observatory": { @@ -67,19 +67,20 @@ Add to your Claude Code MCP configuration: } } } -``` +---- Then ask Claude things like: -- "Search for issues about session sync in claude-code" -- "Create a bug report for the archive persistence issue" -- "Find issues related to #12114" -- "What are the component hotspots in this repo?" -- "Show me state sync issues" +* "`Search for issues about session sync in claude-code`" +* "`Create a bug report for the archive persistence issue`" +* "`Find issues related to #12114`" +* "`What are the component hotspots in this repo?`" +* "`Show me state sync issues`" -### Command Line +==== Command Line -```bash +[source,bash] +---- # Create issues interactively gh-manage issue bug gh-manage issue feature @@ -106,13 +107,14 @@ gh-manage stats hotspots # Raw Datalog queries gh-manage datalog "related(12114, Y, Reason)" -``` +---- -## Configuration +=== Configuration -### Nickel (Recommended) +==== Nickel (Recommended) -```nickel +[source,nickel] +---- # config/local.ncl let schema = import "./schema.ncl" in @@ -140,30 +142,32 @@ schema.make_config { default_repo = "anthropics/claude-code", }, } 'json -``` +---- Generate different formats: -```bash +[source,bash] +---- nickel export config/local.ncl --format json > config.json nickel eval config/local.ncl -- to_elixir_config > config/runtime.exs nickel eval config/local.ncl -- to_env_file > .env nickel eval config/local.ncl -- to_guix_service > guix/service.scm -``` +---- -### Environment Variables +==== Environment Variables -```bash +[source,bash] +---- GITHUB_TOKEN=ghp_xxxx GITHUB_API_URL=https://api.github.com # or GitHub Enterprise URL OBSERVATORY_DEFAULT_REPO=anthropics/claude-code OBSERVATORY_SQLITE_PATH=./data/observatory.db OBSERVATORY_POLL_INTERVAL=300 -``` +---- -## Architecture +=== Architecture -``` +.... ┌──────────────────────────────────────────────────────────────┐ │ Interfaces │ │ CLI (escript) │ MCP Server │ REST API │ Web UI │ @@ -182,13 +186,14 @@ OBSERVATORY_POLL_INTERVAL=300 │ Oxigraph │ │ SQLite │ │ Julia Engine │ │ RDF/SPARQL│ │ Timeline │ │ Statistics │ └──────────┘ └──────────┘ └──────────────┘ -``` +.... -## Datalog Analysis +=== Datalog Analysis The Datalog engine derives relationships and patterns from GitHub data: -```prolog +[source,prolog] +---- % Find related issues ?- related(12114, Y, Reason). % Returns: Y=10839 (same_component), Y=8667 (mentions), ... @@ -204,24 +209,34 @@ The Datalog engine derives relationships and patterns from GitHub data: % Component hotspots ?- component_hotspot(Component, Count). % Returns: session_management=42, mcp_integration=18, ... -``` +---- -### Available Rules +==== Available Rules -| Rule | Description | -|------|-------------| -| `related(X, Y, Reason)` | Issues X and Y are related (mentions, same_component, same_label) | -| `state_sync_issue(X)` | Issue X is about state synchronization | -| `regression(X)` | Issue X was closed then reopened | -| `fix_caused_regression(PR, Fixed, Broke)` | PR fixed one issue but caused another | -| `potentially_duplicate(X, Y)` | High similarity between X and Y | -| `component_hotspot(C, N)` | Component C has N+ issues | +[width="100%",cols="32%,68%",options="header",] +|=== +|Rule |Description +|`+related(X, Y, Reason)+` |Issues X and Y are related (mentions, +same_component, same_label) -## Julia Analytics +|`+state_sync_issue(X)+` |Issue X is about state synchronization + +|`+regression(X)+` |Issue X was closed then reopened + +|`+fix_caused_regression(PR, Fixed, Broke)+` |PR fixed one issue but +caused another + +|`+potentially_duplicate(X, Y)+` |High similarity between X and Y + +|`+component_hotspot(C, N)+` |Component C has N+ issues +|=== + +=== Julia Analytics Statistical analysis of contribution patterns: -```julia +[source,julia] +---- using Observatory # Load events @@ -236,19 +251,21 @@ generate_charts(stats, "./charts") # Repo stats repo_stats = compute_repo_stats(events, "anthropics/claude-code") -``` +---- Run as service: -```bash +[source,bash] +---- julia analytics/src/Observatory.jl serve 8787 -``` +---- -## Packaging +=== Packaging -### Container (Wolfi + nerdctl) +==== Container (Wolfi + nerdctl) -```bash +[source,bash] +---- # Build nerdctl build -t observatory:latest -f Dockerfile.wolfi . @@ -259,11 +276,12 @@ nerdctl run -d \ -p 4000:4000 \ -p 8080:8080 \ observatory:latest -``` +---- -### Guix +==== Guix -```bash +[source,bash] +---- # Add channel guix pull --channels=./guix/channels.scm @@ -272,27 +290,29 @@ guix install observatory # Or use as service guix system reconfigure config.scm -``` +---- -### Nix +==== Guix -```bash +[source,bash] +---- # Development shell -nix develop +guix develop # Build -nix build +guix build # NixOS module { - imports = [ ./flake.nix#nixosModules.default ]; + imports = [ ./flake.guix#nixosModules.default ]; services.observatory.enable = true; } -``` +---- -## Development +=== Development -```bash +[source,bash] +---- # Run tests mix test @@ -307,11 +327,11 @@ mix format # Generate docs mix docs -``` +---- -### Project Structure +==== Project Structure -``` +.... observatory/ ├── lib/ │ └── gh_manage/ @@ -333,28 +353,29 @@ observatory/ │ └── Observatory.jl # Julia analytics ├── config/ │ └── schema.ncl # Nickel config schema -├── frontend/ # ReScript-Tea (planned) +├── frontend/ # AffineScript-Tea (planned) ├── guix/ # Guix channel ├── mix.exs -├── flake.nix +├── flake.guix └── ARCHITECTURE.md -``` +.... -## License +=== License MPL-2.0 -## Contributing +=== Contributing -1. Fork on GitLab -2. Create feature branch -3. Make changes -4. Run tests: `mix test` -5. Submit merge request +[arabic] +. Fork on GitLab +. Create feature branch +. Make changes +. Run tests: `+mix test+` +. Submit merge request -## Acknowledgments +=== Acknowledgments -- Built with Elixir/OTP -- Datalog inspired by Datalog Educational System -- Configuration via Nickel -- Analytics via Julia +* Built with Elixir/OTP +* Datalog inspired by Datalog Educational System +* Configuration via Nickel +* Analytics via Julia diff --git a/examples/web-project-deno.json b/examples/web-project-deno.json index 5ddd3bd..ee775a4 100644 --- a/examples/web-project-deno.json +++ b/examples/web-project-deno.json @@ -1,17 +1,17 @@ { - "// NOTE": "Example deno.json for ReScript web projects", + "// NOTE": "Example deno.json for AffineScript web projects", "tasks": { - "build": "deno run -A npm:rescript", - "clean": "deno run -A npm:rescript clean", - "watch": "deno run -A npm:rescript -w", + "build": "deno run -A npm:affinescript", + "clean": "deno run -A npm:affinescript clean", + "watch": "deno run -A npm:affinescript -w", "serve": "deno run -A jsr:@std/http/file-server .", "test": "deno test --allow-all" }, "imports": { - "rescript": "^12.0.0", - "@rescript/core": "npm:@rescript/core@^1.6.0", - "safe-dom/": "https://raw.githubusercontent.com/hyperpolymath/rescript-dom-mounter/main/src/", - "proven/": "../proven/bindings/rescript/src/" + "affinescript": "^12.0.0", + "@affinescript/core": "npm:@affinescript/core@^1.6.0", + "safe-dom/": "https://raw.githubusercontent.com/hyperpolymath/affinescript-dom-mounter/main/src/", + "proven/": "../proven/bindings/affinescript/src/" }, "compilerOptions": { "allowJs": true, diff --git a/llm-warmup-dev.adoc b/llm-warmup-dev.adoc new file mode 100644 index 0000000..f68d0af --- /dev/null +++ b/llm-warmup-dev.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — feedback-o-tron (Developer) + +=== What is feedback-o-tron? + +See README.adoc for overview. + +=== Key Commands + +* `+just setup+` — set up development environment +* `+just build+` — build the project +* `+just test+` — run tests +* `+just doctor+` — diagnose issues +* `+just heal+` — attempt auto-repair + +=== Quick Context + +* License: MPL-2.0 +* Part of hyperpolymath ecosystem +* See EXPLAINME.adoc for architecture diff --git a/llm-warmup-dev.md b/llm-warmup-dev.md deleted file mode 100644 index c12b3bd..0000000 --- a/llm-warmup-dev.md +++ /dev/null @@ -1,20 +0,0 @@ - -# LLM Warmup — feedback-o-tron (Developer) - -## What is feedback-o-tron? -See README.adoc for overview. - -## Key Commands -- `just setup` — set up development environment -- `just build` — build the project -- `just test` — run tests -- `just doctor` — diagnose issues -- `just heal` — attempt auto-repair - -## Quick Context -- License: MPL-2.0 -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture diff --git a/llm-warmup-user.adoc b/llm-warmup-user.adoc new file mode 100644 index 0000000..d674b77 --- /dev/null +++ b/llm-warmup-user.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — feedback-o-tron (User) + +=== What is feedback-o-tron? + +See README.adoc for overview. + +=== Key Commands + +* `+just setup+` — set up development environment +* `+just build+` — build the project +* `+just test+` — run tests +* `+just doctor+` — diagnose issues +* `+just heal+` — attempt auto-repair + +=== Quick Context + +* License: MPL-2.0 +* Part of hyperpolymath ecosystem +* See EXPLAINME.adoc for architecture diff --git a/llm-warmup-user.md b/llm-warmup-user.md deleted file mode 100644 index d5886c7..0000000 --- a/llm-warmup-user.md +++ /dev/null @@ -1,20 +0,0 @@ - -# LLM Warmup — feedback-o-tron (User) - -## What is feedback-o-tron? -See README.adoc for overview. - -## Key Commands -- `just setup` — set up development environment -- `just build` — build the project -- `just test` — run tests -- `just doctor` — diagnose issues -- `just heal` — attempt auto-repair - -## Quick Context -- License: MPL-2.0 -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture diff --git a/tasks/Justfile b/tasks/Justfile index f907911..fc40479 100644 --- a/tasks/Justfile +++ b/tasks/Justfile @@ -1,4 +1,4 @@ -# feedback-a-tron - Nix Development Tasks +# feedback-a-tron - Guix Development Tasks set shell := ["bash", "-uc"] set dotenv-load := true @@ -8,35 +8,35 @@ project := "feedback-a-tron" default: @just --list --unsorted -# Build with nix +# Build with guix build: - nix build + guix build # Build and show output path build-show: - nix build --print-out-paths + guix build --print-out-paths # Enter dev shell develop: - nix develop + guix develop # Check flake check: - nix flake check + guix flake check # Update flake inputs update: - nix flake update + guix flake update # Show flake info info: - nix flake info + guix flake info -# Format nix files +# Format guix files fmt: - nixfmt *.nix || nix fmt + nixfmt *.guix || guix fmt -# Run nix linter +# Run guix linter lint: statix check . || true @@ -46,7 +46,7 @@ clean: # Show derivation show-drv: - nix derivation show + guix derivation show # All checks before commit pre-commit: check