From 92f0a25b7db37ce237a7d2fda4a53619c1d058d1 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Mon, 24 Aug 2026 08:50:53 +0100 Subject: [PATCH] refactor: migrate repository documentation from Markdown to AsciiDoc --- ABI-FFI-README.md => ABI-FFI-README.adoc | 244 ++++++++++++----------- ARCHITECTURE.adoc | 48 +++++ ARCHITECTURE.md | 47 ----- CHANGELOG.adoc | 70 +++++++ CHANGELOG.md | 65 ------ CODE_OF_CONDUCT.adoc | 132 ++++++++++++ CODE_OF_CONDUCT.md | 132 ------------ CONTRIBUTING.adoc | 110 ++++++++++ CONTRIBUTING.md | 120 ----------- GOVERNANCE.adoc | 60 ++++++ GOVERNANCE.md | 60 ------ SECRETS.adoc | 221 ++++++++++++++++++++ SECRETS.md | 183 ----------------- SECURITY.adoc | 23 +++ SECURITY.md | 25 --- TEST-NEEDS.adoc | 36 ++++ TEST-NEEDS.md | 37 ---- 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 -- 24 files changed, 959 insertions(+), 901 deletions(-) rename ABI-FFI-README.md => ABI-FFI-README.adoc (74%) create mode 100644 ARCHITECTURE.adoc delete mode 100644 ARCHITECTURE.md create mode 100644 CHANGELOG.adoc delete mode 100644 CHANGELOG.md create mode 100644 CODE_OF_CONDUCT.adoc 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 create mode 100644 SECRETS.adoc delete mode 100644 SECRETS.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 (88%) 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/ABI-FFI-README.md b/ABI-FFI-README.adoc similarity index 74% rename from ABI-FFI-README.md rename to ABI-FFI-README.adoc index ada05ff..f1163e3 100644 --- a/ABI-FFI-README.md +++ b/ABI-FFI-README.adoc @@ -1,23 +1,22 @@ - -{{~ Aditionally delete this line and fill out the template below ~}} +\{\{~ Aditionally delete this line and fill out the template below ~}} -# {{PROJECT}} ABI/FFI Documentation +== \{\{PROJECT}} ABI/FFI Documentation -## Overview +=== Overview -This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: +This library follows the *Hyperpolymath RSR Standard* for ABI and FFI +design: -- **ABI (Application Binary Interface)** defined in **Idris2** with formal proofs -- **FFI (Foreign Function Interface)** implemented in **Zig** for C compatibility -- **Generated C headers** bridge Idris2 ABI to Zig FFI -- **Any language** can call through standard C ABI +* *ABI (Application Binary Interface)* defined in *Idris2* with formal +proofs +* *FFI (Foreign Function Interface)* implemented in *Zig* for C +compatibility +* *Generated C headers* bridge Idris2 ABI to Zig FFI +* *Any language* can call through standard C ABI -## Architecture +=== Architecture -``` +.... ┌─────────────────────────────────────────────┐ │ ABI Definitions (Idris2) │ │ src/abi/ │ @@ -49,11 +48,11 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: │ Any Language via C ABI │ │ - Rust, ReScript, Julia, Python, etc. │ └─────────────────────────────────────────────┘ -``` +.... -## Directory Structure +=== Directory Structure -``` +.... {{project}}/ ├── src/ │ ├── abi/ # ABI definitions (Idris2) @@ -81,15 +80,17 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: ├── rust/ ├── rescript/ └── julia/ -``` +.... -## Why Idris2 for ABI? +=== Why Idris2 for ABI? -### 1. **Formal Verification** +==== 1. *Formal Verification* -Idris2's dependent types allow proving properties about the ABI at compile-time: +Idris2’s dependent types allow proving properties about the ABI at +compile-time: -```idris +[source,idris] +---- -- Prove struct size is correct public export exampleStructSize : HasSize ExampleStruct 16 @@ -101,13 +102,14 @@ fieldAligned : Divides 8 (offsetOf ExampleStruct.field) -- Prove ABI is platform-compatible public export abiCompatible : Compatible (ABI 1) (ABI 2) -``` +---- -### 2. **Type Safety** +==== 2. *Type Safety* Encode invariants that C/Zig cannot express: -```idris +[source,idris] +---- -- Non-null pointer guaranteed at type level data Handle : Type where MkHandle : (ptr : Bits64) -> {auto 0 nonNull : So (ptr /= 0)} -> Handle @@ -115,13 +117,14 @@ data Handle : Type where -- Array with length proof data Buffer : (n : Nat) -> Type where MkBuffer : Vect n Byte -> Buffer n -``` +---- -### 3. **Platform Abstraction** +==== 3. *Platform Abstraction* Platform-specific types with compile-time selection: -```idris +[source,idris] +---- CInt : Platform -> Type CInt Linux = Bits32 CInt Windows = Bits32 @@ -129,13 +132,14 @@ CInt Windows = Bits32 CSize : Platform -> Type CSize Linux = Bits64 CSize Windows = Bits64 -``` +---- -### 4. **Safe Evolution** +==== 4. *Safe Evolution* Prove that new ABI versions are backward-compatible: -```idris +[source,idris] +---- -- Compiler enforces compatibility abiUpgrade : ABI 1 -> ABI 2 abiUpgrade old = MkABI2 { @@ -144,71 +148,78 @@ abiUpgrade old = MkABI2 { -- Can add new fields new_features = defaults } -``` +---- -## Why Zig for FFI? +=== Why Zig for FFI? -### 1. **C ABI Compatibility** +==== 1. *C ABI Compatibility* Zig exports C-compatible functions naturally: -```zig +[source,zig] +---- export fn library_function(param: i32) i32 { return param * 2; } -``` +---- -### 2. **Memory Safety** +==== 2. *Memory Safety* Compile-time safety without runtime overhead: -```zig +[source,zig] +---- // Null check enforced at compile time const handle = init() orelse return error.InitFailed; defer free(handle); -``` +---- -### 3. **Cross-Compilation** +==== 3. *Cross-Compilation* Built-in cross-compilation to any platform: -```bash +[source,bash] +---- zig build -Dtarget=x86_64-linux zig build -Dtarget=aarch64-macos zig build -Dtarget=x86_64-windows -``` +---- -### 4. **Zero Dependencies** +==== 4. *Zero Dependencies* No runtime, no libc required (unless explicitly needed): -```zig +[source,zig] +---- // Minimal binary size pub const lib = @import("std"); // Only includes what you use -``` +---- -## Building +=== Building -### Build FFI Library +==== Build FFI Library -```bash +[source,bash] +---- cd ffi/zig zig build # Build debug zig build -Doptimize=ReleaseFast # Build optimized zig build test # Run tests -``` +---- -### Generate C Header from Idris2 ABI +==== Generate C Header from Idris2 ABI -```bash +[source,bash] +---- cd src/abi idris2 --cg c-header Types.idr -o ../../generated/abi/{{project}}.h -``` +---- -### Cross-Compile +==== Cross-Compile -```bash +[source,bash] +---- cd ffi/zig # Linux x86_64 @@ -219,13 +230,14 @@ zig build -Dtarget=aarch64-macos # Windows x86_64 zig build -Dtarget=x86_64-windows -``` +---- -## Usage +=== Usage -### From C +==== From C -```c +[source,c] +---- #include "{{project}}.h" int main() { @@ -241,16 +253,19 @@ int main() { {{project}}_free(handle); return 0; } -``` +---- Compile with: -```bash + +[source,bash] +---- gcc -o example example.c -l{{project}} -L./zig-out/lib -``` +---- -### From Idris2 +==== From Idris2 -```idris +[source,idris] +---- import {{PROJECT}}.ABI.Foreign main : IO () @@ -263,11 +278,12 @@ main = do free handle putStrLn "Success" -``` +---- -### From Rust +==== From Rust -```rust +[source,rust] +---- #[link(name = "{{project}}")] extern "C" { fn {{project}}_init() -> *mut std::ffi::c_void; @@ -286,11 +302,12 @@ fn main() { {{project}}_free(handle); } } -``` +---- -### From Julia +==== From Julia -```julia +[source,julia] +---- const lib{{project}} = "lib{{project}}" function init() @@ -316,27 +333,30 @@ try finally cleanup(handle) end -``` +---- -## Testing +=== Testing -### Unit Tests (Zig) +==== Unit Tests (Zig) -```bash +[source,bash] +---- cd ffi/zig zig build test -``` +---- -### Integration Tests +==== Integration Tests -```bash +[source,bash] +---- cd ffi/zig zig build test-integration -``` +---- -### ABI Verification (Idris2) +==== ABI Verification (Idris2) -```idris +[source,idris] +---- -- Compile-time verification %runElab verifyABI @@ -346,44 +366,44 @@ main = do verifyLayoutsCorrect verifyAlignmentsCorrect putStrLn "ABI verification passed" -``` +---- -## Contributing +=== Contributing When modifying the ABI/FFI: -1. **Update ABI first** (`src/abi/*.idr`) - - Modify type definitions - - Update proofs - - Ensure backward compatibility - -2. **Generate C header** - ```bash - idris2 --cg c-header src/abi/Types.idr -o generated/abi/{{project}}.h - ``` - -3. **Update FFI implementation** (`ffi/zig/src/main.zig`) - - Implement new functions - - Match ABI types exactly - -4. **Add tests** - - Unit tests in Zig - - Integration tests - - ABI verification tests - -5. **Update documentation** - - Function signatures - - Usage examples - - Migration guide (if breaking changes) - -## License +[arabic] +. *Update ABI first* (`+src/abi/*.idr+`) +* Modify type definitions +* Update proofs +* Ensure backward compatibility +. *Generate C header* ++ +[source,bash] +---- +idris2 --cg c-header src/abi/Types.idr -o generated/abi/{{project}}.h +---- +. *Update FFI implementation* (`+ffi/zig/src/main.zig+`) +* Implement new functions +* Match ABI types exactly +. *Add tests* +* Unit tests in Zig +* Integration tests +* ABI verification tests +. *Update documentation* +* Function signatures +* Usage examples +* Migration guide (if breaking changes) + +=== License MPL-2.0 -## See Also +=== See Also -- [Idris2 Documentation](https://idris2.readthedocs.io) -- [Zig Documentation](https://ziglang.org/documentation/master/) -- [Rhodium Standard Repositories](https://github.com/hyperpolymath/rhodium-standard-repositories) -- [FFI Migration Guide](../ffi-migration-guide.md) -- [ABI Migration Guide](../abi-migration-guide.md) +* https://idris2.readthedocs.io[Idris2 Documentation] +* https://ziglang.org/documentation/master/[Zig Documentation] +* https://github.com/hyperpolymath/rhodium-standard-repositories[Rhodium +Standard Repositories] +* link:../ffi-migration-guide.md[FFI Migration Guide] +* link:../abi-migration-guide.md[ABI Migration Guide] 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..7059275 --- /dev/null +++ b/CHANGELOG.adoc @@ -0,0 +1,70 @@ +== Changelog + +All notable changes to `+universal-project-manager+` 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: 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 (#16) +* fix(ci): sync hypatia-scan.yml to canonical (#15) +* fix(ci): build Hypatia escript from repo root (estate dogfood drift) +* fix(ci): rsr-antipattern.yml duplicate heredoc (#13) +* fix(scorecard): enforce granular permissions and add fuzzing +placeholder +* fix(ci): Resolve workflow-linter self-matching and metadata issues +* fix: correct email jonathan.jewell → j.d.a.jewell +* fix(license): SPDX AGPL-3.0 → PMPL-1.0-or-later in dotfiles +* fix: remove duplicate SCM files from root +* fix: correct author name in CITATION.cff + +==== Changed + +* refactor: migrate 6SCM → 6A2 (.scm → .a2ml format) + +==== Documentation + +* docs: add TEST-NEEDS.md (CRG C) +* docs: add EXPLAINME.adoc — prove-it file backing README claims +* docs: add checkpoint files for state tracking + +==== CI + +* ci: redistribute concurrency-cancel guard to read-only check workflows +(#18) +* 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 b7f2363..0000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,65 +0,0 @@ - -# Changelog - -All notable changes to `universal-project-manager` 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: 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 (#16) -- fix(ci): sync hypatia-scan.yml to canonical (#15) -- fix(ci): build Hypatia escript from repo root (estate dogfood drift) -- fix(ci): rsr-antipattern.yml duplicate heredoc (#13) -- fix(scorecard): enforce granular permissions and add fuzzing placeholder -- fix(ci): Resolve workflow-linter self-matching and metadata issues -- fix: correct email jonathan.jewell → j.d.a.jewell -- fix(license): SPDX AGPL-3.0 → PMPL-1.0-or-later in dotfiles -- fix: remove duplicate SCM files from root -- fix: correct author name in CITATION.cff - -### Changed - -- refactor: migrate 6SCM → 6A2 (.scm → .a2ml format) - -### Documentation - -- docs: add TEST-NEEDS.md (CRG C) -- docs: add EXPLAINME.adoc — prove-it file backing README claims -- docs: add checkpoint files for state tracking - -### CI - -- ci: redistribute concurrency-cancel guard to read-only check workflows (#18) -- 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 new file mode 100644 index 0000000..f39d9ca --- /dev/null +++ b/CODE_OF_CONDUCT.adoc @@ -0,0 +1,132 @@ +== Contributor Covenant Code of Conduct + +=== Our Pledge + +We as members, contributors, and leaders pledge to make participation in +our community a harassment-free experience for everyone, regardless of +age, body size, visible or invisible disability, ethnicity, sex +characteristics, gender identity and expression, level of experience, +education, socio-economic status, nationality, personal appearance, +race, religion, or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, +welcoming, diverse, inclusive, and healthy community. + +=== Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our +mistakes, and learning from the experience +* Focusing on what is best not just for us as individuals, but for the +overall community + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or +advances of any kind +* Trolling, insulting or derogatory comments, and personal or political +attacks +* Public or private harassment +* Publishing others’ private information, such as a physical or email +address, without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a +professional setting + +=== Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our +standards of acceptable behavior and will take appropriate and fair +corrective action in response to any behavior that they deem +inappropriate, threatening, offensive, or harmful. + +Community leaders have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other +contributions that are not aligned to this Code of Conduct, and will +communicate reasons for moderation decisions when appropriate. + +=== Scope + +This Code of Conduct applies within all community spaces, and also +applies when an individual is officially representing the community in +public spaces. Examples of representing our community include using an +official e-mail address, posting via an official social media account, +or acting as an appointed representative at an online or offline event. + +=== Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may +be reported to the community leaders responsible for enforcement at . +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security +of the reporter of any incident. + +=== Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in +determining the consequences for any action they deem in violation of +this Code of Conduct: + +==== 1. Correction + +*Community Impact*: Use of inappropriate language or other behavior +deemed unprofessional or unwelcome in the community. + +*Consequence*: A private, written warning from community leaders, +providing clarity around the nature of the violation and an explanation +of why the behavior was inappropriate. A public apology may be +requested. + +==== 2. Warning + +*Community Impact*: A violation through a single incident or series of +actions. + +*Consequence*: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, for a specified period of +time. This includes avoiding interactions in community spaces as well as +external channels like social media. Violating these terms may lead to a +temporary or permanent ban. + +==== 3. Temporary Ban + +*Community Impact*: A serious violation of community standards, +including sustained inappropriate behavior. + +*Consequence*: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No +public or private interaction with the people involved, including +unsolicited interaction with those enforcing the Code of Conduct, is +allowed during this period. Violating these terms may lead to a +permanent ban. + +==== 4. Permanent Ban + +*Community Impact*: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of +individuals. + +*Consequence*: A permanent ban from any sort of public interaction +within the community. + +=== Attribution + +This Code of Conduct is adapted from the +https://www.contributor-covenant.org[Contributor Covenant], version 2.0, +available at +https://www.contributor-covenant.org/version/2/0/code_of_conduct.html. + +Community Impact Guidelines were inspired by +https://github.com/mozilla/diversity[Mozilla’s code of conduct +enforcement ladder]. + +For answers to common questions about this code of conduct, see the FAQ +at https://www.contributor-covenant.org/faq. Translations are available +at https://www.contributor-covenant.org/translations. diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md deleted file mode 100644 index e06b1e3..0000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,132 +0,0 @@ - -# Contributor Covenant Code of Conduct - -## Our Pledge - -We as members, contributors, and leaders pledge to make participation in our -community a harassment-free experience for everyone, regardless of age, body -size, visible or invisible disability, ethnicity, sex characteristics, gender -identity and expression, level of experience, education, socio-economic status, -nationality, personal appearance, race, religion, or sexual identity -and orientation. - -We pledge to act and interact in ways that contribute to an open, welcoming, -diverse, inclusive, and healthy community. - -## Our Standards - -Examples of behavior that contributes to a positive environment for our -community include: - -* Demonstrating empathy and kindness toward other people -* Being respectful of differing opinions, viewpoints, and experiences -* Giving and gracefully accepting constructive feedback -* Accepting responsibility and apologizing to those affected by our mistakes, - and learning from the experience -* Focusing on what is best not just for us as individuals, but for the - overall community - -Examples of unacceptable behavior include: - -* The use of sexualized language or imagery, and sexual attention or - advances of any kind -* Trolling, insulting or derogatory comments, and personal or political attacks -* Public or private harassment -* Publishing others' private information, such as a physical or email - address, without their explicit permission -* Other conduct which could reasonably be considered inappropriate in a - professional setting - -## Enforcement Responsibilities - -Community leaders are responsible for clarifying and enforcing our standards of -acceptable behavior and will take appropriate and fair corrective action in -response to any behavior that they deem inappropriate, threatening, offensive, -or harmful. - -Community leaders have the right and responsibility to remove, edit, or reject -comments, commits, code, wiki edits, issues, and other contributions that are -not aligned to this Code of Conduct, and will communicate reasons for moderation -decisions when appropriate. - -## Scope - -This Code of Conduct applies within all community spaces, and also applies when -an individual is officially representing the community in public spaces. -Examples of representing our community include using an official e-mail address, -posting via an official social media account, or acting as an appointed -representative at an online or offline event. - -## Enforcement - -Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported to the community leaders responsible for enforcement at -. -All complaints will be reviewed and investigated promptly and fairly. - -All community leaders are obligated to respect the privacy and security of the -reporter of any incident. - -## Enforcement Guidelines - -Community leaders will follow these Community Impact Guidelines in determining -the consequences for any action they deem in violation of this Code of Conduct: - -### 1. Correction - -**Community Impact**: Use of inappropriate language or other behavior deemed -unprofessional or unwelcome in the community. - -**Consequence**: A private, written warning from community leaders, providing -clarity around the nature of the violation and an explanation of why the -behavior was inappropriate. A public apology may be requested. - -### 2. Warning - -**Community Impact**: A violation through a single incident or series -of actions. - -**Consequence**: A warning with consequences for continued behavior. No -interaction with the people involved, including unsolicited interaction with -those enforcing the Code of Conduct, for a specified period of time. This -includes avoiding interactions in community spaces as well as external channels -like social media. Violating these terms may lead to a temporary or -permanent ban. - -### 3. Temporary Ban - -**Community Impact**: A serious violation of community standards, including -sustained inappropriate behavior. - -**Consequence**: A temporary ban from any sort of interaction or public -communication with the community for a specified period of time. No public or -private interaction with the people involved, including unsolicited interaction -with those enforcing the Code of Conduct, is allowed during this period. -Violating these terms may lead to a permanent ban. - -### 4. Permanent Ban - -**Community Impact**: Demonstrating a pattern of violation of community -standards, including sustained inappropriate behavior, harassment of an -individual, or aggression toward or disparagement of classes of individuals. - -**Consequence**: A permanent ban from any sort of public interaction within -the community. - -## Attribution - -This Code of Conduct is adapted from the [Contributor Covenant][homepage], -version 2.0, available at -https://www.contributor-covenant.org/version/2/0/code_of_conduct.html. - -Community Impact Guidelines were inspired by [Mozilla's code of conduct -enforcement ladder](https://github.com/mozilla/diversity). - -[homepage]: https://www.contributor-covenant.org - -For answers to common questions about this code of conduct, see the FAQ at -https://www.contributor-covenant.org/faq. Translations are available at -https://www.contributor-covenant.org/translations. diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc new file mode 100644 index 0000000..1e41a41 --- /dev/null +++ b/CONTRIBUTING.adoc @@ -0,0 +1,110 @@ +== Clone the repository + +git clone https://github.com/hyperpolymath/universal-project-manager.git +cd universal-project-manager + +== Using Nix (recommended for reproducibility) + +nix develop + +== Or using toolbox/distrobox + +toolbox create universal-project-manager-dev toolbox enter +universal-project-manager-dev # Install dependencies manually + +== Verify setup + +just check # or: cargo check / mix compile / etc. just test # Run test +suite + +.... + +### Repository Structure +.... + +universal-project-manager/ ├── 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/universal-project-manager/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://github.com/hyperpolymath/universal-project-manager/labels/help%20wanted) — Community help needed +- [`documentation`](https://github.com/hyperpolymath/universal-project-manager/labels/documentation) — Docs improvements +- [`perimeter-3`](https://github.com/hyperpolymath/universal-project-manager/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 efef6fe..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,120 +0,0 @@ - -# Clone the repository -git clone https://github.com/hyperpolymath/universal-project-manager.git -cd universal-project-manager - -# Using Nix (recommended for reproducibility) -nix develop - -# Or using toolbox/distrobox -toolbox create universal-project-manager-dev -toolbox enter universal-project-manager-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure -``` -universal-project-manager/ -├── 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/universal-project-manager/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://github.com/hyperpolymath/universal-project-manager/labels/help%20wanted) — Community help needed -- [`documentation`](https://github.com/hyperpolymath/universal-project-manager/labels/documentation) — Docs improvements -- [`perimeter-3`](https://github.com/hyperpolymath/universal-project-manager/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/SECRETS.adoc b/SECRETS.adoc new file mode 100644 index 0000000..99a477b --- /dev/null +++ b/SECRETS.adoc @@ -0,0 +1,221 @@ +== Secrets Configuration Guide + +This document lists all secrets required for the CI/CD pipelines to +function properly. + +=== GitHub Repository Secrets + +Configure these secrets in your GitHub repository: *Settings* > *Secrets +and variables* > *Actions* > *New repository secret* + +==== Required Secrets + +[width="100%",cols="28%,26%,28%,18%",options="header",] +|=== +|Secret Name |Description |Where to Get |Used By +|`+GITLAB_SSH_PRIVATE_KEY+` |SSH private key for GitLab push mirroring +|Generate with `+ssh-keygen -t ed25519 -C "github-mirror"+` +|`+.github/workflows/ci.yml+` (mirror job) + +|`+GITLAB_MIRROR_URL+` |GitLab repository URL for mirroring +|`+git@gitlab.com:overarch-underpin/managers/universal-project-manager.git+` +|`+.github/workflows/ci.yml+` (mirror job) +|=== + +==== Optional Secrets + +[width="100%",cols="28%,26%,28%,18%",options="header",] +|=== +|Secret Name |Description |Where to Get |Used By +|`+CODECOV_TOKEN+` |Token for uploading coverage reports +|https://codecov.io[codecov.io] - Get from repo settings +|`+.github/workflows/ci.yml+` (test job) + +|`+SNYK_TOKEN+` |Token for Snyk security scanning +|https://snyk.io[snyk.io] - Account settings |Security scanning +workflows + +|`+SONAR_TOKEN+` |Token for SonarCloud analysis +|https://sonarcloud.io[sonarcloud.io] - Security tab |Code quality +workflows +|=== + +==== Built-in Secrets (No Configuration Needed) + +[width="100%",cols="33%,32%,35%",options="header",] +|=== +|Secret Name |Description |Availability +|`+GITHUB_TOKEN+` |Automatic GitHub token |Automatically available in +all workflows +|=== + +''''' + +=== GitLab CI/CD Variables + +Configure these variables in your GitLab project: *Settings* > *CI/CD* > +*Variables* > *Add variable* + +==== Required Variables + +[width="100%",cols="26%,21%,22%,18%,13%",options="header",] +|=== +|Variable Name |Description |Where to Get |Protected |Masked +|`+CI_REGISTRY_USER+` |GitLab registry username |Your GitLab username +|No |No + +|`+CI_REGISTRY_PASSWORD+` |GitLab registry password or token |GitLab +Personal Access Token with `+read_registry+`, `+write_registry+` |Yes +|Yes +|=== + +==== Optional Variables + +[width="100%",cols="26%,21%,22%,18%,13%",options="header",] +|=== +|Variable Name |Description |Where to Get |Protected |Masked +|`+GITHUB_MIRROR_URL+` |GitHub repository URL (if reverse mirroring) +|`+git@github.com:hyperpolymath/Universal-Project-Manager.git+` |No |No + +|`+GITHUB_SSH_PRIVATE_KEY+` |SSH key for GitHub push |Generate with +`+ssh-keygen+` |Yes |Yes +|=== + +==== Predefined Variables (No Configuration Needed) + +GitLab provides many predefined CI/CD variables automatically. Key ones +include: + +* `+CI_COMMIT_REF_SLUG+` - Slug of the branch or tag +* `+CI_COMMIT_SHA+` - Full commit SHA +* `+CI_DEFAULT_BRANCH+` - Default branch name +* `+CI_PROJECT_PATH+` - Project path with namespace +* `+CI_REGISTRY+` - GitLab Container Registry URL +* `+CI_REGISTRY_IMAGE+` - Registry image path + +''''' + +=== Setup Instructions + +==== 1. Generate SSH Key for Mirroring + +[source,bash] +---- +# Generate a new ED25519 SSH key pair +ssh-keygen -t ed25519 -C "github-to-gitlab-mirror" -f gitlab_mirror_key -N "" + +# The private key (add to GitHub secrets as GITLAB_SSH_PRIVATE_KEY): +cat gitlab_mirror_key + +# The public key (add to GitLab as a deploy key with write access): +cat gitlab_mirror_key.pub +---- + +==== 2. Add Deploy Key to GitLab + +[arabic] +. Go to your GitLab project: *Settings* > *Repository* > *Deploy keys* +. Click *Add deploy key* +. Title: `+GitHub Mirror+` +. Key: Paste the public key from `+gitlab_mirror_key.pub+` +. *Enable* "`Grant write permissions to this key`" +. Click *Add key* + +==== 3. Add SSH Key to GitHub + +[arabic] +. Go to your GitHub repository: *Settings* > *Secrets and variables* > +*Actions* +. Click *New repository secret* +. Name: `+GITLAB_SSH_PRIVATE_KEY+` +. Secret: Paste the entire contents of `+gitlab_mirror_key+` (including +BEGIN/END lines) +. Click *Add secret* + +==== 4. Add Mirror URL to GitHub + +[arabic] +. In the same GitHub Secrets page, click *New repository secret* +. Name: `+GITLAB_MIRROR_URL+` +. Secret: +`+git@gitlab.com:overarch-underpin/managers/universal-project-manager.git+` +. Click *Add secret* + +==== 5. Configure Codecov (Optional) + +[arabic] +. Go to https://codecov.io[codecov.io] and sign in with GitHub +. Add your repository +. Copy the upload token from the repository settings +. Add to GitHub Secrets as `+CODECOV_TOKEN+` + +''''' + +=== Security Best Practices + +==== Do’s + +* Use *protected* variables for production secrets +* Use *masked* variables for sensitive values +* Rotate keys periodically (recommended: every 90 days) +* Use environment-specific secrets when possible +* Audit secret access regularly + +==== Don’ts + +* Never commit secrets to the repository +* Never log secret values in CI output +* Never share secrets between unrelated projects +* Never use personal access tokens for CI (use deploy keys/tokens) +* Never disable masking for sensitive values + +''''' + +=== Verification + +==== Test GitHub Mirror Setup + +[source,bash] +---- +# From your local machine, verify the connection works +ssh -T git@gitlab.com -i ~/.ssh/gitlab_mirror_key +---- + +Expected output: `+Welcome to GitLab, @username!+` + +==== Test CI Pipeline + +[arabic] +. Push a small change to trigger the CI +. Check the Actions tab for workflow runs +. Verify the mirror job succeeds +. Check GitLab to confirm the push arrived + +''''' + +=== Troubleshooting + +==== Mirror Push Fails with "`Permission denied`" + +* Verify the deploy key has *write permissions* on GitLab +* Check the SSH key format (should include BEGIN/END lines) +* Ensure the key isn’t password-protected + +==== Codecov Upload Fails + +* Verify the token is correct +* Check if the repository is properly activated on codecov.io +* Ensure coverage files are being generated + +==== GitLab Container Registry Auth Fails + +* Use a Personal Access Token, not your password +* Token needs `+read_registry+` and `+write_registry+` scopes +* Variable should be *masked* and *protected* + +''''' + +=== Contact + +For issues with secret configuration: - GitHub: Open an issue in this +repository - GitLab: Contact the project maintainers diff --git a/SECRETS.md b/SECRETS.md deleted file mode 100644 index e495db9..0000000 --- a/SECRETS.md +++ /dev/null @@ -1,183 +0,0 @@ - -# Secrets Configuration Guide - -This document lists all secrets required for the CI/CD pipelines to function properly. - -## GitHub Repository Secrets - -Configure these secrets in your GitHub repository: -**Settings** > **Secrets and variables** > **Actions** > **New repository secret** - -### Required Secrets - -| Secret Name | Description | Where to Get | Used By | -|-------------|-------------|--------------|---------| -| `GITLAB_SSH_PRIVATE_KEY` | SSH private key for GitLab push mirroring | Generate with `ssh-keygen -t ed25519 -C "github-mirror"` | `.github/workflows/ci.yml` (mirror job) | -| `GITLAB_MIRROR_URL` | GitLab repository URL for mirroring | `git@gitlab.com:overarch-underpin/managers/universal-project-manager.git` | `.github/workflows/ci.yml` (mirror job) | - -### Optional Secrets - -| Secret Name | Description | Where to Get | Used By | -|-------------|-------------|--------------|---------| -| `CODECOV_TOKEN` | Token for uploading coverage reports | [codecov.io](https://codecov.io) - Get from repo settings | `.github/workflows/ci.yml` (test job) | -| `SNYK_TOKEN` | Token for Snyk security scanning | [snyk.io](https://snyk.io) - Account settings | Security scanning workflows | -| `SONAR_TOKEN` | Token for SonarCloud analysis | [sonarcloud.io](https://sonarcloud.io) - Security tab | Code quality workflows | - -### Built-in Secrets (No Configuration Needed) - -| Secret Name | Description | Availability | -|-------------|-------------|--------------| -| `GITHUB_TOKEN` | Automatic GitHub token | Automatically available in all workflows | - ---- - -## GitLab CI/CD Variables - -Configure these variables in your GitLab project: -**Settings** > **CI/CD** > **Variables** > **Add variable** - -### Required Variables - -| Variable Name | Description | Where to Get | Protected | Masked | -|---------------|-------------|--------------|-----------|--------| -| `CI_REGISTRY_USER` | GitLab registry username | Your GitLab username | No | No | -| `CI_REGISTRY_PASSWORD` | GitLab registry password or token | GitLab Personal Access Token with `read_registry`, `write_registry` | Yes | Yes | - -### Optional Variables - -| Variable Name | Description | Where to Get | Protected | Masked | -|---------------|-------------|--------------|-----------|--------| -| `GITHUB_MIRROR_URL` | GitHub repository URL (if reverse mirroring) | `git@github.com:hyperpolymath/Universal-Project-Manager.git` | No | No | -| `GITHUB_SSH_PRIVATE_KEY` | SSH key for GitHub push | Generate with `ssh-keygen` | Yes | Yes | - -### Predefined Variables (No Configuration Needed) - -GitLab provides many predefined CI/CD variables automatically. Key ones include: - -- `CI_COMMIT_REF_SLUG` - Slug of the branch or tag -- `CI_COMMIT_SHA` - Full commit SHA -- `CI_DEFAULT_BRANCH` - Default branch name -- `CI_PROJECT_PATH` - Project path with namespace -- `CI_REGISTRY` - GitLab Container Registry URL -- `CI_REGISTRY_IMAGE` - Registry image path - ---- - -## Setup Instructions - -### 1. Generate SSH Key for Mirroring - -```bash -# Generate a new ED25519 SSH key pair -ssh-keygen -t ed25519 -C "github-to-gitlab-mirror" -f gitlab_mirror_key -N "" - -# The private key (add to GitHub secrets as GITLAB_SSH_PRIVATE_KEY): -cat gitlab_mirror_key - -# The public key (add to GitLab as a deploy key with write access): -cat gitlab_mirror_key.pub -``` - -### 2. Add Deploy Key to GitLab - -1. Go to your GitLab project: **Settings** > **Repository** > **Deploy keys** -2. Click **Add deploy key** -3. Title: `GitHub Mirror` -4. Key: Paste the public key from `gitlab_mirror_key.pub` -5. **Enable** "Grant write permissions to this key" -6. Click **Add key** - -### 3. Add SSH Key to GitHub - -1. Go to your GitHub repository: **Settings** > **Secrets and variables** > **Actions** -2. Click **New repository secret** -3. Name: `GITLAB_SSH_PRIVATE_KEY` -4. Secret: Paste the entire contents of `gitlab_mirror_key` (including BEGIN/END lines) -5. Click **Add secret** - -### 4. Add Mirror URL to GitHub - -1. In the same GitHub Secrets page, click **New repository secret** -2. Name: `GITLAB_MIRROR_URL` -3. Secret: `git@gitlab.com:overarch-underpin/managers/universal-project-manager.git` -4. Click **Add secret** - -### 5. Configure Codecov (Optional) - -1. Go to [codecov.io](https://codecov.io) and sign in with GitHub -2. Add your repository -3. Copy the upload token from the repository settings -4. Add to GitHub Secrets as `CODECOV_TOKEN` - ---- - -## Security Best Practices - -### Do's - -- Use **protected** variables for production secrets -- Use **masked** variables for sensitive values -- Rotate keys periodically (recommended: every 90 days) -- Use environment-specific secrets when possible -- Audit secret access regularly - -### Don'ts - -- Never commit secrets to the repository -- Never log secret values in CI output -- Never share secrets between unrelated projects -- Never use personal access tokens for CI (use deploy keys/tokens) -- Never disable masking for sensitive values - ---- - -## Verification - -### Test GitHub Mirror Setup - -```bash -# From your local machine, verify the connection works -ssh -T git@gitlab.com -i ~/.ssh/gitlab_mirror_key -``` - -Expected output: `Welcome to GitLab, @username!` - -### Test CI Pipeline - -1. Push a small change to trigger the CI -2. Check the Actions tab for workflow runs -3. Verify the mirror job succeeds -4. Check GitLab to confirm the push arrived - ---- - -## Troubleshooting - -### Mirror Push Fails with "Permission denied" - -- Verify the deploy key has **write permissions** on GitLab -- Check the SSH key format (should include BEGIN/END lines) -- Ensure the key isn't password-protected - -### Codecov Upload Fails - -- Verify the token is correct -- Check if the repository is properly activated on codecov.io -- Ensure coverage files are being generated - -### GitLab Container Registry Auth Fails - -- Use a Personal Access Token, not your password -- Token needs `read_registry` and `write_registry` scopes -- Variable should be **masked** and **protected** - ---- - -## Contact - -For issues with secret configuration: -- GitHub: Open an issue in this repository -- GitLab: Contact the project maintainers 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..1027788 --- /dev/null +++ b/TEST-NEEDS.adoc @@ -0,0 +1,36 @@ +== TEST-NEEDS.md — universal-project-manager + +=== CRG Grade: C — ACHIEVED 2026-04-04 + +=== Current Test State + +[cols=",,",options="header",] +|=== +|Category |Count |Notes +|BATS shell tests |1 |`+tests/test_detect.bats+` +|Test runner scripts |2 |`+tests/run_tests.sh+` + CI test script +|Zig FFI tests |1 |`+ffi/zig/test/integration_test.zig+` +|Test infrastructure |Present |`+tests/+` directory +|=== + +=== What’s Covered + +* [x] BATS framework for shell script testing +* [x] Project detection tests +* [x] Zig FFI integration tests +* [x] CI integration via test scripts + +=== Still Missing (for CRG B+) + +* [ ] Multi-project manager compatibility tests +* [ ] Plugin integration tests +* [ ] Configuration edge case tests +* [ ] Performance benchmarks +* [ ] Cross-platform detection tests + +=== Run Tests + +[source,bash] +---- +cd /var/mnt/eclipse/repos/universal-project-manager && bash tests/run_tests.sh +---- diff --git a/TEST-NEEDS.md b/TEST-NEEDS.md deleted file mode 100644 index 119669b..0000000 --- a/TEST-NEEDS.md +++ /dev/null @@ -1,37 +0,0 @@ - -# TEST-NEEDS.md — universal-project-manager - -## CRG Grade: C — ACHIEVED 2026-04-04 - -## Current Test State - -| Category | Count | Notes | -|----------|-------|-------| -| BATS shell tests | 1 | `tests/test_detect.bats` | -| Test runner scripts | 2 | `tests/run_tests.sh` + CI test script | -| Zig FFI tests | 1 | `ffi/zig/test/integration_test.zig` | -| Test infrastructure | Present | `tests/` directory | - -## What's Covered - -- [x] BATS framework for shell script testing -- [x] Project detection tests -- [x] Zig FFI integration tests -- [x] CI integration via test scripts - -## Still Missing (for CRG B+) - -- [ ] Multi-project manager compatibility tests -- [ ] Plugin integration tests -- [ ] Configuration edge case tests -- [ ] Performance benchmarks -- [ ] Cross-platform detection tests - -## Run Tests - -```bash -cd /var/mnt/eclipse/repos/universal-project-manager && bash tests/run_tests.sh -``` diff --git a/TOPOLOGY.md b/TOPOLOGY.adoc similarity index 88% rename from TOPOLOGY.md rename to TOPOLOGY.adoc index 2d926c3..78aaf82 100644 --- a/TOPOLOGY.md +++ b/TOPOLOGY.adoc @@ -1,15 +1,8 @@ - - - +== Universal Project Manager (UPM) — Project Topology -# Universal Project Manager (UPM) — Project Topology +=== System Architecture -## System Architecture - -``` +.... ┌─────────────────────────────────────────┐ │ OPERATOR / CI │ │ (Justfile / Shell CLI) │ @@ -49,11 +42,11 @@ Copyright (c) Jonathan D.A. Jewell │ Justfile Automation .machine_readable/ │ │ GitHub/GitLab CI 0-AI-MANIFEST.a2ml │ └─────────────────────────────────────────┘ -``` +.... -## Completion Dashboard +=== Completion Dashboard -``` +.... COMPONENT STATUS NOTES ───────────────────────────────── ────────────────── ───────────────────────────────── CORE CI SCRIPTS @@ -75,25 +68,26 @@ REPO INFRASTRUCTURE ───────────────────────────────────────────────────────────────────────────── OVERALL: ██████████ 100% Phase 1 Foundation Complete -``` +.... -## Key Dependencies +=== Key Dependencies -``` +.... detect.sh ──────► setup.sh ──────► test.sh / lint.sh ──────► build.sh │ │ │ │ ▼ ▼ ▼ ▼ Langs/PMs ──────► Toolchain ───────► Coverage ───────────► Artifact -``` +.... -## 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..322d34a --- /dev/null +++ b/docs/tech-debt-2026-05-26.adoc @@ -0,0 +1,71 @@ +== Tech-Debt Audit — universal-project-manager — 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 |501 +|`+docs/+` files |1 +|`+docs/+` LoC |36 +|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 +501 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 a69177d..0000000 --- a/docs/tech-debt-2026-05-26.md +++ /dev/null @@ -1,56 +0,0 @@ - -# Tech-Debt Audit — universal-project-manager — 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 | 501 | -| `docs/` files | 1 | -| `docs/` LoC | 36 | -| 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 501 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..d9e637f --- /dev/null +++ b/llm-warmup-dev.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — universal-project-manager (Developer) + +=== What is universal-project-manager? + +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 0223163..0000000 --- a/llm-warmup-dev.md +++ /dev/null @@ -1,20 +0,0 @@ - -# LLM Warmup — universal-project-manager (Developer) - -## What is universal-project-manager? -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..d07a35d --- /dev/null +++ b/llm-warmup-user.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — universal-project-manager (User) + +=== What is universal-project-manager? + +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 b9d60d4..0000000 --- a/llm-warmup-user.md +++ /dev/null @@ -1,20 +0,0 @@ - -# LLM Warmup — universal-project-manager (User) - -## What is universal-project-manager? -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