From 0350bc746aa669ec3f67e73f52c02b5997693a5e Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Mon, 24 Aug 2026 08:36:01 +0100 Subject: [PATCH] refactor: migrate repository documentation from Markdown to AsciiDoc --- ARCHITECTURE.adoc | 48 ++++++++++++ ARCHITECTURE.md | 47 ------------ CHANGELOG.adoc | 79 ++++++++++++++++++++ CHANGELOG.md | 70 ------------------ CODE_OF_CONDUCT.adoc | 131 ++++----------------------------- CODE_OF_CONDUCT.md | 30 -------- CONTRIBUTING.adoc | 109 +++++++++++++++++++++++++++ CONTRIBUTING.md | 120 ------------------------------ GOVERNANCE.adoc | 60 +++++++++++++++ GOVERNANCE.md | 60 --------------- MAINTAINERS.adoc | 79 ++++++++++++-------- MAINTAINERS.md | 61 --------------- PROOF-NEEDS.adoc | 38 ++++++++++ PROOF-NEEDS.md | 29 -------- SECURITY.adoc | 23 ++++++ SECURITY.md | 25 ------- TEST-NEEDS.adoc | 82 +++++++++++++++++++++ TEST-NEEDS.md | 62 ---------------- TOPOLOGY.md => TOPOLOGY.adoc | 42 +++++------ docs/tech-debt-2026-05-26.adoc | 71 ++++++++++++++++++ docs/tech-debt-2026-05-26.md | 56 -------------- llm-warmup-dev.adoc | 19 +++++ llm-warmup-dev.md | 20 ----- llm-warmup-user.adoc | 19 +++++ llm-warmup-user.md | 20 ----- 25 files changed, 629 insertions(+), 771 deletions(-) create mode 100644 ARCHITECTURE.adoc delete mode 100644 ARCHITECTURE.md create mode 100644 CHANGELOG.adoc delete mode 100644 CHANGELOG.md delete mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.adoc delete mode 100644 CONTRIBUTING.md create mode 100644 GOVERNANCE.adoc delete mode 100644 GOVERNANCE.md delete mode 100644 MAINTAINERS.md create mode 100644 PROOF-NEEDS.adoc delete mode 100644 PROOF-NEEDS.md create mode 100644 SECURITY.adoc delete mode 100644 SECURITY.md create mode 100644 TEST-NEEDS.adoc delete mode 100644 TEST-NEEDS.md rename TOPOLOGY.md => TOPOLOGY.adoc (89%) create mode 100644 docs/tech-debt-2026-05-26.adoc delete mode 100644 docs/tech-debt-2026-05-26.md create mode 100644 llm-warmup-dev.adoc delete mode 100644 llm-warmup-dev.md create mode 100644 llm-warmup-user.adoc delete mode 100644 llm-warmup-user.md 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..b58a56d --- /dev/null +++ b/CHANGELOG.adoc @@ -0,0 +1,79 @@ +== Changelog + +All notable changes to `+polysafe-gitfixer+` 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: add stapeln.toml container definition +* feat: add UX Justfile with doctor, tour, help-me, assail recipes +* feat: deploy UX Manifesto infrastructure +* feat: add CLADE.a2ml — clade taxonomy declaration +* feat(ci): enable Hypatia scanning + +==== Fixed + +* fix(ci): bump a2ml/k9-validate-action pins to canonical (#19) +* fix(ci): sync hypatia-scan.yml to canonical (#18) +* fix(ci): Phase-2 fleet submission must not fail the security gate +(#17) +* fix(ci): hypatia-scan workdir ($\{\{ env.HOME }} resolves empty) (#16) +* fix(ci): hypatia-scan.yml – –exit-zero + GITHUB_TOKEN +(hyperpolymath/hypatia#213) (#13) +* fix(ci): rsr-antipattern duplicate heredoc + setup-beam ubuntu24 (#14) +* fix(ci): update hypatia binary detection (check '`hypatia`' before +'`hypatia-v2`') +* fix: implement NIF bindings for polysafe-gitfixer, replacing 12 hollow +stubs +* fix(scorecard): enforce granular permissions and add fuzzing +placeholder +* fix(ci): Resolve workflow-linter self-matching and metadata issues + +==== Changed + +* refactor: migrate 6SCM → 6A2 (.scm → .a2ml format) + +==== Documentation + +* docs: substantive CRG C annotation (EXPLAINME.adoc) +* docs: add TEST-NEEDS.md and/or PROOF-NEEDS.md from audit +* docs: add EXPLAINME.adoc — prove-it file backing README claims +* docs: update SCM files with project information +* docs: add CONTRIBUTING.md +* docs: add SCM checkpoint files +* docs: add checkpoint files for state tracking + +==== CI + +* ci: redistribute concurrency-cancel guard to read-only check workflows +(#21) +* ci: bump actions/upload-artifact SHA to current v4 (#12) +* ci: SHA-pin hyperpolymath validate-actions in dogfood-gate +* ci(antipattern): fix top-level dir + benchmark/lsp filename matching +(#11) +* ci(antipattern): TS check reads .claude/CLAUDE.md exemption table +(#10) + +=== 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 5c999d2..0000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,70 +0,0 @@ - -# Changelog - -All notable changes to `polysafe-gitfixer` 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: add stapeln.toml container definition -- feat: add UX Justfile with doctor, tour, help-me, assail recipes -- feat: deploy UX Manifesto infrastructure -- feat: add CLADE.a2ml — clade taxonomy declaration -- feat(ci): enable Hypatia scanning - -### Fixed - -- fix(ci): bump a2ml/k9-validate-action pins to canonical (#19) -- fix(ci): sync hypatia-scan.yml to canonical (#18) -- fix(ci): Phase-2 fleet submission must not fail the security gate (#17) -- fix(ci): hypatia-scan workdir (${{ env.HOME }} resolves empty) (#16) -- fix(ci): hypatia-scan.yml -- --exit-zero + GITHUB_TOKEN (hyperpolymath/hypatia#213) (#13) -- fix(ci): rsr-antipattern duplicate heredoc + setup-beam ubuntu24 (#14) -- fix(ci): update hypatia binary detection (check 'hypatia' before 'hypatia-v2') -- fix: implement NIF bindings for polysafe-gitfixer, replacing 12 hollow stubs -- fix(scorecard): enforce granular permissions and add fuzzing placeholder -- fix(ci): Resolve workflow-linter self-matching and metadata issues - -### Changed - -- refactor: migrate 6SCM → 6A2 (.scm → .a2ml format) - -### Documentation - -- docs: substantive CRG C annotation (EXPLAINME.adoc) -- docs: add TEST-NEEDS.md and/or PROOF-NEEDS.md from audit -- docs: add EXPLAINME.adoc — prove-it file backing README claims -- docs: update SCM files with project information -- docs: add CONTRIBUTING.md -- docs: add SCM checkpoint files -- docs: add checkpoint files for state tracking - -### CI - -- ci: redistribute concurrency-cancel guard to read-only check workflows (#21) -- ci: bump actions/upload-artifact SHA to current v4 (#12) -- ci: SHA-pin hyperpolymath validate-actions in dogfood-gate -- ci(antipattern): fix top-level dir + benchmark/lsp filename matching (#11) -- ci(antipattern): TS check reads .claude/CLAUDE.md exemption table (#10) - -## 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 index 94e7aa9..bd2a83c 100644 --- a/CODE_OF_CONDUCT.adoc +++ b/CODE_OF_CONDUCT.adoc @@ -1,125 +1,24 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -// Copyright (c) Jonathan D.A. Jewell -= Code of Conduct -:toc: -:toc-placement!: +== Contributor Covenant Code of Conduct -toc::[] +=== Our Pledge -== Our Pledge +We pledge to make participation a harassment-free experience for +everyone. -We as members, contributors, and leaders pledge to make participation in our -community a harassment-free experience for everyone, regardless of age, body -size, visible or invisible disability, ethnicity, sex characteristics, gender -identity and expression, level of experience, education, socio-economic status, -nationality, personal appearance, race, caste, color, religion, or sexual -identity and orientation. +=== Our Standards -We pledge to act and interact in ways that contribute to an open, welcoming, -diverse, inclusive, and healthy community. +*Positive behavior:* * Using welcoming language * Being respectful of +differing viewpoints * Accepting constructive criticism * Focusing on +what is best for the community -== Our Standards +*Unacceptable behavior:* * Harassment, trolling, or personal attacks * +Publishing private information without permission -=== Positive Behaviors +=== Enforcement -Examples of behavior that contributes to a positive environment: +Report issues to the maintainers. All complaints will be reviewed. -* Demonstrating empathy and kindness toward other people -* Being respectful of differing opinions, viewpoints, and experiences -* Giving and gracefully accepting constructive feedback -* Accepting responsibility for our mistakes and learning from them -* Focusing on what is best for the overall community -* Using welcoming and inclusive language -* Being patient with newcomers learning the codebase +=== Attribution -=== Unacceptable Behaviors - -Examples of unacceptable behavior: - -* The use of sexualized language or imagery, and sexual attention or advances -* Trolling, insulting or derogatory comments, and personal or political attacks -* Public or private harassment -* Publishing others' private information without explicit permission -* Deliberately intimidating, stalking, or following -* Other conduct which could reasonably be considered inappropriate - -== Scope - -This Code of Conduct applies within all community spaces, including: - -* GitLab/GitHub repositories (issues, merge requests, comments) -* Project documentation and wikis -* Community chat channels -* Project events and meetups -* Social media interactions representing the project - -It also applies when an individual is officially representing the community -in public spaces. - -== Enforcement - -=== Reporting - -Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported to the project maintainers listed in `MAINTAINERS.md`. - -All complaints will be reviewed and investigated promptly and fairly. -Maintainers are obligated to respect the privacy and security of the -reporter of any incident. - -=== Enforcement Guidelines - -Maintainers will follow these guidelines in determining consequences: - -==== 1. Correction - -**Community Impact**: Use of inappropriate language or other behavior deemed -unprofessional. - -**Consequence**: A private, written warning providing clarity around the -nature of the violation and an explanation of why the behavior was -inappropriate. A public apology may be requested. - -==== 2. Warning - -**Community Impact**: A violation through a single incident or series of -actions. - -**Consequence**: A warning with consequences for continued behavior. No -interaction with the people involved for a specified period. This includes -avoiding interactions in community spaces as well as external channels. -Violating these terms may lead to a temporary or permanent ban. - -==== 3. Temporary Ban - -**Community Impact**: A serious violation of community standards, including -sustained inappropriate behavior. - -**Consequence**: A temporary ban from any sort of interaction or public -communication with the community for a specified period. No public or -private interaction with the people involved is allowed during this period. -Violating these terms may lead to a permanent ban. - -==== 4. Permanent Ban - -**Community Impact**: Demonstrating a pattern of violation of community -standards, including sustained inappropriate behavior, harassment, or -aggression toward individuals or groups. - -**Consequence**: A permanent ban from any sort of public interaction within -the community. - -== Attribution - -This Code of Conduct is adapted from the -https://www.contributor-covenant.org[Contributor Covenant], version 2.1, -available at -https://www.contributor-covenant.org/version/2/1/code_of_conduct.html - -Community Impact Guidelines were inspired by -https://github.com/mozilla/diversity[Mozilla's code of conduct enforcement ladder]. - -== Questions - -For questions about this Code of Conduct, please open an issue or contact -the maintainers directly. +Adapted from https://www.contributor-covenant.org/[Contributor Covenant] +v2.1. diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md deleted file mode 100644 index bbe9219..0000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,30 +0,0 @@ - -# Contributor Covenant Code of Conduct - -## Our Pledge - -We pledge to make participation a harassment-free experience for everyone. - -## Our Standards - -**Positive behavior:** -* Using welcoming language -* Being respectful of differing viewpoints -* Accepting constructive criticism -* Focusing on what is best for the community - -**Unacceptable behavior:** -* Harassment, trolling, or personal attacks -* Publishing private information without permission - -## Enforcement - -Report issues to the maintainers. All complaints will be reviewed. - -## Attribution - -Adapted from [Contributor Covenant](https://www.contributor-covenant.org/) v2.1. - diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc new file mode 100644 index 0000000..64fec0f --- /dev/null +++ b/CONTRIBUTING.adoc @@ -0,0 +1,109 @@ +== Clone the repository + +git clone https://github.com/hyperpolymath/polysafe-gitfixer.git cd +polysafe-gitfixer + +== Using Nix (recommended for reproducibility) + +nix develop + +== Or using toolbox/distrobox + +toolbox create polysafe-gitfixer-dev toolbox enter polysafe-gitfixer-dev +# Install dependencies manually + +== Verify setup + +just check # or: cargo check / mix compile / etc. just test # Run test +suite + +.... + +### Repository Structure +.... + +polysafe-gitfixer/ ├── src/ # Source code (Perimeter 1-2) ├── lib/ # +Library code (Perimeter 1-2) ├── extensions/ # Extensions (Perimeter 2) +├── plugins/ # Plugins (Perimeter 2) ├── tools/ # Tooling (Perimeter 2) +├── docs/ # Documentation (Perimeter 3) │ ├── architecture/ # ADRs, +specs (Perimeter 2) │ └── proposals/ # RFCs (Perimeter 3) ├── examples/ +# Examples (Perimeter 3) ├── spec/ # Spec tests (Perimeter 3) ├── tests/ +# Test suite (Perimeter 2-3) ├── .well-known/ # Protocol files +(Perimeter 1-3) ├── .github/ # GitHub config (Perimeter 1) │ ├── +ISSUE_TEMPLATE/ │ └── workflows/ ├── CHANGELOG.md ├── CODE_OF_CONDUCT.md +├── CONTRIBUTING.md # This file ├── GOVERNANCE.md ├── LICENSE ├── +MAINTAINERS.md ├── README.adoc ├── SECURITY.md ├── flake.nix # Nix flake +(Perimeter 1) └── justfile # Task runner (Perimeter 1) + +.... + +--- + +## How to Contribute + +### Reporting Bugs + +**Before reporting**: +1. Search existing issues +2. Check if it's already fixed in `main` +3. Determine which perimeter the bug affects + +**When reporting**: + +Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) and include: + +- Clear, descriptive title +- Environment details (OS, versions, toolchain) +- Steps to reproduce +- Expected vs actual behaviour +- Logs, screenshots, or minimal reproduction + +### Suggesting Features + +**Before suggesting**: +1. Check the [roadmap](ROADMAP.md) if available +2. Search existing issues and discussions +3. Consider which perimeter the feature belongs to + +**When suggesting**: + +Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) and include: + +- Problem statement (what pain point does this solve?) +- Proposed solution +- Alternatives considered +- Which perimeter this affects + +### Your First Contribution + +Look for issues labelled: + +- [`good first issue`](https://github.com/hyperpolymath/polysafe-gitfixer/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://github.com/hyperpolymath/polysafe-gitfixer/labels/help%20wanted) — Community help needed +- [`documentation`](https://github.com/hyperpolymath/polysafe-gitfixer/labels/documentation) — Docs improvements +- [`perimeter-3`](https://github.com/hyperpolymath/polysafe-gitfixer/labels/perimeter-3) — Community sandbox scope + +--- + +## Development Workflow + +### Branch Naming +.... + +docs/short-description # Documentation (P3) test/what-added # Test +additions (P3) feat/short-description # New features (P2) +fix/issue-number-description # Bug fixes (P2) refactor/what-changed # +Code improvements (P2) security/what-fixed # Security fixes (P1-2) + +.... + +### Commit Messages + +We follow [Conventional Commits](https://www.conventionalcommits.org/): +.... + +(): + +{empty}[optional body] + +{empty}[optional footer] diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 3777246..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,120 +0,0 @@ - -# Clone the repository -git clone https://github.com/hyperpolymath/polysafe-gitfixer.git -cd polysafe-gitfixer - -# Using Nix (recommended for reproducibility) -nix develop - -# Or using toolbox/distrobox -toolbox create polysafe-gitfixer-dev -toolbox enter polysafe-gitfixer-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure -``` -polysafe-gitfixer/ -├── src/ # Source code (Perimeter 1-2) -├── lib/ # Library code (Perimeter 1-2) -├── extensions/ # Extensions (Perimeter 2) -├── plugins/ # Plugins (Perimeter 2) -├── tools/ # Tooling (Perimeter 2) -├── docs/ # Documentation (Perimeter 3) -│ ├── architecture/ # ADRs, specs (Perimeter 2) -│ └── proposals/ # RFCs (Perimeter 3) -├── examples/ # Examples (Perimeter 3) -├── spec/ # Spec tests (Perimeter 3) -├── tests/ # Test suite (Perimeter 2-3) -├── .well-known/ # Protocol files (Perimeter 1-3) -├── .github/ # GitHub config (Perimeter 1) -│ ├── ISSUE_TEMPLATE/ -│ └── workflows/ -├── CHANGELOG.md -├── CODE_OF_CONDUCT.md -├── CONTRIBUTING.md # This file -├── GOVERNANCE.md -├── LICENSE -├── MAINTAINERS.md -├── README.adoc -├── SECURITY.md -├── flake.nix # Nix flake (Perimeter 1) -└── justfile # Task runner (Perimeter 1) -``` - ---- - -## How to Contribute - -### Reporting Bugs - -**Before reporting**: -1. Search existing issues -2. Check if it's already fixed in `main` -3. Determine which perimeter the bug affects - -**When reporting**: - -Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) and include: - -- Clear, descriptive title -- Environment details (OS, versions, toolchain) -- Steps to reproduce -- Expected vs actual behaviour -- Logs, screenshots, or minimal reproduction - -### Suggesting Features - -**Before suggesting**: -1. Check the [roadmap](ROADMAP.md) if available -2. Search existing issues and discussions -3. Consider which perimeter the feature belongs to - -**When suggesting**: - -Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) and include: - -- Problem statement (what pain point does this solve?) -- Proposed solution -- Alternatives considered -- Which perimeter this affects - -### Your First Contribution - -Look for issues labelled: - -- [`good first issue`](https://github.com/hyperpolymath/polysafe-gitfixer/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://github.com/hyperpolymath/polysafe-gitfixer/labels/help%20wanted) — Community help needed -- [`documentation`](https://github.com/hyperpolymath/polysafe-gitfixer/labels/documentation) — Docs improvements -- [`perimeter-3`](https://github.com/hyperpolymath/polysafe-gitfixer/labels/perimeter-3) — Community sandbox scope - ---- - -## Development Workflow - -### Branch Naming -``` -docs/short-description # Documentation (P3) -test/what-added # Test additions (P3) -feat/short-description # New features (P2) -fix/issue-number-description # Bug fixes (P2) -refactor/what-changed # Code improvements (P2) -security/what-fixed # Security fixes (P1-2) -``` - -### Commit Messages - -We follow [Conventional Commits](https://www.conventionalcommits.org/): -``` -(): - -[optional body] - -[optional footer] diff --git a/GOVERNANCE.adoc b/GOVERNANCE.adoc 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/MAINTAINERS.adoc b/MAINTAINERS.adoc index aa23a55..5bcd440 100644 --- a/MAINTAINERS.adoc +++ b/MAINTAINERS.adoc @@ -1,48 +1,65 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -// Copyright (c) Jonathan D.A. Jewell -= Maintainers -:toc: preamble +== Maintainers -This document lists the maintainers of this project and their responsibilities. +This file lists the maintainers of polysafe-gitfixer and their areas of +responsibility. -== Current Maintainers +=== Core Maintainers -[cols="2,3,2",options="header"] +Core maintainers have full access to all project systems and final say +on architectural decisions. + +[width="100%",cols="18%,42%,20%,20%",options="header",] +|=== +|Name |GitLab/GitHub |Areas |Since +|Jonathan D.A. Jewell |@Hyperpolymath |Architecture, Rust, Security +|2024 |=== -| Name | Role | Contact -| Jonathan D.A. Jewell -| Lead Maintainer -| https://github.com/hyperpolymath[@hyperpolymath] +=== Component Leads + +Component leads have expertise in specific areas and help review related +changes. + +[cols=",,,",options="header",] +|=== +|Component |Language |Lead |Backup +|capability |Rust |@Hyperpolymath |- +|fs_ops |Rust |@Hyperpolymath |- +|git_ops |Rust |@Hyperpolymath |- +|diff-engine |Haskell |- |- +|tui |Haskell |- |- +|workflow |Idris/Haskell |- |- +|orchestrator |Elixir |- |- |=== -== Responsibilities +=== Emeritus Maintainers + +Former maintainers who have stepped back but made significant +contributions. -Maintainers are responsible for: +_None yet_ -* Reviewing and merging pull requests -* Triaging issues and feature requests -* Ensuring code quality and security standards -* Managing releases and versioning -* Upholding the project's code of conduct +=== Becoming a Maintainer -== Becoming a Maintainer +See GOVERNANCE.adoc for the process of becoming a maintainer. -Contributors who demonstrate: +In brief: 1. Sustained high-quality contributions 2. Demonstrated good +judgment in code reviews 3. Nomination by existing maintainer 4. +Consensus approval from core team -* Consistent, high-quality contributions -* Understanding of the project's goals and standards -* Constructive participation in discussions -* Commitment to the project's long-term health +=== Contact -May be invited to become maintainers at the discretion of existing maintainers. +* *Security issues*: See SECURITY.md +* *General questions*: Open an issue +* *Private matters*: Contact maintainers via GitLab/GitHub -== Decision Making +=== Attribution -* Routine decisions (bug fixes, minor improvements) can be made by any maintainer -* Significant changes require discussion and consensus among maintainers -* Breaking changes or major features should be discussed in issues before implementation +All contributors are listed in `+.well-known/humans.txt+` and +acknowledged in release notes for their specific contributions. -== Contact +''''' -For questions about project governance, open an issue or contact the maintainers listed above. +_This file follows the +https://gitlab.com/Hyperpolymath/rhodium-standard-repositories[Rhodium +Standard] format._ diff --git a/MAINTAINERS.md b/MAINTAINERS.md deleted file mode 100644 index 25005f2..0000000 --- a/MAINTAINERS.md +++ /dev/null @@ -1,61 +0,0 @@ - -# Maintainers - -This file lists the maintainers of polysafe-gitfixer and their areas of responsibility. - -## Core Maintainers - -Core maintainers have full access to all project systems and final say on -architectural decisions. - -| Name | GitLab/GitHub | Areas | Since | -|------|---------------|-------|-------| -| Jonathan D.A. Jewell | @Hyperpolymath | Architecture, Rust, Security | 2024 | - -## Component Leads - -Component leads have expertise in specific areas and help review related changes. - -| Component | Language | Lead | Backup | -|-----------|----------|------|--------| -| capability | Rust | @Hyperpolymath | - | -| fs_ops | Rust | @Hyperpolymath | - | -| git_ops | Rust | @Hyperpolymath | - | -| diff-engine | Haskell | - | - | -| tui | Haskell | - | - | -| workflow | Idris/Haskell | - | - | -| orchestrator | Elixir | - | - | - -## Emeritus Maintainers - -Former maintainers who have stepped back but made significant contributions. - -*None yet* - -## Becoming a Maintainer - -See [GOVERNANCE.adoc](GOVERNANCE.adoc) for the process of becoming a maintainer. - -In brief: -1. Sustained high-quality contributions -2. Demonstrated good judgment in code reviews -3. Nomination by existing maintainer -4. Consensus approval from core team - -## Contact - -- **Security issues**: See [SECURITY.md](SECURITY.md) -- **General questions**: Open an issue -- **Private matters**: Contact maintainers via GitLab/GitHub - -## Attribution - -All contributors are listed in `.well-known/humans.txt` and acknowledged -in release notes for their specific contributions. - ---- - -*This file follows the [Rhodium Standard](https://gitlab.com/Hyperpolymath/rhodium-standard-repositories) format.* diff --git a/PROOF-NEEDS.adoc b/PROOF-NEEDS.adoc new file mode 100644 index 0000000..1002d04 --- /dev/null +++ b/PROOF-NEEDS.adoc @@ -0,0 +1,38 @@ +== PROOF-NEEDS.md — polysafe-gitfixer + +=== Current State + +* **src/abi/*.idr**: NO +* *Dangerous patterns*: 0 +* *LOC*: ~1,400 (Rust + Elixir NIFs) +* *ABI layer*: Missing + +=== What Needs Proving + +[width="100%",cols="51%,27%,22%",options="header",] +|=== +|Component |What |Why +|Capability system |Capability grants are minimal and non-escalating +|Over-privileged operations can damage repositories + +|Git operations |Git modifications preserve repository integrity +|Corrupting git repos is catastrophic + +|File system operations |FS ops respect capability boundaries |Escaping +sandbox damages the host system + +|NIF safety |Elixir NIF bridge does not corrupt BEAM VM memory |NIF bugs +crash the entire Erlang VM +|=== + +=== Recommended Prover + +*Idris2* — Create `+src/abi/+` with capability types (indexed by +permission set). Git operation correctness proofs would ensure repo +integrity is preserved. + +=== Priority + +*MEDIUM* — Git repository fixer that modifies repos. The capability +system is the most important proof target — it bounds what the tool can +do. Small codebase makes full coverage achievable. diff --git a/PROOF-NEEDS.md b/PROOF-NEEDS.md deleted file mode 100644 index 91601b6..0000000 --- a/PROOF-NEEDS.md +++ /dev/null @@ -1,29 +0,0 @@ - -# PROOF-NEEDS.md — polysafe-gitfixer - -## Current State - -- **src/abi/*.idr**: NO -- **Dangerous patterns**: 0 -- **LOC**: ~1,400 (Rust + Elixir NIFs) -- **ABI layer**: Missing - -## What Needs Proving - -| Component | What | Why | -|-----------|------|-----| -| Capability system | Capability grants are minimal and non-escalating | Over-privileged operations can damage repositories | -| Git operations | Git modifications preserve repository integrity | Corrupting git repos is catastrophic | -| File system operations | FS ops respect capability boundaries | Escaping sandbox damages the host system | -| NIF safety | Elixir NIF bridge does not corrupt BEAM VM memory | NIF bugs crash the entire Erlang VM | - -## Recommended Prover - -**Idris2** — Create `src/abi/` with capability types (indexed by permission set). Git operation correctness proofs would ensure repo integrity is preserved. - -## Priority - -**MEDIUM** — Git repository fixer that modifies repos. The capability system is the most important proof target — it bounds what the tool can do. Small codebase makes full coverage achievable. diff --git a/SECURITY.adoc b/SECURITY.adoc new file mode 100644 index 0000000..1288150 --- /dev/null +++ b/SECURITY.adoc @@ -0,0 +1,23 @@ +== Security Policy + +=== Supported Versions + +Use this section to tell people about which versions of your project are +currently being supported with security updates. + +[cols=",",options="header",] +|=== +|Version |Supported +|5.1.x |:white_check_mark: +|5.0.x |:x: +|4.0.x |:white_check_mark: +|< 4.0 |:x: +|=== + +=== Reporting a Vulnerability + +Use this section to tell people how to report a vulnerability. + +Tell them where to go, how often they can expect to get an update on a +reported vulnerability, what to expect if the vulnerability is accepted +or declined, etc. diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index 062acbd..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,25 +0,0 @@ - -# Security Policy - -## Supported Versions - -Use this section to tell people about which versions of your project are -currently being supported with security updates. - -| Version | Supported | -| ------- | ------------------ | -| 5.1.x | :white_check_mark: | -| 5.0.x | :x: | -| 4.0.x | :white_check_mark: | -| < 4.0 | :x: | - -## Reporting a Vulnerability - -Use this section to tell people how to report a vulnerability. - -Tell them where to go, how often they can expect to get an update on a -reported vulnerability, what to expect if the vulnerability is accepted or -declined, etc. diff --git a/TEST-NEEDS.adoc b/TEST-NEEDS.adoc new file mode 100644 index 0000000..d89df05 --- /dev/null +++ b/TEST-NEEDS.adoc @@ -0,0 +1,82 @@ +== TEST-NEEDS.md — polysafe-gitfixer + +=== CRG Grade: C — ACHIEVED 2026-04-04 + +____ +Generated 2026-03-29 by punishing audit. +____ + +=== Current State + +[cols=",,",options="header",] +|=== +|Category |Count |Notes +|Unit tests |0 |No inline tests, no test files +|Integration |0 |None +|E2E |0 |None +|Benchmarks |0 |None +|=== + +*Source modules:* 6 Rust source files across 4 crates: capability +(audit_log.rs, dir_capability.rs, lib.rs), fs_ops (lib.rs), git_ops +(lib.rs), polysafe_nifs (lib.rs). + +=== What’s Missing + +==== P2P (Property-Based) Tests + +* [ ] Dir capability: property tests for capability +creation/verification invariants +* [ ] Audit log: property tests for log entry integrity +* [ ] fs_ops: property tests for filesystem operation safety (no +escaping sandbox) +* [ ] git_ops: property tests for git operation correctness + +==== E2E Tests + +* [ ] Full fix cycle: detect issue -> create capability -> apply fix -> +audit -> verify +* [ ] Git operation: clone -> modify -> commit -> verify integrity +* [ ] Capability lifecycle: create -> use -> revoke -> verify revoked + +==== Aspect Tests + +* *Security:* A git fixing tool with capabilities and audit logging has +ZERO security tests. Capability bypass, audit log tampering, path +traversal in fs_ops, git injection — ALL untested +* *Performance:* No benchmarks for fix throughput +* *Concurrency:* No tests for concurrent fix operations, capability +contention +* *Error handling:* No tests for git operation failure, filesystem +permission denied, corrupted audit log + +==== Build & Execution + +* [ ] `+cargo test+` across all 4 crates + +==== Benchmarks Needed + +* [ ] Git operation speed +* [ ] Capability validation overhead +* [ ] Audit logging throughput + +==== Self-Tests + +* [ ] Fix its own repository as smoke test +* [ ] Capability system self-test +* [ ] Audit log integrity verification + +=== Priority + +*CRITICAL.* 6 source files, ZERO tests of any kind. A capability-based +security tool with an audit log that has never been tested. The +capability and audit_log modules are security-critical and completely +unverified. This is one of the worst test situations in the entire scan. + +=== FAKE-FUZZ ALERT + +* `+tests/fuzz/placeholder.txt+` is a scorecard placeholder inherited +from rsr-template-repo — it does NOT provide real fuzz testing +* Replace with an actual fuzz harness (see +rsr-template-repo/tests/fuzz/README.adoc) or remove the file +* Priority: P2 — creates false impression of fuzz coverage diff --git a/TEST-NEEDS.md b/TEST-NEEDS.md deleted file mode 100644 index 4962e05..0000000 --- a/TEST-NEEDS.md +++ /dev/null @@ -1,62 +0,0 @@ - -# TEST-NEEDS.md — polysafe-gitfixer - -## CRG Grade: C — ACHIEVED 2026-04-04 - -> Generated 2026-03-29 by punishing audit. - -## Current State - -| Category | Count | Notes | -|-------------|-------|-------| -| Unit tests | 0 | No inline tests, no test files | -| Integration | 0 | None | -| E2E | 0 | None | -| Benchmarks | 0 | None | - -**Source modules:** 6 Rust source files across 4 crates: capability (audit_log.rs, dir_capability.rs, lib.rs), fs_ops (lib.rs), git_ops (lib.rs), polysafe_nifs (lib.rs). - -## What's Missing - -### P2P (Property-Based) Tests -- [ ] Dir capability: property tests for capability creation/verification invariants -- [ ] Audit log: property tests for log entry integrity -- [ ] fs_ops: property tests for filesystem operation safety (no escaping sandbox) -- [ ] git_ops: property tests for git operation correctness - -### E2E Tests -- [ ] Full fix cycle: detect issue -> create capability -> apply fix -> audit -> verify -- [ ] Git operation: clone -> modify -> commit -> verify integrity -- [ ] Capability lifecycle: create -> use -> revoke -> verify revoked - -### Aspect Tests -- **Security:** A git fixing tool with capabilities and audit logging has ZERO security tests. Capability bypass, audit log tampering, path traversal in fs_ops, git injection — ALL untested -- **Performance:** No benchmarks for fix throughput -- **Concurrency:** No tests for concurrent fix operations, capability contention -- **Error handling:** No tests for git operation failure, filesystem permission denied, corrupted audit log - -### Build & Execution -- [ ] `cargo test` across all 4 crates - -### Benchmarks Needed -- [ ] Git operation speed -- [ ] Capability validation overhead -- [ ] Audit logging throughput - -### Self-Tests -- [ ] Fix its own repository as smoke test -- [ ] Capability system self-test -- [ ] Audit log integrity verification - -## Priority - -**CRITICAL.** 6 source files, ZERO tests of any kind. A capability-based security tool with an audit log that has never been tested. The capability and audit_log modules are security-critical and completely unverified. This is one of the worst test situations in the entire scan. - -## FAKE-FUZZ ALERT - -- `tests/fuzz/placeholder.txt` is a scorecard placeholder inherited from rsr-template-repo — it does NOT provide real fuzz testing -- Replace with an actual fuzz harness (see rsr-template-repo/tests/fuzz/README.adoc) or remove the file -- Priority: P2 — creates false impression of fuzz coverage diff --git a/TOPOLOGY.md b/TOPOLOGY.adoc similarity index 89% rename from TOPOLOGY.md rename to TOPOLOGY.adoc index 8e4911a..2ef5b4f 100644 --- a/TOPOLOGY.md +++ b/TOPOLOGY.adoc @@ -1,15 +1,8 @@ - - - +== polysafe-gitfixer — Project Topology -# polysafe-gitfixer — Project Topology +=== System Architecture -## System Architecture - -``` +.... ┌─────────────────────────────────────────┐ │ OPERATOR / CLI │ │ (Haskell TUI / Brick) │ @@ -54,11 +47,11 @@ Copyright (c) Jonathan D.A. Jewell │ Justfile / Mustfile .machine_readable/ │ │ Nickel Configs RSR Gold (Cert) │ └─────────────────────────────────────────┘ -``` +.... -## Completion Dashboard +=== Completion Dashboard -``` +.... COMPONENT STATUS NOTES ───────────────────────────────── ────────────────── ───────────────────────────────── CORE COMPONENTS @@ -79,25 +72,26 @@ REPO INFRASTRUCTURE ───────────────────────────────────────────────────────────────────────────── OVERALL: █████████░ ~95% Production-grade tool stable -``` +.... -## Key Dependencies +=== Key Dependencies -``` +.... Nickel Config ───► Idris State ────► Elixir Supervisor ───► Rust FS Ops │ │ │ │ ▼ ▼ ▼ ▼ Haskell TUI ◄───► Haskell Diff ◄───► Rust Git Ops ────────► Repository -``` +.... -## Update Protocol +=== Update Protocol This file is maintained by both humans and AI agents. When updating: -1. **After completing a component**: Change its bar and percentage -2. **After adding a component**: Add a new row in the appropriate section -3. **After architectural changes**: Update the ASCII diagram -4. **Date**: Update the `Last updated` comment at the top of this file +[arabic] +. *After completing a component*: Change its bar and percentage +. *After adding a component*: Add a new row in the appropriate section +. *After architectural changes*: Update the ASCII diagram +. *Date*: Update the `+Last updated+` comment at the top of this file -Progress bars use: `█` (filled) and `░` (empty), 10 characters wide. -Percentages: 0%, 10%, 20%, ... 100% (in 10% increments). +Progress bars use: `+█+` (filled) and `+░+` (empty), 10 characters wide. +Percentages: 0%, 10%, 20%, … 100% (in 10% increments). diff --git a/docs/tech-debt-2026-05-26.adoc b/docs/tech-debt-2026-05-26.adoc new file mode 100644 index 0000000..a1e24f9 --- /dev/null +++ b/docs/tech-debt-2026-05-26.adoc @@ -0,0 +1,71 @@ +== Tech-Debt Audit — polysafe-gitfixer — 2026-05-26 + +*Source:* estate-wide automated scan 2026-05-26. *Companion:* +https://github.com/hyperpolymath/standards/tree/main/docs/audits[`+hyperpolymath/standards+` +2026-05-26-estate-*-debt audits]. *Combined severity:* `+MEDIUM+`. + +This file records the _raw findings_ — it does not by itself fix the +debt. Each section ends with a '`Recommended next move`' line; closing +the debt is follow-up work. + +=== 1. Proof debt + +No proof-bearing files (`+*.v+`, `+*.lean+`, `+*.agda+`, `+*.idr+`, +`+*.idr2+`, `+*.fst+`, `+*.dfy+`, `+*.tla+`, `+*.ads+`, `+*.adb+`) found +in this repo. + +*Recommended next move:* none. + +=== 2. Licence debt + +[cols=",",options="header",] +|=== +|Field |Value +|LICENSE file |`+LICENSE+` +|SPDX header |`+MPL-2.0+` +|Manifest licence |`+NONE+` +|Body classifier |`+Palimp-MPL-2.0+` +|Severity |`+ok+` +|=== + +*Recommended next move:* none for licence. + +=== 3. Documentation debt + +[cols=",",options="header",] +|=== +|Field |Value +|README lines |216 +|`+docs/+` files |0 +|`+docs/+` LoC |0 +|CHANGELOG.md |N +|CONTRIBUTING.md |Y +|CODE_OF_CONDUCT.md |Y +|SECURITY.md |Y +|Severity |`+MEDIUM+` +|=== + +*Recommended next move:* introduce a `+docs/+` directory. The README at +216 lines has likely grown to do the work of `+docs/+` — split it into a +thin README + `+docs/architecture.md+`, `+docs/usage.md+`, etc. +Heavy-wiki exemplars to copy from: `+affinescript+`, `+boj-server+`, +`+echidna+`, `+hypatia+`. + +Additionally: *CHANGELOG.md is missing.* 65% of estate repos lack one — +adopting a CHANGELOG (or auto-generating via `+git-cliff+`) is a +recommended estate-wide follow-up. + +=== Cross-references + +* Estate proof-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-proof-debt.md+` +* Estate licence-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-licence-debt.md+` +* Estate documentation-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-documentation-debt.md+` + +''''' + +🤖 Generated by Claude Code estate-wide tech-debt scan (2026-05-26). +This file is informational — closing the debt is follow-up work owned by +the maintainer. diff --git a/docs/tech-debt-2026-05-26.md b/docs/tech-debt-2026-05-26.md deleted file mode 100644 index a0ce7ee..0000000 --- a/docs/tech-debt-2026-05-26.md +++ /dev/null @@ -1,56 +0,0 @@ - -# Tech-Debt Audit — polysafe-gitfixer — 2026-05-26 - -**Source:** estate-wide automated scan 2026-05-26. -**Companion:** [`hyperpolymath/standards` 2026-05-26-estate-*-debt audits](https://github.com/hyperpolymath/standards/tree/main/docs/audits). -**Combined severity:** `MEDIUM`. - -This file records the *raw findings* — it does not by itself fix the debt. Each section ends with a 'Recommended next move' line; closing the debt is follow-up work. - -## 1. Proof debt - -No proof-bearing files (`*.v`, `*.lean`, `*.agda`, `*.idr`, `*.idr2`, `*.fst`, `*.dfy`, `*.tla`, `*.ads`, `*.adb`) found in this repo. - -**Recommended next move:** none. - -## 2. Licence debt - -| Field | Value | -|---|---| -| LICENSE file | `LICENSE` | -| SPDX header | `MPL-2.0` | -| Manifest licence | `NONE` | -| Body classifier | `Palimp-MPL-2.0` | -| Severity | `ok` | - -**Recommended next move:** none for licence. - -## 3. Documentation debt - -| Field | Value | -|---|---| -| README lines | 216 | -| `docs/` files | 0 | -| `docs/` LoC | 0 | -| CHANGELOG.md | N | -| CONTRIBUTING.md | Y | -| CODE_OF_CONDUCT.md | Y | -| SECURITY.md | Y | -| Severity | `MEDIUM` | - -**Recommended next move:** introduce a `docs/` directory. The README at 216 lines has likely grown to do the work of `docs/` — split it into a thin README + `docs/architecture.md`, `docs/usage.md`, etc. Heavy-wiki exemplars to copy from: `affinescript`, `boj-server`, `echidna`, `hypatia`. - -Additionally: **CHANGELOG.md is missing.** 65% of estate repos lack one — adopting a CHANGELOG (or auto-generating via `git-cliff`) is a recommended estate-wide follow-up. - -## Cross-references - -- Estate proof-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-proof-debt.md` -- Estate licence-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-licence-debt.md` -- Estate documentation-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-documentation-debt.md` - ---- - -🤖 Generated by Claude Code estate-wide tech-debt scan (2026-05-26). This file is informational — closing the debt is follow-up work owned by the maintainer. diff --git a/llm-warmup-dev.adoc b/llm-warmup-dev.adoc new file mode 100644 index 0000000..d88cffe --- /dev/null +++ b/llm-warmup-dev.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — polysafe-gitfixer (Developer) + +=== What is polysafe-gitfixer? + +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 e96972f..0000000 --- a/llm-warmup-dev.md +++ /dev/null @@ -1,20 +0,0 @@ - -# LLM Warmup — polysafe-gitfixer (Developer) - -## What is polysafe-gitfixer? -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..7643664 --- /dev/null +++ b/llm-warmup-user.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — polysafe-gitfixer (User) + +=== What is polysafe-gitfixer? + +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 fcb162c..0000000 --- a/llm-warmup-user.md +++ /dev/null @@ -1,20 +0,0 @@ - -# LLM Warmup — polysafe-gitfixer (User) - -## What is polysafe-gitfixer? -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