From 7e702ed8483d22021a4b4985ad4c28afcd04a63a Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Sat, 19 Sep 2026 08:59:55 +0000 Subject: [PATCH] refactor(root): move root artefacts to their canonical locations Applies the estate root-shape rollout: files that are not root-level by necessity move to where their tooling and the estate canon expect them, and every reference to them is updated in the same change. * .github/hooks/validate-a2ml.sh (from .githooks/validate-a2ml.sh) -> .github/hooks/validate-a2ml.sh * .github/hooks/validate-k9.sh (from .githooks/validate-k9.sh) -> .github/hooks/validate-k9.sh * .github/workflows/dogfood-gate.yml * .github/CONTRIBUTING.md (new) * CONTRIBUTING.adoc (deleted) * scripts/rsr_compliance_check.sh Verified with `git apply --check` against current main before committing; no behaviour change intended, the Justfile entry points keep working. --- .github/CONTRIBUTING.md | 664 ++++++++++++++++++ {.githooks => .github/hooks}/validate-a2ml.sh | 0 {.githooks => .github/hooks}/validate-k9.sh | 0 .github/workflows/dogfood-gate.yml | 4 +- CONTRIBUTING.adoc | 562 --------------- scripts/rsr_compliance_check.sh | 4 +- 6 files changed, 668 insertions(+), 566 deletions(-) create mode 100644 .github/CONTRIBUTING.md rename {.githooks => .github/hooks}/validate-a2ml.sh (100%) rename {.githooks => .github/hooks}/validate-k9.sh (100%) delete mode 100644 CONTRIBUTING.adoc diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 0000000..246ea7c --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,664 @@ +# Contributing to Anamnesis + +Thank you for your interest in contributing to Anamnesis! This document +provides guidelines for contributing to the project. + +## Table of Contents + +- [Code of Conduct](#code-of-conduct) + +- [TPCF Perimeter Classification](#tpcf-perimeter-classification) + +- [How to Contribute](#how-to-contribute) + +- [Development Setup](#development-setup) + +- [Contribution Workflow](#contribution-workflow) + +- [Coding Standards](#coding-standards) + +- [Testing Requirements](#testing-requirements) + +- [Documentation](#documentation) + +- [Commit Messages](#commit-messages) + +- [Pull Request Process](#pull-request-process) + +- [Review Process](#review-process) + +- [Community](#community) + +## Code of Conduct + +This project adheres to a Code of Conduct based on **CCCP (Compassionate +Code Conduct Pledge)** principles. Please read CODE_OF_CONDUCT.md before +contributing. + +**Key Points:** - Be respectful and considerate - Prioritize emotional +safety over efficiency - Assume good faith - Embrace reversibility and +experimentation - No harassment, discrimination, or aggressive behavior + +## TPCF Perimeter Classification + +**Current Classification: Perimeter 2 - Trusted Collaborators** + +### What This Means + +**Perimeter 2** is a graduated trust model designed for research-grade +projects with technical complexity: + +- **Read Access**: Public (anyone can clone, fork, study) + +- **Write Access**: Maintainers + approved collaborators only + +- **Admin Access**: Project owner (Hyperpolymath) + +### Access Levels + + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Level

Permissions

Requirements

Public

Read, fork, open issues

None (open source)

Contributor

Submit PRs (reviewed before merge)

Signed Contributor Agreement, 1+ merged PR

Collaborator

Direct push to feature branches

3+ merged PRs, technical expertise, maintainer approval

Maintainer

Push to main, release management

10+ merged PRs, 6
+months activity, MAINTAINERS.md vote

Admin

Repository settings, security

Project founder(s) only

+ +### Why Perimeter 2? + +Anamnesis is currently: - **Research-grade** (not production-ready) - +**Multi-language complexity** (OCaml, Elixir, Julia, λProlog, +AffineScript) - **Experimental** (testing novel approaches) - +**Pre-Milestone 1** (foundational phase) + +**Not suitable for**: - Drive-by contributions without context - +Unreviewed direct commits to main - Breaking changes without discussion + +### Migration to Perimeter 3 (Future) + +We’ll move to **Perimeter 3 (Community Sandbox)** when: - \[x\] +Milestone 1 complete (Claude JSON → Virtuoso RDF pipeline working) - \[ +\] CI/CD with automated tests (\>50% coverage) - \[ \] Comprehensive +contributor documentation - \[ \] 3+ active maintainers - \[ \] +Community governance structure established + +## How to Contribute + +### Types of Contributions Welcome + +1. **Bug Reports**: Found an issue? Open a GitHub Issue with details + +2. **Feature Requests**: Suggest improvements via GitHub Discussions + +3. **Code Contributions**: Fix bugs, add features, improve performance + +4. **Documentation**: Fix typos, clarify explanations, add examples + +5. **Testing**: Write tests, improve coverage, report test failures + +6. **Research**: Validate tech choices, benchmark performance, academic + papers + +7. **Design**: UX/UI improvements, architecture proposals + +8. **Community**: Answer questions, help newcomers, organize events + +### Not Ready Yet (But Soon!) + +- **Proving Ground Testing**: Copy zotero-voyant-export, run end-to-end + tests (after Milestone 1) + +- **Additional Format Parsers**: ChatGPT, Mistral, Git logs (OCaml + proficiency required) + +- **Visualization Components**: AffineScript components for Reagraph + (after data pipeline works) + +## Development Setup + +### Prerequisites + +**Language Runtimes:** - **OCaml** 5.0+ (install via +[OPAM](https://opam.ocaml.org/)) - **Elixir** 1.15+ (install via +[asdf](https://asdf-vm.com/) or package manager) - **Julia** 1.10+ +(install via [juliaup](https://github.com/JuliaLang/juliaup)) - +**Node.js** 18+ (for AffineScript) - **Virtuoso** 7+ (Docker +recommended) + +**Build Tools:** - **Dune** 3.0+ (OCaml build system) - **Just** +(command runner - install from ) - +**Guix** (optional, for reproducible builds) + +### Quick Start + +``` bash +# Clone the repository +git clone https://github.com/Hyperpolymath/anamnesis.git +cd anamnesis + +# Setup component dependencies +just setup-all # Runs setup for all components + +# Or setup individually: +cd parser && opam install --deps-only . && dune build +cd orchestrator && mix deps.get && mix compile +cd learning && julia --project=. -e 'using Pkg; Pkg.instantiate()' +cd visualization && npm install && npm run res:build + +# Run tests +just test + +# Verify RSR compliance +just rsr-check +``` + +See component READMEs for detailed setup: - `parser/README.md` - OCaml +parser setup - `orchestrator/README.md` - Elixir orchestrator setup - +`reasoning/README.md` - λProlog/ELPI setup - `learning/README.md` - +Julia analytics setup - `visualization/README.md` - AffineScript +visualization setup + +## Contribution Workflow + +### 1. Before You Start + +- **Check existing issues/PRs**: Avoid duplicate work + +- **Open a discussion**: For major changes, discuss first + +- **Read the architecture**: + `docs/architecture/system-architecture.adoc` + +- **Review research**: `docs/research/` for tech stack decisions + +### 2. Create a Feature Branch + +``` bash +git checkout -b feature/your-feature-name +# or +git checkout -b fix/bug-description +``` + +**Branch Naming Convention:** - `feature/` - New features - `fix/` - Bug +fixes - `docs/` - Documentation only - `test/` - Test additions - +`refactor/` - Code refactoring (no behavior change) - `chore/` - Build +system, dependencies, tooling + +### 3. Make Changes + +- Follow [Coding Standards](#coding-standards) + +- Write tests for new code + +- Update documentation + +- Run `just` `validate` before committing + +### 4. Commit Changes + +See [Commit Messages](#commit-messages) for format. + +``` bash +git add +git commit -m "feat(parser): add ChatGPT format parser + +Implements ChatGPT conversation JSON parsing with: +- Node-based structure handling +- Message tree flattening +- Artifact extraction from code blocks + +Refs #123" +``` + +### 5. Push and Create PR + +``` bash +git push origin feature/your-feature-name +``` + +Then open a Pull Request on GitHub with: - **Title**: Clear, concise +description - **Description**: What, why, how - **Issue reference**: +`Closes` `#123` or `Refs` `#456` - **Checklist**: Tests pass, docs +updated, etc. + +## Coding Standards + +### General Principles + +- **Type Safety**: Leverage static typing in every language + +- **Functional Paradigm**: Prefer pure functions, immutability + +- **Explicit over Implicit**: Clear naming, no magic + +- **Small Functions**: \<50 lines ideally + +- **No Side Effects**: Isolate I/O, mutation, randomness + +- **Error Handling**: Use Result/Option types, not exceptions in hot + paths + +### Language-Specific + +#### OCaml + +- **Style**: Follow [OCaml style + guide](https://ocaml.org/docs/guidelines) + +- **Formatting**: Use `ocamlformat` (config in `.ocamlformat`) + +- **Naming**: `snake_case` for functions/variables, `CamelCase` for + modules + +- **Documentation**: OCamldoc comments for public APIs + +- **No `Obj.magic`**: Avoid unsafe casts + +#### Elixir + +- **Style**: Follow [Elixir style + guide](https://github.com/christopheradams/elixir_style_guide) + +- **Formatting**: Use `mix` `format` (config in `.formatter.exs`) + +- **Naming**: `snake_case` for functions/variables, `CamelCase` for + modules + +- **Documentation**: `@moduledoc` and `@doc` for all public functions + +- **Typespecs**: Add `@spec` for all public functions + +- **Pattern Matching**: Prefer pattern matching over conditionals + +#### Julia + +- **Style**: Follow [Julia style + guide](https://docs.julialang.org/en/v1/manual/style-guide/) + +- **Formatting**: Use `JuliaFormatter.jl` + +- **Naming**: `snake_case` for functions, `CamelCase` for types + +- **Documentation**: Docstrings for all exported functions + +- **Type Stability**: Avoid type-unstable code (use `@code_warntype`) + +#### λProlog (ELPI) + +- **Style**: Consistent indentation (2 spaces) + +- **Naming**: `snake_case` for predicates + +- **Documentation**: Comment clauses, especially complex rules + +- **Modularity**: Separate concerns into different files + +#### AffineScript + +- **Style**: Follow [AffineScript + conventions](https://affinescript-lang.org/docs/manual/latest/introduction) + +- **Formatting**: Use `affinescript` `format` + +- **Naming**: `camelCase` for values/functions, `PascalCase` for + modules/types + +- **Documentation**: JSDoc comments for exported functions + +- **Phantom Types**: Use for ID safety (e.g., `MessageId`, `ArtifactId`) + +## Testing Requirements + +### Minimum Coverage + +- **Bronze Level (RSR)**: 50% coverage required + +- **Silver Level**: 70% coverage + +- **Gold Level**: 85% coverage + +**Current Target**: 50%+ for Milestone 1 completion + +### Test Structure + +#### OCaml (Alcotest + qcheck) + +``` ocaml +(* test/test_claude_parser.ml *) +let test_parse_valid_conversation () = + let json = {|{"uuid": "123", "name": "Test", ...}|} in + match Claude_parser.parse json with + | Ok conv -> + Alcotest.(check string) "conversation id" "123" conv.id + | Error e -> + Alcotest.fail e + +let () = + Alcotest.run "Claude Parser Tests" [ + "parsing", [ + test_case "valid conversation" `Quick test_parse_valid_conversation; + ]; + ] +``` + +#### Elixir (ExUnit) + +``` elixir +# test/anamnesis/ports/parser_port_test.exs +defmodule Anamnesis.Ports.ParserPortTest do + use ExUnit.Case, async: true + + test "parses Claude conversation" do + content = File.read!("test/fixtures/claude_conversation.json") + {:ok, conv} = Anamnesis.Ports.ParserPort.parse(content, :claude) + + assert conv["platform"] == "claude" + assert length(conv["messages"]) > 0 + end +end +``` + +#### Julia (Test.jl) + +``` julia +# test/rdf_tests.jl +using Test +using AnamnesisAnalytics + +@testset "RDF Generation" begin + conv = Dict("id" => "test-123", "messages" => []) + triples = conversation_to_rdf(conv) + + @test length(triples) >= 1 + @test any(t -> t.predicate == RDF.type, triples) +end +``` + +#### AffineScript (Jest) + +``` javascript +// __tests__/ColorMixing.test.js +import { mixColors } from '../src/transforms/ColorMixing.bs.js'; + +test('mixColors returns gray for empty memberships', () => { + expect(mixColors([])).toBe('#999999'); +}); +``` + +### Running Tests + +``` bash +# All tests +just test + +# Component-specific +cd parser && dune runtest +cd orchestrator && mix test +cd learning && julia --project=. test/runtests.jl +cd visualization && npm test +``` + +## Documentation + +### What to Document + +- **Public APIs**: All exported functions, modules, types + +- **Architecture Changes**: Update + `docs/architecture/system-architecture.adoc` + +- **Tech Decisions**: Add to research docs or create new doc in + `docs/guides/` + +- **Examples**: Add code examples for non-trivial features + +- **CHANGELOG.md**: Update for user-facing changes + +### Documentation Formats + +- **AsciiDoc** (`.adoc`): Complex technical documents, architecture + +- **Markdown** (`.md`): READMEs, contribution guides, simple docs + +- **Inline Comments**: Complex algorithms, non-obvious code + +- **API Docs**: Language-specific (OCamldoc, ExDoc, Julia docstrings, + JSDoc) + +### Writing Style + +- **Clear and Concise**: No jargon without explanation + +- **Examples**: Show, don’t just tell + +- **Audience**: Assume technical competence, explain domain-specific + concepts + +- **Grammar**: Use spell-check, but don’t obsess (substance \> + perfection) + +## Commit Messages + +### Format + +Follow [Conventional Commits](https://www.conventionalcommits.org/): + + (): + + + +