From 0fbdaba70be38c4812ed3e358e80e6e38b850095 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Sun, 23 Aug 2026 20:03:08 +0100 Subject: [PATCH 1/2] chore: global textual eradication of Nix and ReScript --- .claude/CLAUDE.md | 4 ++-- .github/workflows/governance.yml | 2 +- ABI-FFI-README.md | 4 ++-- CONTRIBUTING.md | 6 +++--- RSR_OUTLINE.adoc | 8 ++++---- docs/STATE-ASSESSMENT-2026-04-16.adoc | 8 ++++---- examples/web-project-deno.json | 16 ++++++++-------- 7 files changed, 24 insertions(+), 24 deletions(-) diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index eee67d7..bb8457e 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -30,7 +30,7 @@ | Bun | Deno | | pnpm/yarn | Deno | | Go | Rust | -| Python | Julia/Rust/ReScript | +| Python | Julia/Rust/AffineScript | | Java/Kotlin | Rust/Tauri/Dioxus | | Swift | Tauri/Dioxus | | React Native | Tauri/Dioxus | @@ -57,7 +57,7 @@ Both are FOSS with independent governance (no Big Tech). ### Package Management - **Primary**: Guix (guix.scm) -- **Fallback**: Nix (flake.nix) +- **Fallback**: Guix (flake.guix) - **JS deps**: Deno (deno.json imports) ### Security Requirements diff --git a/.github/workflows/governance.yml b/.github/workflows/governance.yml index 116e0ee..2f986b5 100644 --- a/.github/workflows/governance.yml +++ b/.github/workflows/governance.yml @@ -3,7 +3,7 @@ # in hyperpolymath/standards instead of carrying per-repo copies. # # Replaces the per-repo governance scaffolding removed in the same commit: -# quality.yml, guix-nix-policy.yml, npm-bun-blocker.yml, ts-blocker.yml, +# quality.yml, guix-guix-policy.yml, npm-bun-blocker.yml, ts-blocker.yml, # security-policy.yml, rsr-antipattern.yml, wellknown-enforcement.yml, # workflow-linter.yml # diff --git a/ABI-FFI-README.md b/ABI-FFI-README.md index 0790754..386e7f0 100644 --- a/ABI-FFI-README.md +++ b/ABI-FFI-README.md @@ -43,7 +43,7 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: ▼ ┌─────────────────────────────────────────────┐ │ Any Language via C ABI │ -│ - Rust, ReScript, Julia, Python, etc. │ +│ - Rust, AffineScript, Julia, Python, etc. │ └─────────────────────────────────────────────┘ ``` @@ -75,7 +75,7 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: │ └── bindings/ # Language-specific wrappers (optional) ├── rust/ - ├── rescript/ + ├── affinescript/ └── julia/ ``` diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f85f359..127ceb6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,8 +2,8 @@ git clone https://github.com/hyperpolymath/branch-newspaper.git cd branch-newspaper -# Using Nix (recommended for reproducibility) -nix develop +# Using Guix (recommended for reproducibility) +guix develop # Or using toolbox/distrobox toolbox create branch-newspaper-dev @@ -41,7 +41,7 @@ branch-newspaper/ ├── MAINTAINERS.md ├── README.adoc ├── SECURITY.md -├── flake.nix # Nix flake (Perimeter 1) +├── flake.guix # Guix flake (Perimeter 1) └── Justfile # Task runner (Perimeter 1) ``` diff --git a/RSR_OUTLINE.adoc b/RSR_OUTLINE.adoc index d3fdc87..8f6db23 100644 --- a/RSR_OUTLINE.adoc +++ b/RSR_OUTLINE.adoc @@ -146,8 +146,8 @@ project/ === Language Tiers -* **Tier 1** (Gold): Rust, Elixir, Zig, Ada, Haskell, ReScript -* **Tier 2** (Silver): Nickel, Racket, Guile Scheme, Nix +* **Tier 1** (Gold): Rust, Elixir, Zig, Ada, Haskell, AffineScript +* **Tier 2** (Silver): Nickel, Racket, Guile Scheme, Guix * **Infrastructure**: Guix channels, derivations === Required Files @@ -161,12 +161,12 @@ project/ * `.well-known/security.txt` * `.well-known/ai.txt` * `.well-known/humans.txt` -* `guix.scm` OR `flake.nix` +* `guix.scm` OR `flake.guix` === Prohibited * Python outside `salt/` directory -* TypeScript/JavaScript (use ReScript) +* TypeScript/JavaScript (use AffineScript) * CUE (use Guile/Nickel) * `Dockerfile` (use `Containerfile`) diff --git a/docs/STATE-ASSESSMENT-2026-04-16.adoc b/docs/STATE-ASSESSMENT-2026-04-16.adoc index 76de2f5..e006afe 100644 --- a/docs/STATE-ASSESSMENT-2026-04-16.adoc +++ b/docs/STATE-ASSESSMENT-2026-04-16.adoc @@ -59,7 +59,7 @@ infrastructure/governance scaffold with no runnable product. ** `ci.yml`, `codeql.yml`, `quality.yml` ** `mirror-sync.yml`, `mirror.yml`, `instant-sync.yml` ** `casket-pages.yml`, `boj-build.yml` - ** `guix-nix-policy.yml`, `security-policy.yml` + ** `guix-guix-policy.yml`, `security-policy.yml` * `.gitlab-ci.yml` for GitLab mirror * Justfile with onboarding recipes (`doctor`, `heal`, `tour`) ** Core recipes (`build`, `test`, `clean`, `fmt`, `lint`) are all stubs: `echo "TODO: Add X command"` @@ -116,7 +116,7 @@ These enforce policies on a codebase that doesn't exist. === Template/Placeholder Code * `ffi/zig/src/main.zig` — unsubstituted RSR template (`{{project}}` placeholders) -* `examples/SafeDOMExample.res` — standalone ReScript example, unconnected +* `examples/SafeDOMExample.res` — standalone AffineScript example, unconnected * `tests/fuzz/placeholder.txt` — empty === Documentation (describes absent system) @@ -150,7 +150,7 @@ These enforce policies on a codebase that doesn't exist. == Unresolved Architectural Tension -The `CLAUDE.md` language policy bans Node.js/npm and mandates Deno + ReScript. +The `CLAUDE.md` language policy bans Node.js/npm and mandates Deno + AffineScript. The `README.adoc` describes an Elixir/Phoenix application which typically depends on Node.js (esbuild) for asset compilation. @@ -159,7 +159,7 @@ needs resolution before development begins: 1. **Option A**: Use Phoenix with Deno-based asset pipeline (non-standard, requires custom setup) 2. **Option B**: Use Phoenix with its standard esbuild pipeline (conflicts with CLAUDE.md) -3. **Option C**: Rebuild the concept in a fully CLAUDE.md-compliant stack (ReScript + Deno + Gleam) +3. **Option C**: Rebuild the concept in a fully CLAUDE.md-compliant stack (AffineScript + Deno + Gleam) == Git History Analysis diff --git a/examples/web-project-deno.json b/examples/web-project-deno.json index 5ddd3bd..ee775a4 100644 --- a/examples/web-project-deno.json +++ b/examples/web-project-deno.json @@ -1,17 +1,17 @@ { - "// NOTE": "Example deno.json for ReScript web projects", + "// NOTE": "Example deno.json for AffineScript web projects", "tasks": { - "build": "deno run -A npm:rescript", - "clean": "deno run -A npm:rescript clean", - "watch": "deno run -A npm:rescript -w", + "build": "deno run -A npm:affinescript", + "clean": "deno run -A npm:affinescript clean", + "watch": "deno run -A npm:affinescript -w", "serve": "deno run -A jsr:@std/http/file-server .", "test": "deno test --allow-all" }, "imports": { - "rescript": "^12.0.0", - "@rescript/core": "npm:@rescript/core@^1.6.0", - "safe-dom/": "https://raw.githubusercontent.com/hyperpolymath/rescript-dom-mounter/main/src/", - "proven/": "../proven/bindings/rescript/src/" + "affinescript": "^12.0.0", + "@affinescript/core": "npm:@affinescript/core@^1.6.0", + "safe-dom/": "https://raw.githubusercontent.com/hyperpolymath/affinescript-dom-mounter/main/src/", + "proven/": "../proven/bindings/affinescript/src/" }, "compilerOptions": { "allowJs": true, From 991359704483d264f5493e6e7de37334137eac8e Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Mon, 24 Aug 2026 07:59:48 +0100 Subject: [PATCH 2/2] refactor: migrate repository documentation from Markdown to AsciiDoc --- ABI-FFI-README.md => ABI-FFI-README.adoc | 240 +++++++++++++---------- CHANGELOG.adoc | 76 +++++++ CHANGELOG.md | 68 ------- CODE_OF_CONDUCT.adoc | 132 +++++++++++++ CODE_OF_CONDUCT.md | 128 ------------ CONTRIBUTING.adoc | 109 ++++++++++ CONTRIBUTING.md | 116 ----------- GOVERNANCE.adoc | 60 ++++++ GOVERNANCE.md | 60 ------ PROOF-NEEDS.adoc | 13 ++ PROOF-NEEDS.md | 10 - README.adoc | 183 +++++++++++++++++ README.md | 207 ------------------- REQUIRES_INITIALISATION.adoc | 112 +++++++++++ REQUIRES_INITIALISATION.md | 110 ----------- SECRETS.adoc | 198 +++++++++++++++++++ SECRETS.md | 161 --------------- SECURITY.md => SECURITY.adoc | 24 +-- TEST-NEEDS.adoc | 32 +++ TEST-NEEDS.md | 29 --- TOPOLOGY.md => TOPOLOGY.adoc | 39 ++-- docs/tech-debt-2026-05-26.adoc | 71 +++++++ docs/tech-debt-2026-05-26.md | 57 ------ llm-warmup-dev.adoc | 19 ++ llm-warmup-dev.md | 16 -- llm-warmup-user.adoc | 19 ++ llm-warmup-user.md | 16 -- 27 files changed, 1187 insertions(+), 1118 deletions(-) rename ABI-FFI-README.md => ABI-FFI-README.adoc (74%) 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 PROOF-NEEDS.adoc delete mode 100644 PROOF-NEEDS.md create mode 100644 README.adoc delete mode 100644 README.md create mode 100644 REQUIRES_INITIALISATION.adoc delete mode 100644 REQUIRES_INITIALISATION.md create mode 100644 SECRETS.adoc delete mode 100644 SECRETS.md rename SECURITY.md => SECURITY.adoc (52%) 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 386e7f0..de11427 100644 --- a/ABI-FFI-README.md +++ b/ABI-FFI-README.adoc @@ -1,19 +1,22 @@ -{{~ Aditionally delete this line and fill out the template below ~}} +\{\{~ Aditionally delete this line and fill out the template below ~}} -# BRANCH_NEWSPAPER ABI/FFI Documentation +== BRANCH_NEWSPAPER 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/ │ @@ -45,11 +48,11 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: │ Any Language via C ABI │ │ - Rust, AffineScript, Julia, Python, etc. │ └─────────────────────────────────────────────┘ -``` +.... -## Directory Structure +=== Directory Structure -``` +.... {{project}}/ ├── src/ │ ├── abi/ # ABI definitions (Idris2) @@ -77,15 +80,17 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: ├── rust/ ├── affinescript/ └── 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 @@ -97,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 @@ -111,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 @@ -125,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 { @@ -140,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 @@ -215,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() { @@ -237,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 BRANCH_NEWSPAPER.ABI.Foreign main : IO () @@ -259,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; @@ -282,11 +302,12 @@ fn main() { {{project}}_free(handle); } } -``` +---- -### From Julia +==== From Julia -```julia +[source,julia] +---- const lib{{project}} = "lib{{project}}" function init() @@ -312,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 @@ -342,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/CHANGELOG.adoc b/CHANGELOG.adoc new file mode 100644 index 0000000..e0c5fb8 --- /dev/null +++ b/CHANGELOG.adoc @@ -0,0 +1,76 @@ +== Changelog + +All notable changes to `+branch-newspaper+` 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 (#47) +* fix(ci): sync hypatia-scan.yml to canonical (#46) +* fix(ci): adopt canonical hypatia-scan.yml (#45) +* fix(ci): Phase-2 fleet submission must not fail the security gate +(#44) +* fix(ci): hypatia-scan workdir ($\{\{ env.HOME }} resolves empty) (#43) +* fix(ci): hypatia-scan.yml – –exit-zero + GITHUB_TOKEN +(hyperpolymath/hypatia#213) (#39) +* fix(ci): rsr-antipattern duplicate heredoc + setup-beam ubuntu24 (#40) +* fix(ci): move secret-scanner Cargo.toml gate from job-level if: to +step-level (#41) +* fix(scorecard): enforce granular permissions and add fuzzing +placeholder +* fix(ci): Resolve workflow-linter self-matching and metadata issues + +==== Changed + +* refactor: migrate 6SCM → 6A2 (.scm → .a2ml format) + +==== Documentation + +* docs: add honest state assessment (2026-04-16) +* docs: add TEST-NEEDS.md (CRG C) +* 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 +(#49) +* ci: SHA-pin hyperpolymath validate-actions in dogfood-gate +* ci(antipattern): fix top-level dir + benchmark/lsp filename matching +(#38) +* ci(antipattern): TS check reads .claude/CLAUDE.md exemption table +(#37) +* ci(antipattern): broaden TS allowlist (cli, mod.ts, lsp-server, +_vscode_, deno-*) (#36) + +=== 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 2b71df4..0000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,68 +0,0 @@ - - -# Changelog - -All notable changes to `branch-newspaper` 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 (#47) -- fix(ci): sync hypatia-scan.yml to canonical (#46) -- fix(ci): adopt canonical hypatia-scan.yml (#45) -- fix(ci): Phase-2 fleet submission must not fail the security gate (#44) -- fix(ci): hypatia-scan workdir (${{ env.HOME }} resolves empty) (#43) -- fix(ci): hypatia-scan.yml -- --exit-zero + GITHUB_TOKEN (hyperpolymath/hypatia#213) (#39) -- fix(ci): rsr-antipattern duplicate heredoc + setup-beam ubuntu24 (#40) -- fix(ci): move secret-scanner Cargo.toml gate from job-level if: to step-level (#41) -- fix(scorecard): enforce granular permissions and add fuzzing placeholder -- fix(ci): Resolve workflow-linter self-matching and metadata issues - -### Changed - -- refactor: migrate 6SCM → 6A2 (.scm → .a2ml format) - -### Documentation - -- docs: add honest state assessment (2026-04-16) -- docs: add TEST-NEEDS.md (CRG C) -- 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 (#49) -- ci: SHA-pin hyperpolymath validate-actions in dogfood-gate -- ci(antipattern): fix top-level dir + benchmark/lsp filename matching (#38) -- ci(antipattern): TS check reads .claude/CLAUDE.md exemption table (#37) -- ci(antipattern): broaden TS allowlist (cli, mod.ts, lsp-server, *vscode*, deno-*) (#36) - -## 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 18c9147..0000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,128 +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..d59e572 --- /dev/null +++ b/CONTRIBUTING.adoc @@ -0,0 +1,109 @@ +== Clone the repository + +git clone https://github.com/hyperpolymath/branch-newspaper.git cd +branch-newspaper + +== Using Guix (recommended for reproducibility) + +guix develop + +== Or using toolbox/distrobox + +toolbox create branch-newspaper-dev toolbox enter branch-newspaper-dev # +Install dependencies manually + +== Verify setup + +just check # or: cargo check / mix compile / etc. just test # Run test +suite + +.... + +### Repository Structure +.... + +branch-newspaper/ ├── 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.guix # Guix +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/branch-newspaper/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://github.com/hyperpolymath/branch-newspaper/labels/help%20wanted) — Community help needed +- [`documentation`](https://github.com/hyperpolymath/branch-newspaper/labels/documentation) — Docs improvements +- [`perimeter-3`](https://github.com/hyperpolymath/branch-newspaper/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 127ceb6..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,116 +0,0 @@ -# Clone the repository -git clone https://github.com/hyperpolymath/branch-newspaper.git -cd branch-newspaper - -# Using Guix (recommended for reproducibility) -guix develop - -# Or using toolbox/distrobox -toolbox create branch-newspaper-dev -toolbox enter branch-newspaper-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure -``` -branch-newspaper/ -├── 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.guix # Guix 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/branch-newspaper/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://github.com/hyperpolymath/branch-newspaper/labels/help%20wanted) — Community help needed -- [`documentation`](https://github.com/hyperpolymath/branch-newspaper/labels/documentation) — Docs improvements -- [`perimeter-3`](https://github.com/hyperpolymath/branch-newspaper/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/PROOF-NEEDS.adoc b/PROOF-NEEDS.adoc new file mode 100644 index 0000000..f3b5bf7 --- /dev/null +++ b/PROOF-NEEDS.adoc @@ -0,0 +1,13 @@ +== PROOF-NEEDS.md + +=== Template ABI Cleanup (2026-03-29) + +Template ABI removed – was creating false impression of formal +verification. The removed files (Types.idr, Layout.idr, Foreign.idr) +contained only RSR template scaffolding with unresolved +BRANCH_NEWSPAPER/Jonathan D.A. Jewell placeholders and no +domain-specific proofs. + +When this project needs formal ABI verification, create domain-specific +Idris2 proofs following the pattern in repos like `+typed-wasm+`, +`+proven+`, `+echidna+`, or `+boj-server+`. diff --git a/PROOF-NEEDS.md b/PROOF-NEEDS.md deleted file mode 100644 index 1e8c215..0000000 --- a/PROOF-NEEDS.md +++ /dev/null @@ -1,10 +0,0 @@ -# PROOF-NEEDS.md - -## Template ABI Cleanup (2026-03-29) - -Template ABI removed -- was creating false impression of formal verification. -The removed files (Types.idr, Layout.idr, Foreign.idr) contained only RSR template -scaffolding with unresolved BRANCH_NEWSPAPER/Jonathan D.A. Jewell placeholders and no domain-specific proofs. - -When this project needs formal ABI verification, create domain-specific Idris2 proofs -following the pattern in repos like `typed-wasm`, `proven`, `echidna`, or `boj-server`. diff --git a/README.adoc b/README.adoc new file mode 100644 index 0000000..983e79c --- /dev/null +++ b/README.adoc @@ -0,0 +1,183 @@ +https://github.com/hyperpolymath/palimpsest-license[image:https://img.shields.io/badge/License-MPL--2.0-blue.svg[License: +PMPL-1.0]] +https://github.com/hyperpolymath/palimpsest-license[image:https://img.shields.io/badge/Philosophy-Palimpsest-indigo.svg[Palimpsest]] + +[![CI]()](https://github.com/hyperpolymath/branch-newspaper/actions/workflows/ci.yml) +[![Mirror +Sync]()](https://github.com/hyperpolymath/branch-newspaper/actions/workflows/mirror-sync.yml) +[![CodeQL]()](https://github.com/hyperpolymath/branch-newspaper/actions/workflows/codeql.yml) + +A Phoenix LiveView application for citizen journalists and union +branches with integration for decentralized content storage. + +== Features + +* *Meeting Minutes Management* - Create, edit, and organize meeting +minutes +* *IPFS Integration* - Store content on IPFS for decentralized, +immutable storage +* *Real-time UI* - Phoenix LiveView for instant updates without page +reloads +* *Tag Organization* - Categorize minutes with tags for easy discovery + +== Tech Stack + +| Component | Technology | |———–|————| | Language | Elixir ~> 1.15 | | +Framework | Phoenix 1.8.1 | | Real-time | Phoenix LiveView 1.1.0 | | +Database | SQLite3 (dev) / PostgreSQL (prod) | | Storage | IPFS (Kubo) | +| CSS | Tailwind CSS v4 | + +== Prerequisites + +* Elixir 1.15+ and Erlang/OTP 25+ +* Node.js 18+ (for asset compilation) +* IPFS node (Kubo) running locally or accessible + +== Getting Started + +=== Development Setup + +[arabic] +. *Clone the repository* `+\'bash+` `+git+` `+clone+` +https://github.com/hyperpolymath/branch-newspaper.git[`+https://github.com/hyperpolymath/branch-newspaper.git+`] +`+cd+` `+branch-newspaper+`` + +[arabic, start=2] +. *Install dependencies and setup database* `+\'bash+` `+mix+` +`+setup+`` + +[arabic, start=3] +. *Start the IPFS daemon* (in a separate terminal) `+\'bash+` `+ipfs+` +`+daemon+`` + +[arabic, start=4] +. *Start the Phoenix server* `+\'bash+` `+mix+` `+phx.server+` `+#+` +`+Or+` `+with+` `+interactive+` `+Elixir+` `+shell:+` `+iex+` `+-S+` +`+mix+` `+phx.server+`` + +[arabic, start=5] +. *Visit the application* + +.... +Open [http://localhost:4000](http://localhost:4000) in your browser. +.... + +=== Running Tests + +[source,bash] +---- += Run all tests + +mix test + += Run with coverage + +mix test --cover + += Run the precommit checks (format, compile warnings, tests) + +mix precommit +---- + +=== Code Quality + +[source,bash] +---- += Check formatting + +mix format --check-formatted + += Run all lint checks + +./ci-scripts/lint.sh +---- + +== Configuration + +=== Environment Variables + +| Variable | Description | Default | |———-|————-|———| | +`+SECRET_KEY_BASE+` | Phoenix secret key | (generated) | | +`+DATABASE_URL+` | Database connection string | SQLite file | | +`+PHX_HOST+` | Production hostname | localhost | | `+PORT+` | HTTP port +| 4000 | | `+IPFS_API_URL+` | IPFS API endpoint | +http://localhost:5001/api/v0 | + +See [SECRETS.md](SECRETS.md) for complete secrets documentation. + +== Project Structure + +.... +branch-newspaper/ +├── assets/ # Frontend assets (JS, CSS) +├── ci-scripts/ # Shared CI/CD scripts +├── config/ # Application configuration +├── lib/ +│ ├── branch_newspaper/ # Business logic +│ │ ├── content/ # Content domain +│ │ └── services/ # External services (IPFS) +│ └── branch_newspaper_web/ # Web interface +│ ├── components/ # UI components +│ ├── controllers/ # HTTP controllers +│ └── live/ # LiveView modules +├── priv/ # Private application files +└── test/ # Test files +.... + +== Documentation + +* [ROADMAP.adoc](ROADMAP.adoc) - Development roadmap and MVP plan +* [TODO.md](TODO.md) - Task backlog and improvements +* [SECRETS.md](SECRETS.md) - Secrets and configuration guide +* [AGENTS.md](AGENTS.md) - AI coding guidelines + +== CI/CD + +This project uses unified CI/CD that runs on both GitHub Actions and +GitLab CI: + +* *Lint* - Code formatting and static analysis +* *Test* - ExUnit tests across multiple Elixir versions +* *Build* - Release compilation for deployment +* *Mirror* - Automatic sync between GitHub and GitLab + +=== Test Matrix + +| Elixir | OTP | Status | |——–|—–|——–| | 1.15.0 | 25.3 | Minimum +supported | | 1.15.7 | 26.2 | Primary | | 1.16.0 | 26.2 | Latest | + +== Contributing + +[arabic] +. Fork the repository +. Create a feature branch (`+git+` `+checkout+` `+-b+` +`+feature/amazing-feature+`) +. Run the precommit checks (`+mix+` `+precommit+`) +. Commit your changes (`+git+` `+commit+` `+-m+` `+’Add+` `+amazing+` +`+feature’+`) +. Push to the branch (`+git+` `+push+` `+origin+` +`+feature/amazing-feature+`) +. Open a Pull Request + +== Repository Mirrors + +* *Primary (GitHub)*: https://github.com/hyperpolymath/branch-newspaper +* *Mirror (GitLab)*: +https://gitlab.com/maa-framework/3-applications/branch-newspaper + +Changes pushed to GitHub are automatically mirrored to GitLab. + +== License + +This project is licensed under the Palimpsest-MPL-1.0 License - see the +[LICENSE](LICENSE) file for details. + +== Acknowledgments + +* [Phoenix Framework](https://phoenixframework.org/) +* [IPFS](https://ipfs.tech/) +* Part of the [MAA Framework](https://gitlab.com/maa-framework) project + +== Architecture + +See TOPOLOGY for a visual architecture map and completion dashboard. diff --git a/README.md b/README.md deleted file mode 100644 index 7af547e..0000000 --- a/README.md +++ /dev/null @@ -1,207 +0,0 @@ - - -[![License: PMPL-1.0](https://img.shields.io/badge/License-MPL--2.0-blue.svg)](https://github.com/hyperpolymath/palimpsest-license) -[![Palimpsest](https://img.shields.io/badge/Philosophy-Palimpsest-indigo.svg)](https://github.com/hyperpolymath/palimpsest-license) - -\[\![CI\]()\]() -\[\![Mirror -Sync\]()\]() -\[\![CodeQL\]()\]() - -A Phoenix LiveView application for citizen journalists and union -branches with integration for decentralized content storage. - -# Features - -- **Meeting Minutes Management** - Create, edit, and organize meeting - minutes - -- **IPFS Integration** - Store content on IPFS for decentralized, - immutable storage - -- **Real-time UI** - Phoenix LiveView for instant updates without page - reloads - -- **Tag Organization** - Categorize minutes with tags for easy discovery - -# Tech Stack - -\| Component \| Technology \| \|-----------\|------------\| \| Language -\| Elixir ~\> 1.15 \| \| Framework \| Phoenix 1.8.1 \| \| Real-time \| -Phoenix LiveView 1.1.0 \| \| Database \| SQLite3 (dev) / PostgreSQL -(prod) \| \| Storage \| IPFS (Kubo) \| \| CSS \| Tailwind CSS v4 \| - -# Prerequisites - -- Elixir 1.15+ and Erlang/OTP 25+ - -- Node.js 18+ (for asset compilation) - -- IPFS node (Kubo) running locally or accessible - -# Getting Started - -## Development Setup - -1. **Clone the repository** `` `bash `` `git` `clone` - [`https://github.com/hyperpolymath/branch-newspaper.git`](https://github.com/hyperpolymath/branch-newspaper.git) - `cd` `branch-newspaper`\` - - - -2. **Install dependencies and setup database** `` `bash `` `mix` - `setup`\` - - - -3. **Start the IPFS daemon** (in a separate terminal) `` `bash `` - `ipfs` `daemon`\` - - - -4. **Start the Phoenix server** `` `bash `` `mix` `phx.server` `#` `Or` - `with` `interactive` `Elixir` `shell:` `iex` `-S` `mix` - `phx.server`\` - - - -5. **Visit the application** - - - - Open [http://localhost:4000](http://localhost:4000) in your browser. - -## Running Tests - -```bash -= Run all tests - -mix test - -= Run with coverage - -mix test --cover - -= Run the precommit checks (format, compile warnings, tests) - -mix precommit -``` - -## Code Quality - -```bash -= Check formatting - -mix format --check-formatted - -= Run all lint checks - -./ci-scripts/lint.sh -``` - -# Configuration - -## Environment Variables - -\| Variable \| Description \| Default \| -\|----------\|-------------\|---------\| \| `SECRET_KEY_BASE` \| Phoenix -secret key \| (generated) \| \| `DATABASE_URL` \| Database connection -string \| SQLite file \| \| `PHX_HOST` \| Production hostname \| -localhost \| \| `PORT` \| HTTP port \| 4000 \| \| `IPFS_API_URL` \| IPFS -API endpoint \| \| - -See \[SECRETS.md\](SECRETS.md) for complete secrets documentation. - -# Project Structure - - branch-newspaper/ - ├── assets/ # Frontend assets (JS, CSS) - ├── ci-scripts/ # Shared CI/CD scripts - ├── config/ # Application configuration - ├── lib/ - │ ├── branch_newspaper/ # Business logic - │ │ ├── content/ # Content domain - │ │ └── services/ # External services (IPFS) - │ └── branch_newspaper_web/ # Web interface - │ ├── components/ # UI components - │ ├── controllers/ # HTTP controllers - │ └── live/ # LiveView modules - ├── priv/ # Private application files - └── test/ # Test files - -# Documentation - -- \[ROADMAP.adoc\](ROADMAP.adoc) - Development roadmap and MVP plan - -- \[TODO.md\](TODO.md) - Task backlog and improvements - -- \[SECRETS.md\](SECRETS.md) - Secrets and configuration guide - -- \[AGENTS.md\](AGENTS.md) - AI coding guidelines - -# CI/CD - -This project uses unified CI/CD that runs on both GitHub Actions and -GitLab CI: - -- **Lint** - Code formatting and static analysis - -- **Test** - ExUnit tests across multiple Elixir versions - -- **Build** - Release compilation for deployment - -- **Mirror** - Automatic sync between GitHub and GitLab - -## Test Matrix - -\| Elixir \| OTP \| Status \| \|--------\|-----\|--------\| \| 1.15.0 \| -25.3 \| Minimum supported \| \| 1.15.7 \| 26.2 \| Primary \| \| 1.16.0 -\| 26.2 \| Latest \| - -# Contributing - -1. Fork the repository - -2. Create a feature branch (`git` `checkout` `-b` - `feature/amazing-feature`) - -3. Run the precommit checks (`mix` `precommit`) - -4. Commit your changes (`git` `commit` `-m` `’Add` `amazing` - `feature’`) - -5. Push to the branch (`git` `push` `origin` `feature/amazing-feature`) - -6. Open a Pull Request - -# Repository Mirrors - -- **Primary (GitHub)**: - - -- **Mirror (GitLab)**: - - -Changes pushed to GitHub are automatically mirrored to GitLab. - -# License - -This project is licensed under the Palimpsest-MPL-1.0 License - see the -\[LICENSE\](LICENSE) file for details. - -# Acknowledgments - -- \[Phoenix Framework\]() - -- \[IPFS\]() - -- Part of the \[MAA Framework\]() - project - -# Architecture - -See TOPOLOGY for a visual -architecture map and completion dashboard. diff --git a/REQUIRES_INITIALISATION.adoc b/REQUIRES_INITIALISATION.adoc new file mode 100644 index 0000000..8c93317 --- /dev/null +++ b/REQUIRES_INITIALISATION.adoc @@ -0,0 +1,112 @@ +== REQUIRES INITIALISATION + +*This repository is not finished being set up.* 8 substitution token(s) +across 2 file(s) still have no value. + +=== Why this is not already done + +This repo was created from `+hyperpolymath/rsr-template-repo+`. The mint +(`+just repo-init+`) fills every token that has a single mechanical +answer — owner, repo, author, dates, licence, branch — and it has done +so here. + +The tokens below are the ones it _deliberately cannot_ answer. They need +a decision or a fact that exists only in your head: what this project is +for, what command builds it, which port the service listens on, whether +a PGP key is held at all. The template’s own token vocabulary says as +much — you cannot sensibly answer "`required invariants`" in a +thirty-second bootstrap. + +They were left *visibly unfilled on purpose*. The alternatives were both +worse: inventing plausible values would put confident falsehoods into a +security policy and an architecture document, and silently deleting the +sections would hide the fact that a decision is owed. A visible gap is +honest; a fabricated answer is not. + +=== Do not delete this file until every item below is resolved + +This file is the only marker that the work is outstanding. Deleting it +early does not finish the setup, it just conceals it — and the next +person or agent to arrive will reasonably assume the repo is complete. + +* *If you are a person:* delete this file yourself once the last item is +done. +* *If you are an agent:* resolve what you legitimately can, leave the +rest, and delete this file only when no token below remains anywhere in +the tree. Do not delete it to make a gate go green. + +Re-running the estate top-up tool will remove this file automatically +once nothing is outstanding, so the safest way to finish is to fix the +tokens and let the check confirm it. + +=== What is needed, and where it goes + +==== `+{{CONSUMER1}}+` + +A downstream repo that consumes this one. + +Appears in: + +* `+.machine_readable/INTENT.contractile+` + +==== `+{{CONSUMER2}}+` + +A second downstream consumer. + +Appears in: + +* `+.machine_readable/INTENT.contractile+` + +==== `+{{DEP1}}+` + +First named dependency, in .machine_readable/INTENT.contractile. + +Appears in: + +* `+.machine_readable/INTENT.contractile+` + +==== `+{{DEP2}}+` + +Second named dependency, in .machine_readable/INTENT.contractile. + +Appears in: + +* `+.machine_readable/INTENT.contractile+` + +==== `+{{MONOREPO_OR_STANDALONE}}+` + +Literally '`monorepo`' or '`standalone`'. + +Appears in: + +* `+.machine_readable/INTENT.contractile+` + +==== `+{{ONE_PARAGRAPH_ANTI_PURPOSE}}+` + +A paragraph on what this deliberately is NOT for. + +Appears in: + +* `+.machine_readable/INTENT.contractile+` + +==== `+{{ONE_PARAGRAPH_PURPOSE}}+` + +A paragraph on what this is for. + +Appears in: + +* `+.machine_readable/INTENT.contractile+` + +==== `+{{PROJECT_UNIQUE_STRENGTH}}+` + +What this does that its alternatives do not. + +Appears in: + +* `+.machine_readable/agent_instructions/methodology.a2ml+` + +''''' + +Generated by the estate top-up pass. Rationale and the governing rulings +are in `+hyperpolymath/standards+`; the token vocabulary is +`+.machine_readable/ai/PLACEHOLDERS.adoc+` in `+rsr-template-repo+`. diff --git a/REQUIRES_INITIALISATION.md b/REQUIRES_INITIALISATION.md deleted file mode 100644 index b5a1dbf..0000000 --- a/REQUIRES_INITIALISATION.md +++ /dev/null @@ -1,110 +0,0 @@ - - -# REQUIRES INITIALISATION - -**This repository is not finished being set up.** 8 substitution token(s) across 2 file(s) still have no value. - -## Why this is not already done - -This repo was created from `hyperpolymath/rsr-template-repo`. The mint -(`just repo-init`) fills every token that has a single mechanical answer — -owner, repo, author, dates, licence, branch — and it has done so here. - -The tokens below are the ones it *deliberately cannot* answer. They need a -decision or a fact that exists only in your head: what this project is for, -what command builds it, which port the service listens on, whether a PGP key -is held at all. The template's own token vocabulary says as much — you cannot -sensibly answer "required invariants" in a thirty-second bootstrap. - -They were left **visibly unfilled on purpose**. The alternatives were both -worse: inventing plausible values would put confident falsehoods into a -security policy and an architecture document, and silently deleting the -sections would hide the fact that a decision is owed. A visible gap is -honest; a fabricated answer is not. - -## Do not delete this file until every item below is resolved - -This file is the only marker that the work is outstanding. Deleting it early -does not finish the setup, it just conceals it — and the next person or agent -to arrive will reasonably assume the repo is complete. - -- **If you are a person:** delete this file yourself once the last item is done. -- **If you are an agent:** resolve what you legitimately can, leave the rest, - and delete this file only when no token below remains anywhere in the tree. - Do not delete it to make a gate go green. - -Re-running the estate top-up tool will remove this file automatically once -nothing is outstanding, so the safest way to finish is to fix the tokens and -let the check confirm it. - -## What is needed, and where it goes - -### `{{CONSUMER1}}` - -A downstream repo that consumes this one. - -Appears in: - -- `.machine_readable/INTENT.contractile` - -### `{{CONSUMER2}}` - -A second downstream consumer. - -Appears in: - -- `.machine_readable/INTENT.contractile` - -### `{{DEP1}}` - -First named dependency, in .machine_readable/INTENT.contractile. - -Appears in: - -- `.machine_readable/INTENT.contractile` - -### `{{DEP2}}` - -Second named dependency, in .machine_readable/INTENT.contractile. - -Appears in: - -- `.machine_readable/INTENT.contractile` - -### `{{MONOREPO_OR_STANDALONE}}` - -Literally 'monorepo' or 'standalone'. - -Appears in: - -- `.machine_readable/INTENT.contractile` - -### `{{ONE_PARAGRAPH_ANTI_PURPOSE}}` - -A paragraph on what this deliberately is NOT for. - -Appears in: - -- `.machine_readable/INTENT.contractile` - -### `{{ONE_PARAGRAPH_PURPOSE}}` - -A paragraph on what this is for. - -Appears in: - -- `.machine_readable/INTENT.contractile` - -### `{{PROJECT_UNIQUE_STRENGTH}}` - -What this does that its alternatives do not. - -Appears in: - -- `.machine_readable/agent_instructions/methodology.a2ml` - ---- - -Generated by the estate top-up pass. Rationale and the governing rulings are -in `hyperpolymath/standards`; the token vocabulary is -`.machine_readable/ai/PLACEHOLDERS.adoc` in `rsr-template-repo`. diff --git a/SECRETS.adoc b/SECRETS.adoc new file mode 100644 index 0000000..d8af18d --- /dev/null +++ b/SECRETS.adoc @@ -0,0 +1,198 @@ +== Secrets Configuration + +This document lists all secrets required for the Branch Newspaper +application and CI/CD pipelines. + +=== GitHub Secrets + +Configure these in: *Settings → Secrets and variables → Actions* + +==== Required Secrets + +[width="100%",cols="26%,26%,18%,30%",options="header",] +|=== +|Secret Name |Description |Used By |How to Obtain +|`+GITLAB_SSH_KEY+` |SSH private key for GitLab push access +|`+mirror-sync.yml+`, `+ci.yml+` |See link:#gitlab-ssh-key-setup[GitLab +SSH Key Setup] +|=== + +==== Optional Secrets (for enhanced features) + +[width="100%",cols="26%,26%,18%,30%",options="header",] +|=== +|Secret Name |Description |Used By |How to Obtain +|`+CODECOV_TOKEN+` |Token for uploading coverage reports |`+ci.yml+` (if +coverage enabled) |https://codecov.io[codecov.io] → Settings + +|`+DOCKERHUB_USERNAME+` |Docker Hub username for image publishing +|Deployment workflows |https://hub.docker.com[hub.docker.com] account + +|`+DOCKERHUB_TOKEN+` |Docker Hub access token |Deployment workflows +|Docker Hub → Account Settings → Security +|=== + +''''' + +=== GitLab CI/CD Variables + +Configure these in: *Settings → CI/CD → Variables* + +==== Required Variables + +[width="100%",cols="33%,27%,23%,17%",options="header",] +|=== +|Variable Name |Description |Protected |Masked +|`+GITHUB_MIRROR_TOKEN+` |GitHub PAT for pull mirroring (if used) |Yes +|Yes +|=== + +==== Optional Variables + +[cols=",,,",options="header",] +|=== +|Variable Name |Description |Protected |Masked +|`+DEPLOY_SSH_KEY+` |SSH key for deployment servers |Yes |Yes +|`+STAGING_HOST+` |Staging server hostname |No |No +|`+PRODUCTION_HOST+` |Production server hostname |Yes |No +|=== + +''''' + +=== Application Secrets + +These should be set as environment variables in your deployment +environment. + +==== Required for Production + +[width="100%",cols="50%,30%,20%",options="header",] +|=== +|Environment Variable |Description |Example +|`+SECRET_KEY_BASE+` |Phoenix secret key (64+ chars) |Generate with +`+mix phx.gen.secret+` + +|`+DATABASE_URL+` |Database connection string (if using external DB) +|`+ecto://user:pass@host/db+` + +|`+PHX_HOST+` |Production hostname |`+branch-newspaper.example.com+` + +|`+PORT+` |HTTP port to listen on |`+4000+` +|=== + +==== IPFS Configuration + +[width="100%",cols="50%,30%,20%",options="header",] +|=== +|Environment Variable |Description |Default +|`+IPFS_API_URL+` |IPFS node API endpoint +|`+http://localhost:5001/api/v0+` + +|`+IPFS_GATEWAY_URL+` |IPFS gateway for content retrieval +|`+http://localhost:8080/ipfs+` +|=== + +''''' + +=== Setup Instructions + +==== GitLab SSH Key Setup + +This is required for the GitHub → GitLab mirror sync to work. + +[arabic] +. *Generate a new SSH key pair* (or use an existing one): ++ +[source,bash] +---- +ssh-keygen -t ed25519 -C "github-to-gitlab-mirror" -f gitlab_deploy_key +---- +. *Add the PUBLIC key to GitLab*: +* Go to: +https://gitlab.com/maa-framework/3-applications/branch-newspaper[gitlab.com/maa-framework/3-applications/branch-newspaper] +* Navigate to: Settings → Repository → Deploy keys +* Click "`Add deploy key`" +* Paste the contents of `+gitlab_deploy_key.pub+` +* *Enable "`Grant write permissions to this key`"* +. *Add the PRIVATE key to GitHub*: +* Go to: +https://github.com/hyperpolymath/branch-newspaper[github.com/hyperpolymath/branch-newspaper] +* Navigate to: Settings → Secrets and variables → Actions +* Click "`New repository secret`" +* Name: `+GITLAB_SSH_KEY+` +* Value: Paste the entire contents of `+gitlab_deploy_key+` (the private +key file) +. *Verify the setup*: +* Go to Actions tab in GitHub +* Manually trigger "`Mirror Sync`" workflow +* Check the workflow logs + +==== Generating Phoenix Secret Key + +[source,bash] +---- +# In a terminal with Elixir installed: +mix phx.gen.secret + +# Or using OpenSSL: +openssl rand -base64 64 +---- + +==== Database URL Format + +For different database backends: + +[source,bash] +---- +# SQLite (default for development) +# No DATABASE_URL needed - uses local file + +# PostgreSQL +DATABASE_URL=ecto://username:password@hostname:5432/database_name + +# MySQL +DATABASE_URL=ecto://username:password@hostname:3306/database_name +---- + +''''' + +=== Security Best Practices + +[arabic] +. *Never commit secrets to version control* +* Use `+.env+` files locally (add to `+.gitignore+`) +* Use CI/CD secret management features +. *Rotate secrets regularly* +* `+SECRET_KEY_BASE+`: Rotate quarterly or after personnel changes +* `+GITLAB_SSH_KEY+`: Rotate annually or after suspected compromise +. *Use the principle of least privilege* +* Deploy keys should have minimal required permissions +* API tokens should be scoped appropriately +. *Monitor for exposed secrets* +* Enable GitHub secret scanning +* Use pre-commit hooks to prevent accidental commits + +''''' + +=== Troubleshooting + +==== Mirror sync fails with "`Permission denied`" + +* Verify `+GITLAB_SSH_KEY+` is set correctly +* Ensure the deploy key has write permission on GitLab +* Check that the key format is correct (full private key including +headers) + +==== CI fails to fetch dependencies + +* Check if `+HEX_API_KEY+` is needed for private packages +* Verify network access from CI runners + +==== Deployment fails with "`SECRET_KEY_BASE not set`" + +* Ensure all required environment variables are configured +* Check deployment platform’s secret management + +''''' + +_Last updated: 2025-12-08_ diff --git a/SECRETS.md b/SECRETS.md deleted file mode 100644 index 6221182..0000000 --- a/SECRETS.md +++ /dev/null @@ -1,161 +0,0 @@ -# Secrets Configuration - -This document lists all secrets required for the Branch Newspaper application and CI/CD pipelines. - -## GitHub Secrets - -Configure these in: **Settings → Secrets and variables → Actions** - -### Required Secrets - -| Secret Name | Description | Used By | How to Obtain | -|-------------|-------------|---------|---------------| -| `GITLAB_SSH_KEY` | SSH private key for GitLab push access | `mirror-sync.yml`, `ci.yml` | See [GitLab SSH Key Setup](#gitlab-ssh-key-setup) | - -### Optional Secrets (for enhanced features) - -| Secret Name | Description | Used By | How to Obtain | -|-------------|-------------|---------|---------------| -| `CODECOV_TOKEN` | Token for uploading coverage reports | `ci.yml` (if coverage enabled) | [codecov.io](https://codecov.io) → Settings | -| `DOCKERHUB_USERNAME` | Docker Hub username for image publishing | Deployment workflows | [hub.docker.com](https://hub.docker.com) account | -| `DOCKERHUB_TOKEN` | Docker Hub access token | Deployment workflows | Docker Hub → Account Settings → Security | - ---- - -## GitLab CI/CD Variables - -Configure these in: **Settings → CI/CD → Variables** - -### Required Variables - -| Variable Name | Description | Protected | Masked | -|---------------|-------------|-----------|--------| -| `GITHUB_MIRROR_TOKEN` | GitHub PAT for pull mirroring (if used) | Yes | Yes | - -### Optional Variables - -| Variable Name | Description | Protected | Masked | -|---------------|-------------|-----------|--------| -| `DEPLOY_SSH_KEY` | SSH key for deployment servers | Yes | Yes | -| `STAGING_HOST` | Staging server hostname | No | No | -| `PRODUCTION_HOST` | Production server hostname | Yes | No | - ---- - -## Application Secrets - -These should be set as environment variables in your deployment environment. - -### Required for Production - -| Environment Variable | Description | Example | -|---------------------|-------------|---------| -| `SECRET_KEY_BASE` | Phoenix secret key (64+ chars) | Generate with `mix phx.gen.secret` | -| `DATABASE_URL` | Database connection string (if using external DB) | `ecto://user:pass@host/db` | -| `PHX_HOST` | Production hostname | `branch-newspaper.example.com` | -| `PORT` | HTTP port to listen on | `4000` | - -### IPFS Configuration - -| Environment Variable | Description | Default | -|---------------------|-------------|---------| -| `IPFS_API_URL` | IPFS node API endpoint | `http://localhost:5001/api/v0` | -| `IPFS_GATEWAY_URL` | IPFS gateway for content retrieval | `http://localhost:8080/ipfs` | - ---- - -## Setup Instructions - -### GitLab SSH Key Setup - -This is required for the GitHub → GitLab mirror sync to work. - -1. **Generate a new SSH key pair** (or use an existing one): - ```bash - ssh-keygen -t ed25519 -C "github-to-gitlab-mirror" -f gitlab_deploy_key - ``` - -2. **Add the PUBLIC key to GitLab**: - - Go to: [gitlab.com/maa-framework/3-applications/branch-newspaper](https://gitlab.com/maa-framework/3-applications/branch-newspaper) - - Navigate to: Settings → Repository → Deploy keys - - Click "Add deploy key" - - Paste the contents of `gitlab_deploy_key.pub` - - **Enable "Grant write permissions to this key"** - -3. **Add the PRIVATE key to GitHub**: - - Go to: [github.com/hyperpolymath/branch-newspaper](https://github.com/hyperpolymath/branch-newspaper) - - Navigate to: Settings → Secrets and variables → Actions - - Click "New repository secret" - - Name: `GITLAB_SSH_KEY` - - Value: Paste the entire contents of `gitlab_deploy_key` (the private key file) - -4. **Verify the setup**: - - Go to Actions tab in GitHub - - Manually trigger "Mirror Sync" workflow - - Check the workflow logs - -### Generating Phoenix Secret Key - -```bash -# In a terminal with Elixir installed: -mix phx.gen.secret - -# Or using OpenSSL: -openssl rand -base64 64 -``` - -### Database URL Format - -For different database backends: - -```bash -# SQLite (default for development) -# No DATABASE_URL needed - uses local file - -# PostgreSQL -DATABASE_URL=ecto://username:password@hostname:5432/database_name - -# MySQL -DATABASE_URL=ecto://username:password@hostname:3306/database_name -``` - ---- - -## Security Best Practices - -1. **Never commit secrets to version control** - - Use `.env` files locally (add to `.gitignore`) - - Use CI/CD secret management features - -2. **Rotate secrets regularly** - - `SECRET_KEY_BASE`: Rotate quarterly or after personnel changes - - `GITLAB_SSH_KEY`: Rotate annually or after suspected compromise - -3. **Use the principle of least privilege** - - Deploy keys should have minimal required permissions - - API tokens should be scoped appropriately - -4. **Monitor for exposed secrets** - - Enable GitHub secret scanning - - Use pre-commit hooks to prevent accidental commits - ---- - -## Troubleshooting - -### Mirror sync fails with "Permission denied" -- Verify `GITLAB_SSH_KEY` is set correctly -- Ensure the deploy key has write permission on GitLab -- Check that the key format is correct (full private key including headers) - -### CI fails to fetch dependencies -- Check if `HEX_API_KEY` is needed for private packages -- Verify network access from CI runners - -### Deployment fails with "SECRET_KEY_BASE not set" -- Ensure all required environment variables are configured -- Check deployment platform's secret management - ---- - -*Last updated: 2025-12-08* diff --git a/SECURITY.md b/SECURITY.adoc similarity index 52% rename from SECURITY.md rename to SECURITY.adoc index 034e848..1288150 100644 --- a/SECURITY.md +++ b/SECURITY.adoc @@ -1,21 +1,23 @@ -# Security Policy +== Security Policy -## Supported Versions +=== 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: | +[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 +=== 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. +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..aff587c --- /dev/null +++ b/TEST-NEEDS.adoc @@ -0,0 +1,32 @@ +== TEST-NEEDS.md — branch-newspaper + +=== CRG Grade: C — ACHIEVED 2026-04-04 + +=== Current Test State + +[cols=",,",options="header",] +|=== +|Category |Count |Notes +|Test directories |1 |Location(s): /tests +|CI workflows |20 |Running tests on GitHub Actions +|Tests |Present |Configured in CI workflows +|=== + +=== What’s Covered + +* [x] Tests present and running +* [x] CI integration active + +=== Still Missing (for CRG B+) + +* [ ] Code coverage reports (codecov integration) +* [ ] Detailed test documentation in CONTRIBUTING.md +* [ ] Integration tests beyond unit tests +* [ ] Performance benchmarking suite + +=== Run Tests + +[source,bash] +---- +(check Makefile/justfile/package.json for test command) +---- diff --git a/TEST-NEEDS.md b/TEST-NEEDS.md deleted file mode 100644 index c4e9ed4..0000000 --- a/TEST-NEEDS.md +++ /dev/null @@ -1,29 +0,0 @@ -# TEST-NEEDS.md — branch-newspaper - -## CRG Grade: C — ACHIEVED 2026-04-04 - -## Current Test State - -| Category | Count | Notes | -|----------|-------|-------| -| Test directories | 1 | Location(s): /tests | -| CI workflows | 20 | Running tests on GitHub Actions | -| Tests | Present | Configured in CI workflows | - -## What's Covered - -- [x] Tests present and running -- [x] CI integration active - -## Still Missing (for CRG B+) - -- [ ] Code coverage reports (codecov integration) -- [ ] Detailed test documentation in CONTRIBUTING.md -- [ ] Integration tests beyond unit tests -- [ ] Performance benchmarking suite - -## Run Tests - -```bash -(check Makefile/justfile/package.json for test command) -``` diff --git a/TOPOLOGY.md b/TOPOLOGY.adoc similarity index 88% rename from TOPOLOGY.md rename to TOPOLOGY.adoc index afaf0bb..03071f7 100644 --- a/TOPOLOGY.md +++ b/TOPOLOGY.adoc @@ -1,12 +1,8 @@ - - - +== Branch Newspaper — Project Topology -# Branch Newspaper — Project Topology +=== System Architecture -## System Architecture - -``` +.... ┌─────────────────────────────────────────┐ │ USERS / CLIENTS │ │ (Browser / LiveView Socket) │ @@ -45,11 +41,11 @@ │ ci-scripts/ .machine_readable/ │ │ Justfile Mirror Sync │ └─────────────────────────────────────────┘ -``` +.... -## Completion Dashboard +=== Completion Dashboard -``` +.... COMPONENT STATUS NOTES ───────────────────────────────── ────────────────── ───────────────────────────────── WEB & UI @@ -69,25 +65,26 @@ REPO INFRASTRUCTURE ───────────────────────────────────────────────────────────────────────────── OVERALL: █████████░ ~90% Feature-complete for branch use -``` +.... -## Key Dependencies +=== Key Dependencies -``` +.... User Input ───► LiveView ───► Content Logic ───► Database │ ▼ IPFS (Kubo) -``` +.... -## 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..db0156a --- /dev/null +++ b/docs/tech-debt-2026-05-26.adoc @@ -0,0 +1,71 @@ +== Tech-Debt Audit — branch-newspaper — 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 |182 +|`+docs/+` files |2 +|`+docs/+` LoC |227 +|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 +182 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 255f5f5..0000000 --- a/docs/tech-debt-2026-05-26.md +++ /dev/null @@ -1,57 +0,0 @@ - - -# Tech-Debt Audit — branch-newspaper — 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 | 182 | -| `docs/` files | 2 | -| `docs/` LoC | 227 | -| 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 182 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..1125d7b --- /dev/null +++ b/llm-warmup-dev.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — branch-newspaper (Developer) + +=== What is branch-newspaper? + +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 92f53db..0000000 --- a/llm-warmup-dev.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — branch-newspaper (Developer) - -## What is branch-newspaper? -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..5832aa5 --- /dev/null +++ b/llm-warmup-user.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — branch-newspaper (User) + +=== What is branch-newspaper? + +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 b02b50c..0000000 --- a/llm-warmup-user.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — branch-newspaper (User) - -## What is branch-newspaper? -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