diff --git a/.github/workflows/governance.yml b/.github/workflows/governance.yml index cc62f6c..f6e8fcf 100644 --- a/.github/workflows/governance.yml +++ b/.github/workflows/governance.yml @@ -3,7 +3,7 @@ # in hyperpolymath/standards instead of carrying per-repo copies. # # Replaces the per-repo governance scaffolding removed in the same commit: -# quality.yml, guix-nix-policy.yml, npm-bun-blocker.yml, ts-blocker.yml, +# quality.yml, guix-guix-policy.yml, npm-bun-blocker.yml, ts-blocker.yml, # security-policy.yml, rsr-antipattern.yml, wellknown-enforcement.yml, # workflow-linter.yml # diff --git a/.machine_readable/6a2/META.a2ml b/.machine_readable/6a2/META.a2ml index 7d4be5f..dd586e2 100644 --- a/.machine_readable/6a2/META.a2ml +++ b/.machine_readable/6a2/META.a2ml @@ -17,7 +17,7 @@ author = "Jonathan D.A. Jewell (hyperpolymath)" build-tool = "just" container-runtime = "podman" ci-platform = "github-actions" -package-manager = "cargo" # guix.scm / flake.nix also present for reproducible shells +package-manager = "cargo" # guix.scm / flake.guix also present for reproducible shells # ════════════════════════════════════════════════════════════════════════════ # ARCHITECTURE DECISIONS (ADRs) — status: proposed | accepted | superseded | rejected 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..246b1a0 --- /dev/null +++ b/CHANGELOG.adoc @@ -0,0 +1,62 @@ +== Changelog + +All notable changes to `+git-reticulator+` 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(crg): add crg-grade and crg-badge justfile recipes +* feat: wire conflow config validation pipeline +* feat: add k9iser.toml and generate K9 contracts +* feat: add stapeln.toml container definition +* feat: deploy UX Manifesto infrastructure +* feat: git-reticulator — semantic lattice builder for git repos in +AffineScript + +==== Fixed + +* fix(ci): sync hypatia-scan.yml to canonical (413: +env.HOME+Phase-2+SARIF) (#6) +* fix(ci): adopt canonical hypatia-scan.yml (env.HOME/scanner-layout + +Comment-step gate) (#4) +* fix(ci): adopt canonical hypatia-scan.yml (env.HOME/scanner-layout + +Comment-step gate) (#3) +* fix: set correct Groove capability type (was: custom) +* fix(ci): replace casket-pages with standard Jekyll Pages workflow +* fix(deps): update lock files to resolve security advisories +* fix: EXPLAINME.adoc — quote README claims, brief format, evidence +table + +==== Documentation + +* docs(readme): add SPDX header, OSSF and GWF badges +* docs: add TOPOLOGY.md + +==== CI + +* ci(rust): convert rust-ci.yml to thin wrapper (standards#174) (#11) +* ci(deps): add Dependabot config to surface Rust security alerts +* ci: deploy dogfood-gate, add Groove manifest and CRG tests + +=== 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 2f37382..0000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,57 +0,0 @@ - - -# Changelog - -All notable changes to `git-reticulator` 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(crg): add crg-grade and crg-badge justfile recipes -- feat: wire conflow config validation pipeline -- feat: add k9iser.toml and generate K9 contracts -- feat: add stapeln.toml container definition -- feat: deploy UX Manifesto infrastructure -- feat: git-reticulator — semantic lattice builder for git repos in AffineScript - -### Fixed - -- fix(ci): sync hypatia-scan.yml to canonical (413: env.HOME+Phase-2+SARIF) (#6) -- fix(ci): adopt canonical hypatia-scan.yml (env.HOME/scanner-layout + Comment-step gate) (#4) -- fix(ci): adopt canonical hypatia-scan.yml (env.HOME/scanner-layout + Comment-step gate) (#3) -- fix: set correct Groove capability type (was: custom) -- fix(ci): replace casket-pages with standard Jekyll Pages workflow -- fix(deps): update lock files to resolve security advisories -- fix: EXPLAINME.adoc — quote README claims, brief format, evidence table - -### Documentation - -- docs(readme): add SPDX header, OSSF and GWF badges -- docs: add TOPOLOGY.md - -### CI - -- ci(rust): convert rust-ci.yml to thin wrapper (standards#174) (#11) -- ci(deps): add Dependabot config to surface Rust security alerts -- ci: deploy dogfood-gate, add Groove manifest and CRG tests - -## 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..ff3f3db --- /dev/null +++ b/CODE_OF_CONDUCT.adoc @@ -0,0 +1,339 @@ +== Code of Conduct + +=== Our Pledge + +We as members, contributors, and leaders pledge to make participation in +Squisher Corpus 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, caste, colour, 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. + +We recognise that a thriving open source community requires +*psychological safety* — an environment where people can contribute, ask +questions, make mistakes, and learn without fear of ridicule or +retaliation. + +''''' + +=== Our Standards + +==== Expected Behaviour + +The following behaviours contribute to a positive environment: + +*Communication* - Using welcoming and inclusive language - Being +respectful of differing viewpoints and experiences - Giving and +gracefully accepting constructive feedback - Assuming good intent while +addressing impact - Communicating clearly and patiently, especially with +newcomers + +*Collaboration* - Focusing on what is best for the community - Showing +empathy and kindness toward other community members - Being +collaborative rather than competitive - Mentoring and supporting less +experienced contributors - Celebrating others’ contributions and +successes + +*Professionalism* - Accepting responsibility and apologising to those +affected by our mistakes - Learning from the experience and avoiding +repetition - Respecting others’ time and attention - Staying on topic in +project spaces - Following project guidelines and conventions + +*Accessibility* - Using plain language and avoiding unnecessary jargon - +Providing alt text for images and transcripts for audio/video - Being +patient with those using assistive technologies - Accommodating +different communication styles and needs - Recognising that not everyone +communicates the same way + +==== Unacceptable Behaviour + +The following behaviours are considered harassment and are unacceptable: + +*Harassment* - The use of sexualised 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 - Deliberate intimidation, stalking, or following (online or +in-person) - Unwelcome physical contact or simulated physical contact +(e.g., emoji) - Sustained disruption of talks, events, or online +discussions + +*Discrimination* - Discriminatory jokes and language - Posting or +threatening to post others’ personally identifying information +("`doxing`") - Advocating for, or encouraging, any of the above +behaviour - Microaggressions — subtle, often unintentional, +discriminatory comments or actions + +*Professional Misconduct* - Publishing others’ private information +without explicit permission - Misrepresenting affiliation or +contributions - Plagiarism or claiming credit for others’ work - +Retaliating against anyone who reports a Code of Conduct violation - +Other conduct which could reasonably be considered inappropriate in a +professional setting + +==== Grey Areas + +Some situations require judgement. When uncertain: + +* *Intent vs Impact*: Good intentions do not excuse harmful impact. +Focus on making things right. +* *Power Dynamics*: Those with more power (maintainers, employers, +experienced contributors) must be especially mindful of their impact. +* *Cultural Differences*: What’s acceptable varies by culture. When in +doubt, err on the side of caution and ask. +* *Humour*: Jokes at others’ expense are rarely funny to everyone. Punch +up, not down. + +''''' + +=== Scope + +This Code of Conduct applies within all community spaces, including: + +*Online Spaces* - Repository discussions, issues, and pull/merge +requests - Project chat channels (Matrix, Discord, Slack, IRC) - Mailing +lists and forums - Social media when representing the project - Video +calls and virtual meetings + +*In-Person Spaces* - Conferences, meetups, and events - Workshops and +training sessions - Any gathering where you represent the project + +*Representation* This Code of Conduct also applies when an individual is +officially representing the community in public spaces. Examples +include: + +* Using an official project email address +* Posting via an official social media account +* Acting as an appointed representative at an event +* Speaking on behalf of the project + +''''' + +=== Enforcement + +==== Reporting + +If you experience or witness unacceptable behaviour, or have any other +concerns, please report it as soon as possible. + +*How to Report* + +[width="99%",cols="30%,33%,37%",options="header",] +|=== +|Method |Details |Best For +|*Email* |j.d.a.jewell@open.ac.uk |Detailed reports, sensitive matters + +|*Private Message* |Contact any maintainer directly |Quick questions, +minor issues + +|*Anonymous Form* |[Link to form if available] |When you need anonymity +|=== + +*What to Include* + +* Your contact information (unless anonymous) +* Names/usernames of those involved +* Description of what happened +* When and where it occurred +* Any witnesses +* Any supporting evidence (screenshots, links) +* How you would like us to respond (if you have a preference) + +*What Happens Next* + +[arabic] +. You will receive acknowledgment within *48 hours* +. The maintainers will review the report +. We may ask for additional information +. We will determine appropriate action +. We will inform you of the outcome (respecting others’ privacy) + +==== Confidentiality + +All reports will be handled with discretion: + +* Reporter identity is protected by default +* Details are shared only with those who need to know +* We will ask before naming you in any communication +* Anonymous reports are accepted and investigated + +==== Conflicts of Interest + +If a maintainers member is involved in an incident: + +* They will recuse themselves from the process +* Another maintainer or external party will handle the report +* We will disclose any potential conflicts + +''''' + +=== Enforcement Guidelines + +The maintainers will follow these guidelines in determining +consequences: + +==== 1. Correction + +*Community Impact*: Use of inappropriate language or other behaviour +deemed unprofessional or unwelcome. + +*Consequence*: A private, written warning providing clarity around the +nature of the violation and an explanation of why the behaviour was +inappropriate. A public apology may be requested. + +*Duration*: Immediate + +==== 2. Warning + +*Community Impact*: A violation through a single incident or series of +actions. + +*Consequence*: A warning with consequences for continued behaviour. No +interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, for a specified period. 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. + +*Duration*: 1-4 weeks + +==== 3. Temporary Ban + +*Community Impact*: A serious violation of community standards, +including sustained inappropriate behaviour. + +*Consequence*: A temporary ban from any sort of interaction or public +communication with the community for a specified period. 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. + +*Duration*: 1-6 months + +==== 4. Permanent Ban + +*Community Impact*: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behaviour, 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. + +*Duration*: Permanent (with appeal rights after 12 months) + +==== Enforcement Across Perimeters + +For contributors with elevated access (Perimeter 2 or 1): + +[cols=",",options="header",] +|=== +|Level |Additional Consequence +|Correction |Noted in contributor record +|Warning |Access privileges may be temporarily reduced +|Temporary Ban |Access reduced to Perimeter 3 for ban duration +|Permanent Ban |All access revoked +|=== + +''''' + +=== Appeals + +If you believe an enforcement decision was made in error: + +[arabic] +. *Wait 7 days* after the decision (cooling-off period) +. *Email* j.d.a.jewell@open.ac.uk with subject line "`Appeal: [Original +Report ID]`" +. *Explain* why you believe the decision should be reconsidered +. *Provide* any new information not previously available + +*Appeals Process* + +* Appeals are reviewed by a different maintainers member than the +original +* You will receive a response within 14 days +* The appeals decision is final +* You may only appeal once per incident + +*Grounds for Appeal* + +* Procedural errors in the original investigation +* New evidence not previously available +* Disproportionate response to the violation +* Misunderstanding of facts + +''''' + +=== Supporting Those Who Report + +We are committed to supporting those who report violations: + +*We Will* - Believe and take all reports seriously - Respect your +privacy and confidentiality preferences - Keep you informed of progress +(if you wish) - Take steps to protect you from retaliation - Provide +resources if you need support + +*We Will Not* - Require you to confront the person directly - Dismiss +reports without investigation - Reveal your identity without consent - +Tolerate retaliation against reporters - Rush you to make decisions + +''''' + +=== Prevention + +Beyond enforcement, we actively work to prevent issues: + +*Onboarding* - All contributors are expected to read this Code of +Conduct - Perimeter 2 applicants must confirm they’ve read and +understood it - Maintainers receive additional training on enforcement + +*Culture* - We model the behaviour we expect - We intervene early when +we see potential issues - We thank people for positive contributions - +We create opportunities for diverse voices + +*Review* - This Code of Conduct is reviewed annually - Community +feedback is welcomed - Changes are communicated clearly + +''''' + +=== Acknowledgments + +This Code of Conduct is adapted from: + +* https://www.contributor-covenant.org/[Contributor Covenant], version +2.1 +* https://www.djangoproject.com/conduct/[Django Code of Conduct] +* https://www.rust-lang.org/policies/code-of-conduct[Rust Code of +Conduct] +* https://www.python.org/psf/conduct/[Python Community Code of Conduct] + +We thank these communities for their leadership in creating welcoming +spaces. + +''''' + +=== Questions? + +If you have questions about this Code of Conduct: + +* Open a +https://github.com/hyperpolymath/squisher-corpus/discussions[Discussion] +(for general questions) +* Email j.d.a.jewell@open.ac.uk (for private questions) +* Contact any maintainer directly + +''''' + +=== Summary + +*Be kind. Be respectful. Be collaborative.* + +We’re all here because we care about this project. Let’s make it a place +where everyone can do their best work. + +''''' + +Last updated: 2026 · Based on Contributor Covenant 2.1 diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md deleted file mode 100644 index 8267cd4..0000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,327 +0,0 @@ -# Code of Conduct - - - -## Our Pledge - -We as members, contributors, and leaders pledge to make participation in Squisher Corpus 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, caste, colour, 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. - -We recognise that a thriving open source community requires **psychological safety** — an environment where people can contribute, ask questions, make mistakes, and learn without fear of ridicule or retaliation. - ---- - -## Our Standards - -### Expected Behaviour - -The following behaviours contribute to a positive environment: - -**Communication** -- Using welcoming and inclusive language -- Being respectful of differing viewpoints and experiences -- Giving and gracefully accepting constructive feedback -- Assuming good intent while addressing impact -- Communicating clearly and patiently, especially with newcomers - -**Collaboration** -- Focusing on what is best for the community -- Showing empathy and kindness toward other community members -- Being collaborative rather than competitive -- Mentoring and supporting less experienced contributors -- Celebrating others' contributions and successes - -**Professionalism** -- Accepting responsibility and apologising to those affected by our mistakes -- Learning from the experience and avoiding repetition -- Respecting others' time and attention -- Staying on topic in project spaces -- Following project guidelines and conventions - -**Accessibility** -- Using plain language and avoiding unnecessary jargon -- Providing alt text for images and transcripts for audio/video -- Being patient with those using assistive technologies -- Accommodating different communication styles and needs -- Recognising that not everyone communicates the same way - -### Unacceptable Behaviour - -The following behaviours are considered harassment and are unacceptable: - -**Harassment** -- The use of sexualised 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 -- Deliberate intimidation, stalking, or following (online or in-person) -- Unwelcome physical contact or simulated physical contact (e.g., emoji) -- Sustained disruption of talks, events, or online discussions - -**Discrimination** -- Discriminatory jokes and language -- Posting or threatening to post others' personally identifying information ("doxing") -- Advocating for, or encouraging, any of the above behaviour -- Microaggressions — subtle, often unintentional, discriminatory comments or actions - -**Professional Misconduct** -- Publishing others' private information without explicit permission -- Misrepresenting affiliation or contributions -- Plagiarism or claiming credit for others' work -- Retaliating against anyone who reports a Code of Conduct violation -- Other conduct which could reasonably be considered inappropriate in a professional setting - -### Grey Areas - -Some situations require judgement. When uncertain: - -- **Intent vs Impact**: Good intentions do not excuse harmful impact. Focus on making things right. -- **Power Dynamics**: Those with more power (maintainers, employers, experienced contributors) must be especially mindful of their impact. -- **Cultural Differences**: What's acceptable varies by culture. When in doubt, err on the side of caution and ask. -- **Humour**: Jokes at others' expense are rarely funny to everyone. Punch up, not down. - ---- - -## Scope - -This Code of Conduct applies within all community spaces, including: - -**Online Spaces** -- Repository discussions, issues, and pull/merge requests -- Project chat channels (Matrix, Discord, Slack, IRC) -- Mailing lists and forums -- Social media when representing the project -- Video calls and virtual meetings - -**In-Person Spaces** -- Conferences, meetups, and events -- Workshops and training sessions -- Any gathering where you represent the project - -**Representation** -This Code of Conduct also applies when an individual is officially representing the community in public spaces. Examples include: - -- Using an official project email address -- Posting via an official social media account -- Acting as an appointed representative at an event -- Speaking on behalf of the project - ---- - -## Enforcement - -### Reporting - -If you experience or witness unacceptable behaviour, or have any other concerns, please report it as soon as possible. - -**How to Report** - -| Method | Details | Best For | -|--------|---------|----------| -| **Email** | j.d.a.jewell@open.ac.uk | Detailed reports, sensitive matters | -| **Private Message** | Contact any maintainer directly | Quick questions, minor issues | -| **Anonymous Form** | [Link to form if available] | When you need anonymity | - -**What to Include** - -- Your contact information (unless anonymous) -- Names/usernames of those involved -- Description of what happened -- When and where it occurred -- Any witnesses -- Any supporting evidence (screenshots, links) -- How you would like us to respond (if you have a preference) - -**What Happens Next** - -1. You will receive acknowledgment within **48 hours** -2. The maintainers will review the report -3. We may ask for additional information -4. We will determine appropriate action -5. We will inform you of the outcome (respecting others' privacy) - -### Confidentiality - -All reports will be handled with discretion: - -- Reporter identity is protected by default -- Details are shared only with those who need to know -- We will ask before naming you in any communication -- Anonymous reports are accepted and investigated - -### Conflicts of Interest - -If a maintainers member is involved in an incident: - -- They will recuse themselves from the process -- Another maintainer or external party will handle the report -- We will disclose any potential conflicts - ---- - -## Enforcement Guidelines - -The maintainers will follow these guidelines in determining consequences: - -### 1. Correction - -**Community Impact**: Use of inappropriate language or other behaviour deemed unprofessional or unwelcome. - -**Consequence**: A private, written warning providing clarity around the nature of the violation and an explanation of why the behaviour was inappropriate. A public apology may be requested. - -**Duration**: Immediate - -### 2. Warning - -**Community Impact**: A violation through a single incident or series of actions. - -**Consequence**: A warning with consequences for continued behaviour. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period. 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. - -**Duration**: 1-4 weeks - -### 3. Temporary Ban - -**Community Impact**: A serious violation of community standards, including sustained inappropriate behaviour. - -**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period. 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. - -**Duration**: 1-6 months - -### 4. Permanent Ban - -**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behaviour, 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. - -**Duration**: Permanent (with appeal rights after 12 months) - -### Enforcement Across Perimeters - -For contributors with elevated access (Perimeter 2 or 1): - -| Level | Additional Consequence | -|-------|----------------------| -| Correction | Noted in contributor record | -| Warning | Access privileges may be temporarily reduced | -| Temporary Ban | Access reduced to Perimeter 3 for ban duration | -| Permanent Ban | All access revoked | - ---- - -## Appeals - -If you believe an enforcement decision was made in error: - -1. **Wait 7 days** after the decision (cooling-off period) -2. **Email** j.d.a.jewell@open.ac.uk with subject line "Appeal: [Original Report ID]" -3. **Explain** why you believe the decision should be reconsidered -4. **Provide** any new information not previously available - -**Appeals Process** - -- Appeals are reviewed by a different maintainers member than the original -- You will receive a response within 14 days -- The appeals decision is final -- You may only appeal once per incident - -**Grounds for Appeal** - -- Procedural errors in the original investigation -- New evidence not previously available -- Disproportionate response to the violation -- Misunderstanding of facts - ---- - -## Supporting Those Who Report - -We are committed to supporting those who report violations: - -**We Will** -- Believe and take all reports seriously -- Respect your privacy and confidentiality preferences -- Keep you informed of progress (if you wish) -- Take steps to protect you from retaliation -- Provide resources if you need support - -**We Will Not** -- Require you to confront the person directly -- Dismiss reports without investigation -- Reveal your identity without consent -- Tolerate retaliation against reporters -- Rush you to make decisions - ---- - -## Prevention - -Beyond enforcement, we actively work to prevent issues: - -**Onboarding** -- All contributors are expected to read this Code of Conduct -- Perimeter 2 applicants must confirm they've read and understood it -- Maintainers receive additional training on enforcement - -**Culture** -- We model the behaviour we expect -- We intervene early when we see potential issues -- We thank people for positive contributions -- We create opportunities for diverse voices - -**Review** -- This Code of Conduct is reviewed annually -- Community feedback is welcomed -- Changes are communicated clearly - ---- - -## Acknowledgments - -This Code of Conduct is adapted from: - -- [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1 -- [Django Code of Conduct](https://www.djangoproject.com/conduct/) -- [Rust Code of Conduct](https://www.rust-lang.org/policies/code-of-conduct) -- [Python Community Code of Conduct](https://www.python.org/psf/conduct/) - -We thank these communities for their leadership in creating welcoming spaces. - ---- - -## Questions? - -If you have questions about this Code of Conduct: - -- Open a [Discussion](https://github.com/hyperpolymath/squisher-corpus/discussions) (for general questions) -- Email j.d.a.jewell@open.ac.uk (for private questions) -- Contact any maintainer directly - ---- - -## Summary - -**Be kind. Be respectful. Be collaborative.** - -We're all here because we care about this project. Let's make it a place where everyone can do their best work. - ---- - -Last updated: 2026 · Based on Contributor Covenant 2.1 diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc new file mode 100644 index 0000000..0e9f4c1 --- /dev/null +++ b/CONTRIBUTING.adoc @@ -0,0 +1,20 @@ +== Contributing + +Contributions are welcome! Please: + +[arabic] +. Fork the repository +. Create a feature branch from `+main+` +. Ensure all CI checks pass +. Submit a pull request + +=== Standards + +This project follows the +https://github.com/hyperpolymath/standards[Rhodium Standard Repository +(RSR)] conventions. + +=== License + +By contributing, you agree that your contributions will be licensed +under MPL-2.0 (with MPL-2.0 as automatic legal fallback). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 056f4b7..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,17 +0,0 @@ - -# Contributing - -Contributions are welcome! Please: - -1. Fork the repository -2. Create a feature branch from `main` -3. Ensure all CI checks pass -4. Submit a pull request - -## Standards - -This project follows the [Rhodium Standard Repository (RSR)](https://github.com/hyperpolymath/standards) conventions. - -## License - -By contributing, you agree that your contributions will be licensed under MPL-2.0 (with MPL-2.0 as automatic legal fallback). diff --git a/GOVERNANCE.adoc b/GOVERNANCE.adoc new file mode 100644 index 0000000..9b836fb --- /dev/null +++ b/GOVERNANCE.adoc @@ -0,0 +1,60 @@ +== 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/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/PROOF-NEEDS.adoc b/PROOF-NEEDS.adoc new file mode 100644 index 0000000..5f7485b --- /dev/null +++ b/PROOF-NEEDS.adoc @@ -0,0 +1,209 @@ +== PROOF-NEEDS.md + +=== Current State + +* *LOC*: ~237 Rust (host) + ~100 AffineScript (`+.affine+`, not +compilable). +* *Existing proofs*: *first corpus landed (2026-06-04)* — +`+verification/proofs/Lattice/Order.idr+` (Idris2 0.8.0, +`+%default total+`, zero proof escapes), CI-gated by +`+.github/workflows/proof-corpus.yml+`. It proves the _abstract_ order +theory, *not yet* bound to the Rust graph (see below). Before this there +were zero proofs. The 2026-05-26 estate tech-debt audit recorded "`Proof +debt: none / Recommended next move: none`" — that verdict is *wrong* for +a project whose headline noun is _lattice_. A lattice is a mathematical +claim with discharge obligations; asserting it without proof is exactly +the kind of overstatement this file exists to retire. +* *Status*: the structure git-reticulator builds today is a _typed, +weighted digraph_ with a hierarchical containment sub-relation — *not* +(yet) a lattice, not even a partial order (TOPOLOGY.md itself mentions +detecting _circular_ dependencies, i.e. cycles, which a partial order +forbids). + +____ +The point of this document is to make the gap between the noun +("`lattice`") and the artifact (a digraph) explicit, and to list +precisely what must be proved to close it. Until then, prose should say +"`typed graph`" / "`DAG`". +____ + +=== Recommended Prover + +* *Idris2* — to match the estate’s existing formal-methods spine +(`+vcl-ut+` ships a machine-checked Idris2 corpus, `+%default total+`, +zero proof-escape). Reusing it means shared CI +(`+proof-corpus.yml+`-style gate) and shared reviewer muscle. Lean4 or +Coq would also serve; Idris2 is the path of least estate friction. The +order-theory here is elementary; the value is in _connecting the proofs +to the running code_, not in their depth. + +=== Proof status (by category) — 2026-06-04 + +Honest categorisation. *Proved* = mechanically checked +(Idris2/Coq/SPARK). *Tested* = executable checks + unit tests in the +Rust reference core (`+src/lattice/mod.rs+`) — a rung _below_ proof. +git-reticulator has *zero mechanized proofs*; what exists is tested. + +==== Done (mechanized — first corpus, 2026-06-04) + +* *Abstract order theory* (`+verification/proofs/Lattice/Order.idr+`, +Idris2 0.8.0, `+%default total+`, zero proof escapes; CI-gated by +`+proof-corpus.yml+`): the partial-order laws are witnessed +(`+natOrder+`: reflexive + transitive + antisymmetric) and *antisymmetry +⇒ no 2-cycle* (`+noTwoCycle+`) is proved — the order-theoretic heart of +why the SCC condensation is a DAG (*P2a*). *Scope honesty:* proved on an +_abstract_ `+PartialOrder+`, *not yet* on the actual Rust graph in +`+src/lattice/mod.rs+`; binding the two is the ADR-006 Idris2 ABI seam. + +==== Done (tested, not proved) + +* *P2a* SCC condensation is acyclic — `+Condensation::is_acyclic+` (Kahn +topological sort, a genuine runtime check, not a trust assertion) + +tests (the 3-node call cycle collapses to one component; condensation is +a DAG). +* *P4* LOD `+zoom+` soundness + completeness — tested on fixtures (defs +in other files excluded; every descendant returned). +* *P1b (fragment)* `+meet+` = lowest common ancestor — tested +(idempotent, commutative, LCA correct). +* *P1a (fragment)* reflexivity of ≤ — tested. + +==== Not attempted + +* *P1* full lattice laws (associativity/absorption; *join*). +* *P3* monotone abstraction (commit-DAG → lattice) — also: git-history +ingest isn’t wired (`+src/ingest.rs+` is filesystem-only). +* *P5* determinism/confluence. *P6* drift-predicate totality. +* *P7* pgRouting≡lattice — now *N/A* (verisim is the store, not +pgRouting). +* In the _mechanized-proof_ sense, *all of P1–P7 are unattempted* (zero +`+.idr+`). + +==== Sorries / `+believe_me+` / proof escapes + +* *Zero — but vacuously.* There are no proofs, so there are no escape +hatches. This is *not* vcl-ut’s "`zero `+believe_me+` in a real corpus`" +achievement; it is zero-because-empty. Recorded so it is never mistaken +for rigour we lack. + +==== Structural blockers + +* Idris2 prover *now wired* (`+verification/proofs/+` + +`+proof-corpus.yml+`, idris2 0.8.0); first module verified. Remaining: +bind the proofs to the Rust graph and discharge the rest of P1–P7. +* The verifiable core is migrating to AffineScript (ADR-006), itself +alpha with the CORE-01 soundness gap. +* The Rust/SPARK Idris2/Zig ABI seam is *N/A until git-reticulator +exposes an FFI surface* (it’s a CLI/REST app today) — see +`+docs/decisions/rust-spark-stance.adoc+`. + +==== False (claims that would be untrue — and are correctly avoided) + +* "`git-reticulator builds a **lattice**`" (full lattice) is *false*: +arbitrary sibling nodes have no unique join. The code is honest — it +implements `+meet+` only and names the structure a *meet-semilattice* + +typed digraph. The true, scoped claim is evidenced by test; the false +strong claim is not made. + +==== What it means / how much to worry + +* *Low worry* for an early, non-safety-critical research tool. The +property that matters — and holds — is that *nothing is overclaimed*: +code and docs say "`tested not proved`", "`meet-semilattice not +lattice`", "`zero proofs`". That honesty _is_ the estate bar (the +doc-truthing / SPARK-theatre culture is about not faking verification). +The residual risk is correctness-confidence (a zoom/meet edge case could +ship), not safety. The path up is cheap and known: P2→P1→P4 in Idris2, +or largely for free from the AffineScript core’s type discipline +post-migration. + +=== What Needs Proving + +==== P1 — It is actually a lattice (or: rename it) — *HIGH* + +The relation `+≤+` derived from the structure must be shown to be a +lattice: - *P1a* `+≤+` is a partial order: reflexive, antisymmetric, +transitive. - *P1b* For every pair of nodes a *meet* (greatest lower +bound) and a *join* (least upper bound) exist and are unique. - *P1c* +The lattice laws hold: idempotence, commutativity, associativity of +`+∧+`/`+∨+`, and absorption. + +If P1b cannot be met for the real structure (likely — sibling nodes +generally have no unique join), then *honesty demands one of*: - +downgrade the claim to *meet-semilattice* (containment hierarchy with a +top), or - rename to "`semantic **graph**`" and drop "`lattice`" from +the API/docs. + +==== P2 — Cycles must be quotiented before any order claim — *HIGH* + +The dependency graph has cycles. A partial order has none. The standard +fix: - *P2a* Compute the *strongly-connected-component condensation*; +prove the condensation is acyclic (a DAG). - *P2b* Prove the order +induced on the condensation is well-defined (independent of SCC member +choice). Only on the condensation does P1 even get a chance. + +==== P3 — Faithful abstraction of git history (monotonicity) — *HIGH* + +The commit DAG → lattice mapping must not invent or lose ordering: - +*P3a* _Soundness_: if the lattice orders `+a ≤ b+`, then `+a+`’s git +origin is an ancestor of (or contained by) `+b+`’s — no spurious +orderings. - *P3b* _Completeness_: ancestry present in the commit DAG is +reflected. - Together: the construction is a *monotone +(order-preserving) map* from the commit DAG to the lattice. + +==== P4 — LOD `+zoom_to_node+` is sound AND complete — *HIGH (the RAG trust anchor)* + +This is the property that makes retrieval trustworthy — the bridge +between the symbolic guarantee and the neural/LLM consumer. - *P4a* +_Soundness_: every node returned by `+zoom_to_node(n, L)+` is a genuine +descendant of `+n+` at level `+L+` — no spurious context. - *P4b* +_Completeness_: every such descendant is returned — no silently dropped +context. - Formally: `+zoom(n, L) = { m | m ≤ n ∧ level(m) = L }+`, +exactly. Get this wrong and the LLM is fed context that is incomplete +(missing the relevant bit) or padded (wasting the token budget the +feature exists to save). + +==== P5 — Construction is deterministic / confluent — *MEDIUM* + +* Building the lattice twice from the same repo state yields the same +lattice (up to node identity). Without this, caching is unsound and any +downstream proof is meaningless because the object it refers to is +unstable. + +==== P6 — Neuro-symbolic consistency invariant — *MEDIUM (the novel target)* + +The genuinely new obligation, and the one that matters for the +neuro-symbolic claim (see `+.machine_readable/6a2/NEUROSYM.a2ml+`): - Do +*not* prove "`embedding proximity ⇒ lattice proximity`" (false in +general). - *Do* prove the _drift predicate_ is well-defined and +decidable: given a threshold, +`+drift(a,b) := cosine(emb a, emb b) high ∧ lattice-distance(a,b) high+` +is a total, computable signal. This is what lets verisim’s drift +detector treat neuro-symbolic disagreement as an observable event rather +than a silent inconsistency. + +==== P7 — `+pgRouting+` reachability matches lattice reachability — *LOW* + +* The Dijkstra/A* paths used for blast-radius (PB-4) range over the same +edge relation the lattice is built from — prove the stored +`+cost+`/`+weight+` topology is a faithful image of the in-memory +`+Relationship+` set, so "`reachable in the DB`" ⇔ "`reachable in the +lattice`". + +=== Priority + +*MEDIUM-HIGH.* git-reticulator is early and stubbed, so this is not +blocking a shipping product. But it is _cheap, high-signal_ work: P1+P2 +together either earn the central noun or correctly retire it, and P4 is +the precondition for the proof-carrying-retrieval story that makes the +whole neuro-symbolic stack worth building. Do P2 → P1 → P4 first; the +rest can follow the implementation. + +=== Cross-references + +* `+.machine_readable/6a2/NEUROSYM.a2ml+` — where these proofs pay off +(proof-carrying retrieval). +* `+hyperpolymath/vcl-ut+` `+PROOF-NEEDS.md+` + `+verification/proofs/+` +— the estate template for "`PROOF-NEEDS + Idris2 corpus + +VERIFICATION-STANCE`" done well. +* `+TEST-NEEDS.md+` — the testing counterpart (currently smoke-level +over stubs). diff --git a/PROOF-NEEDS.md b/PROOF-NEEDS.md deleted file mode 100644 index 8cfc3d3..0000000 --- a/PROOF-NEEDS.md +++ /dev/null @@ -1,175 +0,0 @@ -# PROOF-NEEDS.md - - - -## Current State - -- **LOC**: ~237 Rust (host) + ~100 AffineScript (`.affine`, not compilable). -- **Existing proofs**: **first corpus landed (2026-06-04)** — - `verification/proofs/Lattice/Order.idr` (Idris2 0.8.0, `%default total`, zero - proof escapes), CI-gated by `.github/workflows/proof-corpus.yml`. It proves the - *abstract* order theory, **not yet** bound to the Rust graph (see below). Before - this there were zero proofs. The 2026-05-26 estate tech-debt audit recorded - "Proof debt: none / Recommended next move: none" — that verdict is **wrong** - for a project whose headline noun is *lattice*. A lattice is a mathematical - claim with discharge obligations; asserting it without proof is exactly the - kind of overstatement this file exists to retire. -- **Status**: the structure git-reticulator builds today is a *typed, weighted - digraph* with a hierarchical containment sub-relation — **not** (yet) a - lattice, not even a partial order (TOPOLOGY.md itself mentions detecting - *circular* dependencies, i.e. cycles, which a partial order forbids). - -> The point of this document is to make the gap between the noun ("lattice") -> and the artifact (a digraph) explicit, and to list precisely what must be -> proved to close it. Until then, prose should say "typed graph" / "DAG". - -## Recommended Prover - -- **Idris2** — to match the estate's existing formal-methods spine (`vcl-ut` - ships a machine-checked Idris2 corpus, `%default total`, zero proof-escape). - Reusing it means shared CI (`proof-corpus.yml`-style gate) and shared - reviewer muscle. Lean4 or Coq would also serve; Idris2 is the path of least - estate friction. The order-theory here is elementary; the value is in - *connecting the proofs to the running code*, not in their depth. - -## Proof status (by category) — 2026-06-04 - -Honest categorisation. **Proved** = mechanically checked (Idris2/Coq/SPARK). -**Tested** = executable checks + unit tests in the Rust reference core -(`src/lattice/mod.rs`) — a rung *below* proof. git-reticulator has **zero -mechanized proofs**; what exists is tested. - -### Done (mechanized — first corpus, 2026-06-04) -- **Abstract order theory** (`verification/proofs/Lattice/Order.idr`, Idris2 0.8.0, - `%default total`, zero proof escapes; CI-gated by `proof-corpus.yml`): the - partial-order laws are witnessed (`natOrder`: reflexive + transitive + - antisymmetric) and **antisymmetry ⇒ no 2-cycle** (`noTwoCycle`) is proved — the - order-theoretic heart of why the SCC condensation is a DAG (**P2a**). **Scope - honesty:** proved on an *abstract* `PartialOrder`, **not yet** on the actual Rust - graph in `src/lattice/mod.rs`; binding the two is the ADR-006 Idris2 ABI seam. - -### Done (tested, not proved) -- **P2a** SCC condensation is acyclic — `Condensation::is_acyclic` (Kahn - topological sort, a genuine runtime check, not a trust assertion) + tests - (the 3-node call cycle collapses to one component; condensation is a DAG). -- **P4** LOD `zoom` soundness + completeness — tested on fixtures (defs in - other files excluded; every descendant returned). -- **P1b (fragment)** `meet` = lowest common ancestor — tested (idempotent, - commutative, LCA correct). -- **P1a (fragment)** reflexivity of ≤ — tested. - -### Not attempted -- **P1** full lattice laws (associativity/absorption; **join**). -- **P3** monotone abstraction (commit-DAG → lattice) — also: git-history ingest - isn't wired (`src/ingest.rs` is filesystem-only). -- **P5** determinism/confluence. **P6** drift-predicate totality. -- **P7** pgRouting≡lattice — now **N/A** (verisim is the store, not pgRouting). -- In the *mechanized-proof* sense, **all of P1–P7 are unattempted** (zero `.idr`). - -### Sorries / `believe_me` / proof escapes -- **Zero — but vacuously.** There are no proofs, so there are no escape hatches. - This is **not** vcl-ut's "zero `believe_me` in a real corpus" achievement; it - is zero-because-empty. Recorded so it is never mistaken for rigour we lack. - -### Structural blockers -- Idris2 prover **now wired** (`verification/proofs/` + `proof-corpus.yml`, idris2 - 0.8.0); first module verified. Remaining: bind the proofs to the Rust graph and - discharge the rest of P1–P7. -- The verifiable core is migrating to AffineScript (ADR-006), itself alpha with - the CORE-01 soundness gap. -- The Rust/SPARK Idris2/Zig ABI seam is **N/A until git-reticulator exposes an - FFI surface** (it's a CLI/REST app today) — see - `docs/decisions/rust-spark-stance.adoc`. - -### False (claims that would be untrue — and are correctly avoided) -- "git-reticulator builds a **lattice**" (full lattice) is **false**: arbitrary - sibling nodes have no unique join. The code is honest — it implements `meet` - only and names the structure a **meet-semilattice** + typed digraph. The true, - scoped claim is evidenced by test; the false strong claim is not made. - -### What it means / how much to worry -- **Low worry** for an early, non-safety-critical research tool. The property - that matters — and holds — is that **nothing is overclaimed**: code and docs - say "tested not proved", "meet-semilattice not lattice", "zero proofs". That - honesty *is* the estate bar (the doc-truthing / SPARK-theatre culture is about - not faking verification). The residual risk is correctness-confidence (a - zoom/meet edge case could ship), not safety. The path up is cheap and known: - P2→P1→P4 in Idris2, or largely for free from the AffineScript core's type - discipline post-migration. - -## What Needs Proving - -### P1 — It is actually a lattice (or: rename it) — **HIGH** -The relation `≤` derived from the structure must be shown to be a lattice: -- **P1a** `≤` is a partial order: reflexive, antisymmetric, transitive. -- **P1b** For every pair of nodes a **meet** (greatest lower bound) and a - **join** (least upper bound) exist and are unique. -- **P1c** The lattice laws hold: idempotence, commutativity, associativity of - `∧`/`∨`, and absorption. - -If P1b cannot be met for the real structure (likely — sibling nodes generally -have no unique join), then **honesty demands one of**: -- downgrade the claim to **meet-semilattice** (containment hierarchy with a top), or -- rename to "semantic **graph**" and drop "lattice" from the API/docs. - -### P2 — Cycles must be quotiented before any order claim — **HIGH** -The dependency graph has cycles. A partial order has none. The standard fix: -- **P2a** Compute the **strongly-connected-component condensation**; prove the - condensation is acyclic (a DAG). -- **P2b** Prove the order induced on the condensation is well-defined - (independent of SCC member choice). Only on the condensation does P1 even - get a chance. - -### P3 — Faithful abstraction of git history (monotonicity) — **HIGH** -The commit DAG → lattice mapping must not invent or lose ordering: -- **P3a** *Soundness*: if the lattice orders `a ≤ b`, then `a`'s git origin is - an ancestor of (or contained by) `b`'s — no spurious orderings. -- **P3b** *Completeness*: ancestry present in the commit DAG is reflected. -- Together: the construction is a **monotone (order-preserving) map** from the - commit DAG to the lattice. - -### P4 — LOD `zoom_to_node` is sound AND complete — **HIGH (the RAG trust anchor)** -This is the property that makes retrieval trustworthy — the bridge between the -symbolic guarantee and the neural/LLM consumer. -- **P4a** *Soundness*: every node returned by `zoom_to_node(n, L)` is a genuine - descendant of `n` at level `L` — no spurious context. -- **P4b** *Completeness*: every such descendant is returned — no silently - dropped context. -- Formally: `zoom(n, L) = { m | m ≤ n ∧ level(m) = L }`, exactly. - Get this wrong and the LLM is fed context that is incomplete (missing the - relevant bit) or padded (wasting the token budget the feature exists to save). - -### P5 — Construction is deterministic / confluent — **MEDIUM** -- Building the lattice twice from the same repo state yields the same lattice - (up to node identity). Without this, caching is unsound and any downstream - proof is meaningless because the object it refers to is unstable. - -### P6 — Neuro-symbolic consistency invariant — **MEDIUM (the novel target)** -The genuinely new obligation, and the one that matters for the neuro-symbolic -claim (see `.machine_readable/6a2/NEUROSYM.a2ml`): -- Do **not** prove "embedding proximity ⇒ lattice proximity" (false in general). -- **Do** prove the *drift predicate* is well-defined and decidable: given a - threshold, `drift(a,b) := cosine(emb a, emb b) high ∧ lattice-distance(a,b) high` - is a total, computable signal. This is what lets verisim's drift detector - treat neuro-symbolic disagreement as an observable event rather than a - silent inconsistency. - -### P7 — `pgRouting` reachability matches lattice reachability — **LOW** -- The Dijkstra/A* paths used for blast-radius (PB-4) range over the same edge - relation the lattice is built from — prove the stored `cost`/`weight` - topology is a faithful image of the in-memory `Relationship` set, so - "reachable in the DB" ⇔ "reachable in the lattice". - -## Priority - -**MEDIUM-HIGH.** git-reticulator is early and stubbed, so this is not blocking -a shipping product. But it is *cheap, high-signal* work: P1+P2 together either -earn the central noun or correctly retire it, and P4 is the precondition for -the proof-carrying-retrieval story that makes the whole neuro-symbolic stack -worth building. Do P2 → P1 → P4 first; the rest can follow the implementation. - -## Cross-references - -- `.machine_readable/6a2/NEUROSYM.a2ml` — where these proofs pay off (proof-carrying retrieval). -- `hyperpolymath/vcl-ut` `PROOF-NEEDS.md` + `verification/proofs/` — the estate template for "PROOF-NEEDS + Idris2 corpus + VERIFICATION-STANCE" done well. -- `TEST-NEEDS.md` — the testing counterpart (currently smoke-level over stubs). diff --git a/READINESS.adoc b/READINESS.adoc new file mode 100644 index 0000000..98ffc2a --- /dev/null +++ b/READINESS.adoc @@ -0,0 +1,42 @@ +== Readiness — git-reticulator + +*Current Grade:* C + +____ +This file is the source of truth read by `+just crg-grade+` / +`+just crg-badge+` (they grep for `+**Current Grade:** X+`). It was +missing before 2026-06-03 even though the Justfile referenced it — +created as part of the tidy-up pass. +____ + +=== CRG (Component Readiness Grade) + +[cols=",,",options="header",] +|=== +|Grade |Meaning |Status +|D |Builds |✅ +|*C* |*All test categories present + passing* |✅ *(current)* +|B |6 quality targets (lint, fmt, doc-coverage, …) |☐ next +|A |Production-ready |☐ +|=== + +See `+hyperpolymath/standards+` → component-readiness-grades for the +rubric. + +=== Honest caveat + +Grade C here reflects test *category presence*, not behavioural +coverage. The 27 tests assert "`does not panic`" over `+println!+` stubs +(see `+.machine_readable/6a2/STATE.a2ml [honest-status]+` and +`+TEST-NEEDS.md+`). The grade is technically correct against the rubric +and simultaneously *overstates functional maturity* — both facts are +recorded so neither surprises a reader. + +=== To reach Grade B + +[arabic] +. Replace ≥1 stub with a real (even in-memory) lattice build. +. Add a test that asserts a structural *property*, not just no-panic. +. Lint/fmt/doc-coverage clean. +. Discharge `+PROOF-NEEDS.md+` P2→P1 (earn the "`lattice`" noun) — +bonus, not required for B. diff --git a/READINESS.md b/READINESS.md deleted file mode 100644 index 730b59c..0000000 --- a/READINESS.md +++ /dev/null @@ -1,36 +0,0 @@ - - - -# Readiness — git-reticulator - -**Current Grade:** C - -> This file is the source of truth read by `just crg-grade` / `just crg-badge` -> (they grep for `**Current Grade:** X`). It was missing before 2026-06-03 even -> though the Justfile referenced it — created as part of the tidy-up pass. - -## CRG (Component Readiness Grade) - -| Grade | Meaning | Status | -|-------|---------|--------| -| D | Builds | ✅ | -| **C** | **All test categories present + passing** | ✅ **(current)** | -| B | 6 quality targets (lint, fmt, doc-coverage, …) | ☐ next | -| A | Production-ready | ☐ | - -See `hyperpolymath/standards` → component-readiness-grades for the rubric. - -## Honest caveat - -Grade C here reflects test **category presence**, not behavioural coverage. The -27 tests assert "does not panic" over `println!` stubs (see -`.machine_readable/6a2/STATE.a2ml [honest-status]` and `TEST-NEEDS.md`). The -grade is technically correct against the rubric and simultaneously **overstates -functional maturity** — both facts are recorded so neither surprises a reader. - -## To reach Grade B - -1. Replace ≥1 stub with a real (even in-memory) lattice build. -2. Add a test that asserts a structural **property**, not just no-panic. -3. Lint/fmt/doc-coverage clean. -4. Discharge `PROOF-NEEDS.md` P2→P1 (earn the "lattice" noun) — bonus, not required for B. diff --git a/README.adoc b/README.adoc new file mode 100644 index 0000000..05417a6 --- /dev/null +++ b/README.adoc @@ -0,0 +1,117 @@ +https://www.bestpractices.dev/en/projects/new?repo_url=https://github.com/hyperpolymath/git-reticulator[image:https://img.shields.io/badge/OpenSSF-Best_Practices-green?logo=opensourcesecurity[OpenSSF +Best Practices]] +https://github.com/hyperpolymath/palimpsest-license[image:https://img.shields.io/badge/License-MPL--2.0-blue.svg[License: +MPL-2.0]] +https://github.com/hyperpolymath/standards/tree/main/component-readiness-grades[image:https://img.shields.io/badge/CRG-C-yellow?style=flat-square[CRG +C]] + +Semantic-lattice + embedding builder for git repositories — the +*symbolic half of a neuro-symbolic retrieval stack*. It lifts a repo +from raw commits/blobs to a typed, hierarchical, embeddable structure +you can *zoom* into, so an LLM gets the minimal relevant context instead +of the whole tree. + +____ +[!IMPORTANT] *Maturity: experimental.* The Rust reference engine is real +(SCC condensation, partial order, LOD zoom, containment meet) and the +build→query dogfood loop works end-to-end: `+reticulate build+` persists +a lattice file, `+reticulate query+` returns token-budgeted context +packs (see `+docs/DOGFOOD.adoc+`). The AffineScript core in +`+src/lattice/affine/*.affine+` is *aspirational* (deferred behind the +ADR-006 bridge); `+postgres+`/embeddings are feature-gated *off*; +mechanized proofs cover abstract order theory only, not yet the Rust +graph (see PROOF-NEEDS). Read `+.machine_readable/6a2/STATE.a2ml+` for +the honest status before relying on anything here. +____ + +== Why this exists + +Existing git-analysis tools work at the raw commit/blob level. +`+git-reticulator+` lifts the analysis to a *navigable semantic +structure* with two faculties fused at every node: an *order position* +(symbolic) and an *embedding* (neural). That fusion is the basis for: + +* *Token-bounded retrieval* — `+zoom_to_node(node,+` `+level)+` returns +the minimal relevant sub-structure (Level-of-Detail) for an LLM prompt. +* *Refactoring-impact / blast-radius* — weighted reachability (pgRouting +Dijkstra/A*) over typed edges. +* *Authorship + time queries* — "`who owns this concept`", "`when did it +enter the codebase`" (maps onto verisim’s provenance + temporal +modalities). + +== The neuro-symbolic picture (where this is headed) + +.... + [git-reticulator] [RAG] [verisim octad] [vcl-ut] + symbolic lattice -> embeddings -> 8-modal substrate -> proof-carrying + + per-node vector similarity (graph=lattice, queries + (LOD zoom) search vector=embeddings, (FRESHNESS, + provenance=authorship) PROVENANCE…) +.... + +The payoff is *proof-carrying retrieval*: neural search *proposes* +context; the symbolic lattice + verisim + vcl-ut *dispose*, so a +retrieved snippet can carry a machine-checked certificate that it really +exists at HEAD (FRESHNESS), was authored by X (PROVENANCE), and isn’t +hallucinated (EXISTENCE). See `+.machine_readable/6a2/NEUROSYM.a2ml+` +and `+.machine_readable/6a2/PLAYBOOK.a2ml+`. + +== Quickstart + +[source,bash] +---- +cargo build --features git-integration # git-aware ingest (plain `cargo build` = filesystem walk) + +# CLI binary is `reticulate` (subcommands: build | query | api): +./target/debug/reticulate build --repo /path/to/repo +# → ingests the repo, writes /path/to/repo/.git-reticulator/lattice.json + +./target/debug/reticulate query --repo /path/to/repo --zoom auth --level definition --budget-tokens 800 +# → token-budgeted context pack (add --format json for machine consumption) + +./target/debug/reticulate --help +---- + +____ +[!NOTE] `+build+` and `+query+` are *real* end-to-end (ingest → lattice +file → budgeted context pack; see `+docs/DOGFOOD.adoc+`). The `+api+` +server and the VeriSimDB store (`+--features verisim+`) remain thin. +____ + +== Architecture + +* `+src/lib.rs+`, `+src/cli/main.rs+`, `+src/api/app.rs+` — Rust host +(CLI + REST shell). +* `+src/lattice/affine/*.affine+` — intended lattice core (AffineScript; +aspirational). +* `+benches/+`, `+tests/+` — criterion + smoke/contract tests. +* `+.machine_readable/6a2/+` — canonical project state, ecosystem, +neuro-symbolic design, playbooks. + +== Status & honesty + +* *Licence*: MPL-2.0. +* *Maturity*: research / skeleton. API not stable. +* *Formal status*: zero proofs; see PROOF-NEEDS for the obligations the +"`lattice`" claim incurs. +* *Honest state*: `+.machine_readable/6a2/STATE.a2ml+` +(IMPLEMENTED|SKELETON|ASPIRATIONAL legend). + +== Contributing + +See CONTRIBUTING. Commits must be GPG-signed; conventional-commits +required (CHANGELOG generated via `+standards+` +`+changelog-reusable.yml+`). + +== Companion repositories + +* https://github.com/hyperpolymath/affinescript[`+affinescript+`] — the +intended core language (compiles to Wasm). +* https://github.com/hyperpolymath/verisimdb[`+verisimdb+`] — the octad +substrate this can feed. +* https://github.com/hyperpolymath/vcl-ut[`+vcl-ut+`] — proof-carrying +query layer over verisim. +* https://github.com/hyperpolymath/standards[`+standards+`] — canonical +estate standards. +* https://github.com/hyperpolymath/k9[`+k9+`] — metadata-extraction +tooling (`+k9iser.toml+` consumed here). diff --git a/README.md b/README.md deleted file mode 100644 index 17aeee7..0000000 --- a/README.md +++ /dev/null @@ -1,130 +0,0 @@ - - -[![OpenSSF Best Practices](https://img.shields.io/badge/OpenSSF-Best_Practices-green?logo=opensourcesecurity)](https://www.bestpractices.dev/en/projects/new?repo_url=https://github.com/hyperpolymath/git-reticulator) -[![License: MPL-2.0](https://img.shields.io/badge/License-MPL--2.0-blue.svg)](https://github.com/hyperpolymath/palimpsest-license) -[![CRG C](https://img.shields.io/badge/CRG-C-yellow?style=flat-square)](https://github.com/hyperpolymath/standards/tree/main/component-readiness-grades) - -Semantic-lattice + embedding builder for git repositories — the -**symbolic half of a neuro-symbolic retrieval stack**. It lifts a repo -from raw commits/blobs to a typed, hierarchical, embeddable structure -you can **zoom** into, so an LLM gets the minimal relevant context -instead of the whole tree. - -> [!IMPORTANT] -> **Maturity: experimental.** The Rust reference engine is real -> (SCC condensation, partial order, LOD zoom, containment meet) and the -> build→query dogfood loop works end-to-end: `reticulate build` persists -> a lattice file, `reticulate query` returns token-budgeted context -> packs (see `docs/DOGFOOD.adoc`). The AffineScript core in -> `src/lattice/affine/*.affine` is **aspirational** (deferred behind the -> ADR-006 bridge); `postgres`/embeddings are feature-gated **off**; -> mechanized proofs cover abstract order theory only, not yet the Rust -> graph (see PROOF-NEEDS). Read -> `.machine_readable/6a2/STATE.a2ml` for the honest status before -> relying on anything here. - -# Why this exists - -Existing git-analysis tools work at the raw commit/blob level. -`git-reticulator` lifts the analysis to a **navigable semantic -structure** with two faculties fused at every node: an **order -position** (symbolic) and an **embedding** (neural). That fusion is the -basis for: - -- **Token-bounded retrieval** — `zoom_to_node(node,` `level)` returns - the minimal relevant sub-structure (Level-of-Detail) for an LLM - prompt. - -- **Refactoring-impact / blast-radius** — weighted reachability - (pgRouting Dijkstra/A\*) over typed edges. - -- **Authorship + time queries** — "who owns this concept", "when did it - enter the codebase" (maps onto verisim’s provenance + temporal - modalities). - -# The neuro-symbolic picture (where this is headed) - - [git-reticulator] [RAG] [verisim octad] [vcl-ut] - symbolic lattice -> embeddings -> 8-modal substrate -> proof-carrying - + per-node vector similarity (graph=lattice, queries - (LOD zoom) search vector=embeddings, (FRESHNESS, - provenance=authorship) PROVENANCE…) - -The payoff is **proof-carrying retrieval**: neural search **proposes** -context; the symbolic lattice + verisim + vcl-ut **dispose**, so a -retrieved snippet can carry a machine-checked certificate that it really -exists at HEAD (FRESHNESS), was authored by X (PROVENANCE), and isn’t -hallucinated (EXISTENCE). See `.machine_readable/6a2/NEUROSYM.a2ml` and -`.machine_readable/6a2/PLAYBOOK.a2ml`. - -# Quickstart - -```bash -cargo build --features git-integration # git-aware ingest (plain `cargo build` = filesystem walk) - -# CLI binary is `reticulate` (subcommands: build | query | api): -./target/debug/reticulate build --repo /path/to/repo -# → ingests the repo, writes /path/to/repo/.git-reticulator/lattice.json - -./target/debug/reticulate query --repo /path/to/repo --zoom auth --level definition --budget-tokens 800 -# → token-budgeted context pack (add --format json for machine consumption) - -./target/debug/reticulate --help -``` - -> [!NOTE] -> `build` and `query` are **real** end-to-end (ingest → lattice file → -> budgeted context pack; see `docs/DOGFOOD.adoc`). The `api` server and -> the VeriSimDB store (`--features verisim`) remain thin. - -# Architecture - -- `src/lib.rs`, `src/cli/main.rs`, `src/api/app.rs` — Rust host (CLI + - REST shell). - -- `src/lattice/affine/*.affine` — intended lattice core (AffineScript; - aspirational). - -- `benches/`, `tests/` — criterion + smoke/contract tests. - -- `.machine_readable/6a2/` — canonical project state, ecosystem, - neuro-symbolic design, playbooks. - -# Status & honesty - -- **Licence**: MPL-2.0. - -- **Maturity**: research / skeleton. API not stable. - -- **Formal status**: zero proofs; see - PROOF-NEEDS for the - obligations the "lattice" claim incurs. - -- **Honest state**: `.machine_readable/6a2/STATE.a2ml` - (IMPLEMENTED\|SKELETON\|ASPIRATIONAL legend). - -# Contributing - -See CONTRIBUTING. Commits must -be GPG-signed; conventional-commits required (CHANGELOG generated via -`standards` `changelog-reusable.yml`). - -# Companion repositories - -- [`affinescript`](https://github.com/hyperpolymath/affinescript) — the - intended core language (compiles to Wasm). - -- [`verisimdb`](https://github.com/hyperpolymath/verisimdb) — the octad - substrate this can feed. - -- [`vcl-ut`](https://github.com/hyperpolymath/vcl-ut) — proof-carrying - query layer over verisim. - -- [`standards`](https://github.com/hyperpolymath/standards) — canonical - estate standards. - -- [`k9`](https://github.com/hyperpolymath/k9) — metadata-extraction - tooling (`k9iser.toml` consumed here). diff --git a/SECURITY.adoc b/SECURITY.adoc new file mode 100644 index 0000000..3081ece --- /dev/null +++ b/SECURITY.adoc @@ -0,0 +1,16 @@ +== Security Policy + +=== Reporting a Vulnerability + +If you discover a security vulnerability, please report it responsibly: + +* *Email:* j.d.a.jewell@open.ac.uk +* *Do NOT* open a public issue for security vulnerabilities + +We will acknowledge receipt within 48 hours and provide a detailed +response within 7 days. + +=== Supported Versions + +Only the latest release on the `+main+` branch is supported with +security updates. diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index b2dacab..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,15 +0,0 @@ - -# Security Policy - -## Reporting a Vulnerability - -If you discover a security vulnerability, please report it responsibly: - -- **Email:** j.d.a.jewell@open.ac.uk -- **Do NOT** open a public issue for security vulnerabilities - -We will acknowledge receipt within 48 hours and provide a detailed response within 7 days. - -## Supported Versions - -Only the latest release on the `main` branch is supported with security updates. diff --git a/TEST-NEEDS.adoc b/TEST-NEEDS.adoc new file mode 100644 index 0000000..93a05f8 --- /dev/null +++ b/TEST-NEEDS.adoc @@ -0,0 +1,53 @@ +== TEST-NEEDS — git-reticulator + +=== CRG Grade: C — ACHIEVED 2026-04-04 + +All required test categories present and passing; `+cargo test+` green. + +____ +*Update 2026-06-04:* the Rust lattice engine is now real, so the suite +is no longer smoke-over-stubs. The 10 new lib tests assert genuine +lattice *properties* (SCC-condensation acyclicity, zoom +soundness+completeness, meet=LCA, reflexivity) — _tested, not proved_ +(see PROOF-NEEDS.md "`Proof status`"). The 20 pre-existing +integration/property/api tests still pass via the IO-free compat shim. +____ + +==== Test Inventory + +[width="100%",cols="25%,25%,25%,25%",options="header",] +|=== +|Category |Status |Location |Count +|Lattice properties |PASS |`+src/lattice/mod.rs+` (`+#[cfg(test)]+`) |6 +|Ingest |PASS |`+src/ingest.rs+` (`+#[cfg(test)]+`) |3 +|Store |PASS |`+src/store.rs+` (`+#[cfg(test)]+`) |1 +|Property-based |PASS |`+tests/property_tests.rs+` |5 +|E2E / Reflexive |PASS |`+tests/integration_tests.rs+` |4 +|Contract |PASS |`+tests/integration_tests.rs+` |3 +|Aspect |PASS |`+tests/integration_tests.rs+` |6 +|API / CLI |PASS |`+tests/api_tests.rs+` |2 +|Benchmarks (baselined) |PASS |`+benches/git_reticulator_bench.rs+` |6 +|=== + +Total tests: *30* (`+cargo test+` exit 0) + +Benchmarks: *6* (Criterion; behavioural criterion benches over fixture +repos are owed for the new engine) + +==== Commands + +[source,sh] +---- +# Run all tests +cargo test + +# Compile benchmarks (no-run for CI) +cargo bench --no-run + +# Run benchmarks (writes HTML reports to target/criterion/) +cargo bench +---- + +==== Next: CRG Grade B + +Requires 6 quality targets (linting, formatting, documentation coverage, +etc.). See `+.machine_readable/6a2/STATE.a2ml+` for details. diff --git a/TEST-NEEDS.md b/TEST-NEEDS.md deleted file mode 100644 index 8822a6f..0000000 --- a/TEST-NEEDS.md +++ /dev/null @@ -1,51 +0,0 @@ - -# TEST-NEEDS — git-reticulator - -## CRG Grade: C — ACHIEVED 2026-04-04 - -All required test categories present and passing; `cargo test` green. - -> **Update 2026-06-04:** the Rust lattice engine is now real, so the suite is no -> longer smoke-over-stubs. The 10 new lib tests assert genuine lattice -> **properties** (SCC-condensation acyclicity, zoom soundness+completeness, -> meet=LCA, reflexivity) — *tested, not proved* (see PROOF-NEEDS.md "Proof -> status"). The 20 pre-existing integration/property/api tests still pass via the -> IO-free compat shim. - -### Test Inventory - -| Category | Status | Location | Count | -|---|---|---|---| -| Lattice properties | PASS | `src/lattice/mod.rs` (`#[cfg(test)]`) | 6 | -| Ingest | PASS | `src/ingest.rs` (`#[cfg(test)]`) | 3 | -| Store | PASS | `src/store.rs` (`#[cfg(test)]`) | 1 | -| Property-based | PASS | `tests/property_tests.rs` | 5 | -| E2E / Reflexive | PASS | `tests/integration_tests.rs` | 4 | -| Contract | PASS | `tests/integration_tests.rs` | 3 | -| Aspect | PASS | `tests/integration_tests.rs` | 6 | -| API / CLI | PASS | `tests/api_tests.rs` | 2 | -| Benchmarks (baselined) | PASS | `benches/git_reticulator_bench.rs` | 6 | - -Total tests: **30** (`cargo test` exit 0) -Benchmarks: **6** (Criterion; behavioural criterion benches over fixture repos are owed for the new engine) - -### Commands - -```sh -# Run all tests -cargo test - -# Compile benchmarks (no-run for CI) -cargo bench --no-run - -# Run benchmarks (writes HTML reports to target/criterion/) -cargo bench -``` - -### Next: CRG Grade B - -Requires 6 quality targets (linting, formatting, documentation coverage, etc.). -See `.machine_readable/6a2/STATE.a2ml` for details. diff --git a/TOPOLOGY.md b/TOPOLOGY.adoc similarity index 57% rename from TOPOLOGY.md rename to TOPOLOGY.adoc index f4b4a15..5916995 100644 --- a/TOPOLOGY.md +++ b/TOPOLOGY.adoc @@ -1,21 +1,20 @@ - - +== TOPOLOGY.md — git-reticulator -# TOPOLOGY.md — git-reticulator +=== Purpose -## Purpose +Semantic-lattice + embedding builder for git repositories. Turns a repo +into a typed, hierarchical, embeddable structure suited to feeding LLMs +cheaply and (eventually) provably — layer 1 of a neuro-symbolic +retrieval stack (see `+.machine_readable/6a2/NEUROSYM.a2ml+`). -Semantic-lattice + embedding builder for git repositories. Turns a repo into a -typed, hierarchical, embeddable structure suited to feeding LLMs cheaply and -(eventually) provably — layer 1 of a neuro-symbolic retrieval stack -(see `.machine_readable/6a2/NEUROSYM.a2ml`). +____ +Status legend: *IMPLEMENTED* (Rust on main) · *SKELETON* (stub/println) +· *ASPIRATIONAL* (designed in `+.affine+`, not compilable yet). +____ -> Status legend: **IMPLEMENTED** (Rust on main) · **SKELETON** (stub/println) · -> **ASPIRATIONAL** (designed in `.affine`, not compilable yet). +=== Module Map (as actually built, 2026-06-03) -## Module Map (as actually built, 2026-06-03) - -``` +.... git-reticulator/ ├── src/ │ ├── lib.rs # host library — SKELETON (println stubs) @@ -33,15 +32,16 @@ git-reticulator/ ├── benches/git_reticulator_bench.rs # criterion ├── Cargo.toml # Rust package (features: git-integration, db, embeddings…) └── Justfile # task runner -``` +.... -There are **no `.as` files** and no `build.sh`; earlier versions of this doc -listed `src/main.as`, `src/git_parser.as`, `src/semantic.as` — those never -existed. The core lives in `src/lattice/affine/*.affine`. +There are *no `+.as+` files* and no `+build.sh+`; earlier versions of +this doc listed `+src/main.as+`, `+src/git_parser.as+`, +`+src/semantic.as+` — those never existed. The core lives in +`+src/lattice/affine/*.affine+`. -## Data Flow (intended; ASPIRATIONAL end-to-end) +=== Data Flow (intended; ASPIRATIONAL end-to-end) -``` +.... [Git repo] ─►(git2)─► [files] ─► [multilevel keyword extraction] ─► [Keyword nodes + embeddings] │ [typed relationship discovery (calls/contains/…)] @@ -49,18 +49,19 @@ existed. The core lives in `src/lattice/affine/*.affine`. [Postgres + pgRouting topology] ◄── persistence │ [zoom_to_node(level)] ─► token-bounded sub-lattice ─► LLM/RAG -``` +.... -Today only the dashed CLI/REST shell exists; every box downstream of `git2` is a -stub or unbuildable. See `.machine_readable/6a2/STATE.a2ml [honest-status]`. +Today only the dashed CLI/REST shell exists; every box downstream of +`+git2+` is a stub or unbuildable. See +`+.machine_readable/6a2/STATE.a2ml [honest-status]+`. -## Key Invariants +=== Key Invariants -- **Honesty**: stubs are documented as stubs; the "lattice" claim is unearned - until `PROOF-NEEDS.md` P1/P2 are discharged (the structure is a typed digraph - with cycles — not yet a partial order). -- **LOD is the point**: `zoom_to_node` must return the *minimal* relevant - sub-lattice (token discipline), and must be sound + complete (PROOF-NEEDS P4). -- **Neuro-symbolic fusion at the node**: every `Keyword` carries both an order - position and an optional embedding (`models.affine`). -``` +* *Honesty*: stubs are documented as stubs; the "`lattice`" claim is +unearned until `+PROOF-NEEDS.md+` P1/P2 are discharged (the structure is +a typed digraph with cycles — not yet a partial order). +* *LOD is the point*: `+zoom_to_node+` must return the _minimal_ +relevant sub-lattice (token discipline), and must be sound + complete +(PROOF-NEEDS P4). +* *Neuro-symbolic fusion at the node*: every `+Keyword+` carries both an +order position and an optional embedding (`+models.affine+`). ``` diff --git a/docs/setup.md b/docs/setup.adoc similarity index 83% rename from docs/setup.md rename to docs/setup.adoc index 465fefe..90b0bcd 100644 --- a/docs/setup.md +++ b/docs/setup.adoc @@ -1,21 +1,21 @@ - -# Git-Reticulator: Database Setup +== Git-Reticulator: Database Setup -To support topological queries and hierarchical LOD (Level of Detail) zooming, Git-Reticulator uses **PostgreSQL** with the **pgRouting** extension. +To support topological queries and hierarchical LOD (Level of Detail) +zooming, Git-Reticulator uses *PostgreSQL* with the *pgRouting* +extension. -## 🐘 Prerequisites -- PostgreSQL 14+ -- PostGIS -- pgRouting +=== 🐘 Prerequisites -## 🛠️ Schema Initialization +* PostgreSQL 14+ +* PostGIS +* pgRouting + +=== 🛠️ Schema Initialization Run the following SQL to set up the semantic lattice environment: -```sql +[source,sql] +---- -- Enable necessary extensions CREATE EXTENSION IF NOT EXISTS postgis; CREATE EXTENSION IF NOT EXISTS pgrouting; @@ -58,17 +58,18 @@ CREATE TABLE IF NOT EXISTS relationships ( -- 3. Topology Generation -- After inserting relationships, run pgr_createTopology to populate source/target integers. -- This is handled by the Git-Reticulator storage engine. -``` +---- -## 🔍 Example pgRouting Query (Shortest Semantic Path) +=== 🔍 Example pgRouting Query (Shortest Semantic Path) To find the most direct semantic relationship between two nodes: -```sql +[source,sql] +---- SELECT * FROM pgr_dijkstra( 'SELECT id, source, target, cost FROM relationships', 1, -- Start node ID (integer) 50, -- End node ID (integer) directed := true ); -``` +---- diff --git a/docs/tech-debt-2026-05-26.adoc b/docs/tech-debt-2026-05-26.adoc new file mode 100644 index 0000000..5b2861d --- /dev/null +++ b/docs/tech-debt-2026-05-26.adoc @@ -0,0 +1,69 @@ +== Tech-Debt Audit — git-reticulator — 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:* `+HIGH+`. + +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 |`+MPL-2.0+` +|Body classifier |`+Palimp-MPL-2.0+` +|Severity |`+ok+` +|=== + +*Recommended next move:* none for licence. + +=== 3. Documentation debt + +[cols=",",options="header",] +|=== +|Field |Value +|README lines |12 +|`+docs/+` files |1 +|`+docs/+` LoC |70 +|CHANGELOG.md |N +|CONTRIBUTING.md |Y +|CODE_OF_CONDUCT.md |N +|SECURITY.md |Y +|Severity |`+HIGH+` +|=== + +*Recommended next move:* expand the stub README (currently 12 lines). +Minimum: title, what-it-is in one paragraph, install/usage, link to +deeper docs. Use `+hyperpolymath/rsr-template-repo+` as the reference. + +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 4e0140f..0000000 --- a/docs/tech-debt-2026-05-26.md +++ /dev/null @@ -1,57 +0,0 @@ - - -# Tech-Debt Audit — git-reticulator — 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:** `HIGH`. - -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 | `MPL-2.0` | -| Body classifier | `Palimp-MPL-2.0` | -| Severity | `ok` | - -**Recommended next move:** none for licence. - -## 3. Documentation debt - -| Field | Value | -|---|---| -| README lines | 12 | -| `docs/` files | 1 | -| `docs/` LoC | 70 | -| CHANGELOG.md | N | -| CONTRIBUTING.md | Y | -| CODE_OF_CONDUCT.md | N | -| SECURITY.md | Y | -| Severity | `HIGH` | - -**Recommended next move:** expand the stub README (currently 12 lines). Minimum: title, what-it-is in one paragraph, install/usage, link to deeper docs. Use `hyperpolymath/rsr-template-repo` as the reference. - -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/llm-warmup-dev.adoc b/llm-warmup-dev.adoc new file mode 100644 index 0000000..f1dcc7b --- /dev/null +++ b/llm-warmup-dev.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — git-reticulator (Developer) + +=== What is git-reticulator? + +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 cceb706..0000000 --- a/llm-warmup-dev.md +++ /dev/null @@ -1,20 +0,0 @@ - -# LLM Warmup — git-reticulator (Developer) - -## What is git-reticulator? -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..d2ad7be --- /dev/null +++ b/llm-warmup-user.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — git-reticulator (User) + +=== What is git-reticulator? + +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 7810e05..0000000 --- a/llm-warmup-user.md +++ /dev/null @@ -1,20 +0,0 @@ - -# LLM Warmup — git-reticulator (User) - -## What is git-reticulator? -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