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