From ef3c6c9f2e8ed5cdb30454eb829fe1f751de00b6 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Mon, 24 Aug 2026 08:53:32 +0100 Subject: [PATCH] refactor: migrate repository documentation from Markdown to AsciiDoc --- ARCHITECTURE.adoc | 48 ++ ARCHITECTURE.md | 47 - CHANGELOG.adoc | 75 ++ CHANGELOG.md | 69 -- CODE_OF_CONDUCT.adoc | 339 ++++++++ CODE_OF_CONDUCT.md | 331 ------- CONTRIBUTING.adoc | 109 +++ CONTRIBUTING.md | 120 --- GOVERNANCE.adoc | 178 +--- GOVERNANCE.md | 60 -- PROOF-NEEDS.adoc | 12 + PROOF-NEEDS.md | 14 - SECURITY.adoc | 452 ++++++++++ SECURITY.md | 410 --------- TEST-NEEDS.adoc | 43 + TEST-NEEDS.md | 39 - TOPOLOGY.md => TOPOLOGY.adoc | 42 +- docs/tech-debt-2026-05-26.adoc | 71 ++ docs/tech-debt-2026-05-26.md | 56 -- journal-theme/.meta/REQUIRED-FILES.adoc | 58 ++ journal-theme/.meta/REQUIRED-FILES.md | 57 -- journal-theme/CODE_OF_CONDUCT.adoc | 174 ++++ journal-theme/CODE_OF_CONDUCT.md | 170 ---- journal-theme/CONTRIBUTING.adoc | 116 ++- journal-theme/CONTRIBUTING.md | 120 --- journal-theme/INSTALL.adoc | 346 ++++++++ journal-theme/INSTALL.md | 310 ------- journal-theme/MAINTAINERS.adoc | 163 +++- journal-theme/MAINTAINERS.md | 119 --- ...E-DEPLOYMENT.md => README-DEPLOYMENT.adoc} | 182 ++-- journal-theme/RSR-COMPLIANCE.adoc | 406 +++++++++ journal-theme/RSR-COMPLIANCE.md | 398 --------- journal-theme/RSR-SILVER-ACHIEVEMENT.adoc | 414 +++++++++ journal-theme/RSR-SILVER-ACHIEVEMENT.md | 449 ---------- journal-theme/SECURITY.adoc | 207 +++++ journal-theme/SECURITY.md | 171 ---- journal-theme/{TESTING.md => TESTING.adoc} | 301 ++++--- journal-theme/changelog.adoc | 21 + journal-theme/changelog.md | 20 - journal-theme/content/EXPLAINME.adoc | 4 + journal-theme/content/EXPLAINME.md | 8 - .../content/field-notes/fog-breathing.adoc | 1 + .../content/field-notes/fog-breathing.md | 5 - .../docs/PHP-SECURITY-INTEGRATION.adoc | 232 +++++ .../docs/PHP-SECURITY-INTEGRATION.md | 206 ----- journal-theme/docs/PORTALS.adoc | 46 + journal-theme/docs/PORTALS.md | 37 - journal-theme/docs/README.adoc | 16 + journal-theme/docs/README.md | 14 - .../docs/contributing-philosophy.adoc | 1 + journal-theme/docs/contributing-philosophy.md | 5 - journal-theme/docs/ethos.adoc | 1 + journal-theme/docs/ethos.md | 5 - journal-theme/docs/spans.adoc | 1 + journal-theme/docs/spans.md | 5 - journal-theme/docs/styles-guide.adoc | 20 + journal-theme/docs/styles-guide.md | 20 - journal-theme/docs/taxonomy.adoc | 1 + journal-theme/docs/taxonomy.md | 5 - journal-theme/entries/EXPLAINME.adoc | 4 + journal-theme/entries/EXPLAINME.md | 8 - .../semantic/constructs/EXPLAINME.adoc | 41 + .../semantic/constructs/EXPLAINME.md | 35 - journal-theme/semantic/glosses/EXPLAINME.adoc | 53 ++ journal-theme/semantic/glosses/EXPLAINME.md | 45 - journal-theme/tests/aria-checklist.adoc | 25 + journal-theme/tests/aria-checklist.md | 23 - journal-theme/tests/validator-links.adoc | 5 + journal-theme/tests/validator-links.md | 8 - llm-warmup-dev.adoc | 19 + llm-warmup-dev.md | 20 - llm-warmup-user.adoc | 19 + llm-warmup-user.md | 20 - .../.meta/REQUIRED-FILES.adoc | 58 ++ .../.meta/REQUIRED-FILES.md | 57 -- .../ABI-FFI-README.adoc | 244 +++--- plugin-conflict-mapper/CODE_OF_CONDUCT.adoc | 160 ++++ plugin-conflict-mapper/CODE_OF_CONDUCT.md | 159 ---- plugin-conflict-mapper/CONTRIBUTING.adoc | 581 ++----------- plugin-conflict-mapper/CONTRIBUTING.md | 120 --- .../{DEVELOPER.md => DEVELOPER.adoc} | 428 ++++----- plugin-conflict-mapper/MAINTAINERS.adoc | 251 +++++- plugin-conflict-mapper/MAINTAINERS.md | 222 ----- plugin-conflict-mapper/REVERSIBILITY.adoc | 514 +++++++++++ plugin-conflict-mapper/REVERSIBILITY.md | 485 ----------- plugin-conflict-mapper/RSR-COMPLIANCE.adoc | 451 ++++++++++ plugin-conflict-mapper/RSR-COMPLIANCE.md | 417 --------- plugin-conflict-mapper/RSR-GOLD-PROGRESS.adoc | 339 ++++++++ plugin-conflict-mapper/RSR-GOLD-PROGRESS.md | 366 -------- plugin-conflict-mapper/SECURITY.adoc | 170 ++++ plugin-conflict-mapper/SECURITY.md | 153 ---- .../docs/SECURITY-INTEGRATION.adoc | 346 ++++++++ .../docs/SECURITY-INTEGRATION.md | 286 ------ plugin-conflict-mapper/index.adoc | 1 + plugin-conflict-mapper/index.md | 4 - .../ABI-FFI-README.adoc | 244 +++--- praxis/CODE_OF_CONDUCT.adoc | 194 +++++ praxis/CODE_OF_CONDUCT.md | 131 --- praxis/CONTRIBUTING.adoc | 116 ++- praxis/CONTRIBUTING.md | 120 --- praxis/Core/cli-wrapper/README.adoc | 150 ++++ praxis/Core/cli-wrapper/README.md | 143 --- .../db-schema/IMPLEMENTATION_SUMMARY.adoc | 319 +++++++ .../Core/db-schema/IMPLEMENTATION_SUMMARY.md | 298 ------- .../{QUICKSTART.md => QUICKSTART.adoc} | 151 ++-- praxis/Core/db-schema/README.adoc | 383 +++++++++ praxis/Core/db-schema/README.md | 378 -------- .../introspection/{README.md => README.adoc} | 261 +++--- .../Core/introspection/docs/ARCHITECTURE.adoc | 319 +++++++ .../Core/introspection/docs/ARCHITECTURE.md | 325 ------- .../docs/{EXAMPLES.md => EXAMPLES.adoc} | 141 +-- .../{README.md => README.adoc} | 372 ++++---- praxis/Core/manifest-parser/docs/API.adoc | 414 +++++++++ praxis/Core/manifest-parser/docs/API.md | 471 ---------- .../manifest-parser/docs/MANIFEST_FORMAT.adoc | 487 +++++++++++ .../manifest-parser/docs/MANIFEST_FORMAT.md | 416 --------- praxis/DEPENDENCY_AUDIT.adoc | 384 +++++++++ praxis/DEPENDENCY_AUDIT.md | 308 ------- praxis/IMPLEMENTATION_SUMMARY.adoc | 604 +++++++++++++ praxis/IMPLEMENTATION_SUMMARY.md | 622 -------------- praxis/INTEGRATION_STATUS.adoc | 534 ++++++++++++ praxis/INTEGRATION_STATUS.md | 502 ----------- praxis/MAINTAINERS.adoc | 227 ++++- praxis/MAINTAINERS.md | 219 ----- praxis/MANUAL_REVIEW_NEEDED.adoc | 20 + praxis/MANUAL_REVIEW_NEEDED.md | 21 - praxis/REVERSIBILITY.adoc | 312 +++++++ praxis/REVERSIBILITY.md | 291 ------- praxis/RHODIUM_PLATINUM_ROADMAP.adoc | 526 ++++++++++++ praxis/RHODIUM_PLATINUM_ROADMAP.md | 588 ------------- praxis/RSR_COMPLIANCE.adoc | 413 +++++++++ praxis/RSR_COMPLIANCE.md | 417 --------- praxis/RSR_IMPLEMENTATION.adoc | 386 +++++++++ praxis/RSR_IMPLEMENTATION.md | 397 --------- praxis/SECURITY.adoc | 253 ++++++ praxis/SECURITY.md | 231 ----- praxis/SymbolicEngine/core/README.adoc | 446 ++++++++++ praxis/SymbolicEngine/core/README.md | 419 --------- praxis/SymbolicEngine/dashboard/README.adoc | 695 +++++++++++++++ praxis/SymbolicEngine/dashboard/README.md | 631 -------------- .../graphql/{README.md => README.adoc} | 355 ++++---- .../{SCHEMA_GUIDE.md => SCHEMA_GUIDE.adoc} | 464 +++++----- .../swarm/{README.md => README.adoc} | 440 +++++----- praxis/engine/php/{README.md => README.adoc} | 282 +++--- praxis/examples/EXAMPLES_SUMMARY.adoc | 548 ++++++++++++ praxis/examples/EXAMPLES_SUMMARY.md | 689 --------------- praxis/examples/FAQ.adoc | 365 ++++++++ praxis/examples/FAQ.md | 412 --------- praxis/examples/QUICKSTART.adoc | 281 ++++++ praxis/examples/QUICKSTART.md | 257 ------ praxis/examples/README.adoc | 408 +++++++++ praxis/examples/README.md | 410 --------- praxis/examples/TROUBLESHOOTING.adoc | 812 ++++++++++++++++++ praxis/examples/TROUBLESHOOTING.md | 770 ----------------- .../{README.md => README.adoc} | 182 ++-- .../{README.md => README.adoc} | 467 +++++----- .../02-wordpress-integration/README.adoc | 477 ++++++++++ .../02-wordpress-integration/README.md | 472 ---------- .../03-swarm-setup/{README.md => README.adoc} | 191 ++-- .../{README.md => README.adoc} | 142 +-- .../{README.md => README.adoc} | 185 ++-- praxis/examples/video-demo/DEMO_SCRIPT.adoc | 386 +++++++++ praxis/examples/video-demo/DEMO_SCRIPT.md | 353 -------- praxis/plugin/README.adoc | 308 +++++++ praxis/plugin/README.md | 294 ------- praxis/tests/{README.md => README.adoc} | 438 +++++----- praxis/wp_injector/IMPLEMENTATION.adoc | 522 +++++++++++ praxis/wp_injector/IMPLEMENTATION.md | 506 ----------- praxis/wp_injector/QUICKSTART.adoc | 284 ++++++ praxis/wp_injector/QUICKSTART.md | 269 ------ praxis/wp_injector/README.adoc | 498 +++++++++++ praxis/wp_injector/README.md | 480 ----------- .../wp_praxis_core/FORMAL_VERIFICATION.adoc | 288 +++++++ praxis/wp_praxis_core/FORMAL_VERIFICATION.md | 277 ------ project-wharf/CODE_OF_CONDUCT.adoc | 24 + project-wharf/CODE_OF_CONDUCT.md | 30 - project-wharf/CONTRIBUTING.adoc | 282 ++---- project-wharf/CONTRIBUTING.md | 120 --- project-wharf/MAINTAINERS.adoc | 67 +- project-wharf/MAINTAINERS.md | 49 -- project-wharf/REVERSIBILITY.adoc | 216 +++++ project-wharf/REVERSIBILITY.md | 197 ----- project-wharf/SECURITY.adoc | 156 ++++ project-wharf/SECURITY.md | 138 --- project-wharf/TOPOLOGY.adoc | 172 ++++ project-wharf/TOPOLOGY.md | 118 --- .../{ARCHITECTURE.md => ARCHITECTURE.adoc} | 360 ++++---- ...{ABI-FFI-README.md => ABI-FFI-README.adoc} | 244 +++--- resurrect/CODE_OF_CONDUCT.adoc | 339 ++++++++ resurrect/CODE_OF_CONDUCT.md | 331 ------- resurrect/CONTRIBUTING.adoc | 116 ++- resurrect/CONTRIBUTING.md | 120 --- resurrect/SECURITY.adoc | 452 ++++++++++ resurrect/SECURITY.md | 410 --------- .../ABI-FFI-README.adoc | 244 +++--- secured/CODE_OF_CONDUCT.adoc | 339 ++++++++ secured/CODE_OF_CONDUCT.md | 331 ------- secured/CONTRIBUTING.adoc | 109 +++ secured/CONTRIBUTING.md | 120 --- secured/README.adoc | 382 ++++++-- secured/README.md | 318 ------- secured/SECURITY.adoc | 452 ++++++++++ secured/SECURITY.md | 410 --------- ...ATION-TESTS.md => VERIFICATION-TESTS.adoc} | 360 ++++---- secured/php-aegis/CODE_OF_CONDUCT.adoc | 60 ++ secured/php-aegis/CODE_OF_CONDUCT.md | 45 - secured/php-aegis/COMPATIBILITY.adoc | 236 +++++ secured/php-aegis/COMPATIBILITY.md | 223 ----- secured/php-aegis/CONTRIBUTING.adoc | 106 ++- secured/php-aegis/CONTRIBUTING.md | 93 -- .../php-aegis/PHP_AEGIS_ANALYSIS_SUMMARY.adoc | 456 ++++++++++ .../php-aegis/PHP_AEGIS_ANALYSIS_SUMMARY.md | 417 --------- secured/php-aegis/POSITIONING.adoc | 294 +++++++ secured/php-aegis/POSITIONING.md | 235 ----- secured/php-aegis/ROADMAP_PRIORITY.adoc | 386 +++++++++ secured/php-aegis/ROADMAP_PRIORITY.md | 331 ------- secured/php-aegis/SECURITY.adoc | 52 ++ secured/php-aegis/SECURITY.md | 48 -- ...RATION.md => CERRO-TORRE-INTEGRATION.adoc} | 356 ++++---- secured/php-aegis/docs/VALIDATION-PLAN.adoc | 400 +++++++++ secured/php-aegis/docs/VALIDATION-PLAN.md | 425 --------- secured/php-aegis/validation/README.adoc | 276 ++++++ secured/php-aegis/validation/README.md | 265 ------ .../validation/VALIDATION-REPORT.adoc | 423 +++++++++ .../php-aegis/validation/VALIDATION-REPORT.md | 405 --------- sinople-theme/.meta/REQUIRED-FILES.adoc | 58 ++ sinople-theme/.meta/REQUIRED-FILES.md | 57 -- sinople-theme/ABI-FFI-README.adoc | 409 +++++++++ sinople-theme/ABI-FFI-README.md | 389 --------- sinople-theme/CODE_OF_CONDUCT.adoc | 234 +++++ sinople-theme/CODE_OF_CONDUCT.md | 232 ----- sinople-theme/CONTRIBUTING.adoc | 116 ++- sinople-theme/CONTRIBUTING.md | 120 --- sinople-theme/CRYPTOGRAPHIC-INTEGRATION.adoc | 656 ++++++++++++++ sinople-theme/CRYPTOGRAPHIC-INTEGRATION.md | 639 -------------- sinople-theme/DOGFOODING-LESSONS.adoc | 219 +++++ sinople-theme/DOGFOODING-LESSONS.md | 200 ----- sinople-theme/MAINTAINERS.adoc | 252 +++++- sinople-theme/MAINTAINERS.md | 239 ------ sinople-theme/PROJECT_SUMMARY.adoc | 381 ++++++++ sinople-theme/PROJECT_SUMMARY.md | 437 ---------- sinople-theme/RSR_AUDIT.adoc | 203 +++++ sinople-theme/RSR_AUDIT.md | 191 ---- sinople-theme/RSR_COMPLETION.adoc | 469 ++++++++++ sinople-theme/RSR_COMPLETION.md | 476 ---------- sinople-theme/SECURITY.adoc | 202 +++++ sinople-theme/SECURITY.md | 187 ---- sinople-theme/SECURITY_INTEGRATION.adoc | 357 ++++++++ sinople-theme/SECURITY_INTEGRATION.md | 337 -------- sinople-theme/STACK.adoc | 136 +++ sinople-theme/STACK.md | 122 --- sinople-theme/THEME-ENHANCEMENTS.adoc | 514 +++++++++++ sinople-theme/THEME-ENHANCEMENTS.md | 422 --------- ... => THEME_TRANSPILATION_ARCHITECTURE.adoc} | 536 ++++++------ sinople-theme/TPCF.adoc | 359 ++++++++ sinople-theme/TPCF.md | 407 --------- sinople-theme/USAGE.adoc | 92 ++ sinople-theme/USAGE.md | 90 -- .../wordpress/SECURITY_INTEGRATION.adoc | 269 ++++++ .../wordpress/SECURITY_INTEGRATION.md | 247 ------ 260 files changed, 32564 insertions(+), 32506 deletions(-) create mode 100644 ARCHITECTURE.adoc delete mode 100644 ARCHITECTURE.md create mode 100644 CHANGELOG.adoc delete mode 100644 CHANGELOG.md create mode 100644 CODE_OF_CONDUCT.adoc delete mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.adoc delete mode 100644 CONTRIBUTING.md delete mode 100644 GOVERNANCE.md create mode 100644 PROOF-NEEDS.adoc delete mode 100644 PROOF-NEEDS.md create mode 100644 SECURITY.adoc delete mode 100644 SECURITY.md create mode 100644 TEST-NEEDS.adoc delete mode 100644 TEST-NEEDS.md rename TOPOLOGY.md => TOPOLOGY.adoc (86%) create mode 100644 docs/tech-debt-2026-05-26.adoc delete mode 100644 docs/tech-debt-2026-05-26.md create mode 100644 journal-theme/.meta/REQUIRED-FILES.adoc delete mode 100644 journal-theme/.meta/REQUIRED-FILES.md create mode 100644 journal-theme/CODE_OF_CONDUCT.adoc delete mode 100644 journal-theme/CODE_OF_CONDUCT.md delete mode 100644 journal-theme/CONTRIBUTING.md create mode 100644 journal-theme/INSTALL.adoc delete mode 100644 journal-theme/INSTALL.md delete mode 100644 journal-theme/MAINTAINERS.md rename journal-theme/{README-DEPLOYMENT.md => README-DEPLOYMENT.adoc} (55%) create mode 100644 journal-theme/RSR-COMPLIANCE.adoc delete mode 100644 journal-theme/RSR-COMPLIANCE.md create mode 100644 journal-theme/RSR-SILVER-ACHIEVEMENT.adoc delete mode 100644 journal-theme/RSR-SILVER-ACHIEVEMENT.md create mode 100644 journal-theme/SECURITY.adoc delete mode 100644 journal-theme/SECURITY.md rename journal-theme/{TESTING.md => TESTING.adoc} (60%) create mode 100644 journal-theme/changelog.adoc delete mode 100644 journal-theme/changelog.md create mode 100644 journal-theme/content/EXPLAINME.adoc delete mode 100644 journal-theme/content/EXPLAINME.md create mode 100644 journal-theme/content/field-notes/fog-breathing.adoc delete mode 100644 journal-theme/content/field-notes/fog-breathing.md create mode 100644 journal-theme/docs/PHP-SECURITY-INTEGRATION.adoc delete mode 100644 journal-theme/docs/PHP-SECURITY-INTEGRATION.md create mode 100644 journal-theme/docs/PORTALS.adoc delete mode 100644 journal-theme/docs/PORTALS.md create mode 100644 journal-theme/docs/README.adoc delete mode 100644 journal-theme/docs/README.md create mode 100644 journal-theme/docs/contributing-philosophy.adoc delete mode 100644 journal-theme/docs/contributing-philosophy.md create mode 100644 journal-theme/docs/ethos.adoc delete mode 100644 journal-theme/docs/ethos.md create mode 100644 journal-theme/docs/spans.adoc delete mode 100644 journal-theme/docs/spans.md create mode 100644 journal-theme/docs/styles-guide.adoc delete mode 100644 journal-theme/docs/styles-guide.md create mode 100644 journal-theme/docs/taxonomy.adoc delete mode 100644 journal-theme/docs/taxonomy.md create mode 100644 journal-theme/entries/EXPLAINME.adoc delete mode 100644 journal-theme/entries/EXPLAINME.md create mode 100644 journal-theme/semantic/constructs/EXPLAINME.adoc delete mode 100644 journal-theme/semantic/constructs/EXPLAINME.md create mode 100644 journal-theme/semantic/glosses/EXPLAINME.adoc delete mode 100644 journal-theme/semantic/glosses/EXPLAINME.md create mode 100644 journal-theme/tests/aria-checklist.adoc delete mode 100644 journal-theme/tests/aria-checklist.md create mode 100644 journal-theme/tests/validator-links.adoc delete mode 100644 journal-theme/tests/validator-links.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 create mode 100644 plugin-conflict-mapper/.meta/REQUIRED-FILES.adoc delete mode 100644 plugin-conflict-mapper/.meta/REQUIRED-FILES.md rename praxis/ABI-FFI-README.md => plugin-conflict-mapper/ABI-FFI-README.adoc (74%) create mode 100644 plugin-conflict-mapper/CODE_OF_CONDUCT.adoc delete mode 100644 plugin-conflict-mapper/CODE_OF_CONDUCT.md delete mode 100644 plugin-conflict-mapper/CONTRIBUTING.md rename plugin-conflict-mapper/{DEVELOPER.md => DEVELOPER.adoc} (74%) delete mode 100644 plugin-conflict-mapper/MAINTAINERS.md create mode 100644 plugin-conflict-mapper/REVERSIBILITY.adoc delete mode 100644 plugin-conflict-mapper/REVERSIBILITY.md create mode 100644 plugin-conflict-mapper/RSR-COMPLIANCE.adoc delete mode 100644 plugin-conflict-mapper/RSR-COMPLIANCE.md create mode 100644 plugin-conflict-mapper/RSR-GOLD-PROGRESS.adoc delete mode 100644 plugin-conflict-mapper/RSR-GOLD-PROGRESS.md create mode 100644 plugin-conflict-mapper/SECURITY.adoc delete mode 100644 plugin-conflict-mapper/SECURITY.md create mode 100644 plugin-conflict-mapper/docs/SECURITY-INTEGRATION.adoc delete mode 100644 plugin-conflict-mapper/docs/SECURITY-INTEGRATION.md create mode 100644 plugin-conflict-mapper/index.adoc delete mode 100644 plugin-conflict-mapper/index.md rename secured/ABI-FFI-README.md => praxis/ABI-FFI-README.adoc (74%) create mode 100644 praxis/CODE_OF_CONDUCT.adoc delete mode 100644 praxis/CODE_OF_CONDUCT.md delete mode 100644 praxis/CONTRIBUTING.md create mode 100644 praxis/Core/cli-wrapper/README.adoc delete mode 100644 praxis/Core/cli-wrapper/README.md create mode 100644 praxis/Core/db-schema/IMPLEMENTATION_SUMMARY.adoc delete mode 100644 praxis/Core/db-schema/IMPLEMENTATION_SUMMARY.md rename praxis/Core/db-schema/{QUICKSTART.md => QUICKSTART.adoc} (72%) create mode 100644 praxis/Core/db-schema/README.adoc delete mode 100644 praxis/Core/db-schema/README.md rename praxis/Core/introspection/{README.md => README.adoc} (53%) create mode 100644 praxis/Core/introspection/docs/ARCHITECTURE.adoc delete mode 100644 praxis/Core/introspection/docs/ARCHITECTURE.md rename praxis/Core/introspection/docs/{EXAMPLES.md => EXAMPLES.adoc} (86%) rename praxis/Core/manifest-parser/{README.md => README.adoc} (51%) create mode 100644 praxis/Core/manifest-parser/docs/API.adoc delete mode 100644 praxis/Core/manifest-parser/docs/API.md create mode 100644 praxis/Core/manifest-parser/docs/MANIFEST_FORMAT.adoc delete mode 100644 praxis/Core/manifest-parser/docs/MANIFEST_FORMAT.md create mode 100644 praxis/DEPENDENCY_AUDIT.adoc delete mode 100644 praxis/DEPENDENCY_AUDIT.md create mode 100644 praxis/IMPLEMENTATION_SUMMARY.adoc delete mode 100644 praxis/IMPLEMENTATION_SUMMARY.md create mode 100644 praxis/INTEGRATION_STATUS.adoc delete mode 100644 praxis/INTEGRATION_STATUS.md delete mode 100644 praxis/MAINTAINERS.md create mode 100644 praxis/MANUAL_REVIEW_NEEDED.adoc delete mode 100644 praxis/MANUAL_REVIEW_NEEDED.md create mode 100644 praxis/REVERSIBILITY.adoc delete mode 100644 praxis/REVERSIBILITY.md create mode 100644 praxis/RHODIUM_PLATINUM_ROADMAP.adoc delete mode 100644 praxis/RHODIUM_PLATINUM_ROADMAP.md create mode 100644 praxis/RSR_COMPLIANCE.adoc delete mode 100644 praxis/RSR_COMPLIANCE.md create mode 100644 praxis/RSR_IMPLEMENTATION.adoc delete mode 100644 praxis/RSR_IMPLEMENTATION.md create mode 100644 praxis/SECURITY.adoc delete mode 100644 praxis/SECURITY.md create mode 100644 praxis/SymbolicEngine/core/README.adoc delete mode 100644 praxis/SymbolicEngine/core/README.md create mode 100644 praxis/SymbolicEngine/dashboard/README.adoc delete mode 100644 praxis/SymbolicEngine/dashboard/README.md rename praxis/SymbolicEngine/graphql/{README.md => README.adoc} (56%) rename praxis/SymbolicEngine/graphql/{SCHEMA_GUIDE.md => SCHEMA_GUIDE.adoc} (68%) rename praxis/SymbolicEngine/swarm/{README.md => README.adoc} (59%) rename praxis/engine/php/{README.md => README.adoc} (59%) create mode 100644 praxis/examples/EXAMPLES_SUMMARY.adoc delete mode 100644 praxis/examples/EXAMPLES_SUMMARY.md create mode 100644 praxis/examples/FAQ.adoc delete mode 100644 praxis/examples/FAQ.md create mode 100644 praxis/examples/QUICKSTART.adoc delete mode 100644 praxis/examples/QUICKSTART.md create mode 100644 praxis/examples/README.adoc delete mode 100644 praxis/examples/README.md create mode 100644 praxis/examples/TROUBLESHOOTING.adoc delete mode 100644 praxis/examples/TROUBLESHOOTING.md rename praxis/examples/demos/full-stack-demo/{README.md => README.adoc} (58%) rename praxis/examples/tutorials/01-getting-started/{README.md => README.adoc} (50%) create mode 100644 praxis/examples/tutorials/02-wordpress-integration/README.adoc delete mode 100644 praxis/examples/tutorials/02-wordpress-integration/README.md rename praxis/examples/tutorials/03-swarm-setup/{README.md => README.adoc} (73%) rename praxis/examples/tutorials/04-database-integration/{README.md => README.adoc} (68%) rename praxis/examples/tutorials/05-custom-symbols/{README.md => README.adoc} (79%) create mode 100644 praxis/examples/video-demo/DEMO_SCRIPT.adoc delete mode 100644 praxis/examples/video-demo/DEMO_SCRIPT.md create mode 100644 praxis/plugin/README.adoc delete mode 100644 praxis/plugin/README.md rename praxis/tests/{README.md => README.adoc} (52%) create mode 100644 praxis/wp_injector/IMPLEMENTATION.adoc delete mode 100644 praxis/wp_injector/IMPLEMENTATION.md create mode 100644 praxis/wp_injector/QUICKSTART.adoc delete mode 100644 praxis/wp_injector/QUICKSTART.md create mode 100644 praxis/wp_injector/README.adoc delete mode 100644 praxis/wp_injector/README.md create mode 100644 praxis/wp_praxis_core/FORMAL_VERIFICATION.adoc delete mode 100644 praxis/wp_praxis_core/FORMAL_VERIFICATION.md create mode 100644 project-wharf/CODE_OF_CONDUCT.adoc delete mode 100644 project-wharf/CODE_OF_CONDUCT.md delete mode 100644 project-wharf/CONTRIBUTING.md delete mode 100644 project-wharf/MAINTAINERS.md create mode 100644 project-wharf/REVERSIBILITY.adoc delete mode 100644 project-wharf/REVERSIBILITY.md create mode 100644 project-wharf/SECURITY.adoc delete mode 100644 project-wharf/SECURITY.md create mode 100644 project-wharf/TOPOLOGY.adoc delete mode 100644 project-wharf/TOPOLOGY.md rename project-wharf/docs/{ARCHITECTURE.md => ARCHITECTURE.adoc} (63%) rename resurrect/{ABI-FFI-README.md => ABI-FFI-README.adoc} (74%) create mode 100644 resurrect/CODE_OF_CONDUCT.adoc delete mode 100644 resurrect/CODE_OF_CONDUCT.md delete mode 100644 resurrect/CONTRIBUTING.md create mode 100644 resurrect/SECURITY.adoc delete mode 100644 resurrect/SECURITY.md rename plugin-conflict-mapper/ABI-FFI-README.md => secured/ABI-FFI-README.adoc (74%) create mode 100644 secured/CODE_OF_CONDUCT.adoc delete mode 100644 secured/CODE_OF_CONDUCT.md create mode 100644 secured/CONTRIBUTING.adoc delete mode 100644 secured/CONTRIBUTING.md delete mode 100644 secured/README.md create mode 100644 secured/SECURITY.adoc delete mode 100644 secured/SECURITY.md rename secured/{VERIFICATION-TESTS.md => VERIFICATION-TESTS.adoc} (59%) create mode 100644 secured/php-aegis/CODE_OF_CONDUCT.adoc delete mode 100644 secured/php-aegis/CODE_OF_CONDUCT.md create mode 100644 secured/php-aegis/COMPATIBILITY.adoc delete mode 100644 secured/php-aegis/COMPATIBILITY.md delete mode 100644 secured/php-aegis/CONTRIBUTING.md create mode 100644 secured/php-aegis/PHP_AEGIS_ANALYSIS_SUMMARY.adoc delete mode 100644 secured/php-aegis/PHP_AEGIS_ANALYSIS_SUMMARY.md create mode 100644 secured/php-aegis/POSITIONING.adoc delete mode 100644 secured/php-aegis/POSITIONING.md create mode 100644 secured/php-aegis/ROADMAP_PRIORITY.adoc delete mode 100644 secured/php-aegis/ROADMAP_PRIORITY.md create mode 100644 secured/php-aegis/SECURITY.adoc delete mode 100644 secured/php-aegis/SECURITY.md rename secured/php-aegis/docs/{CERRO-TORRE-INTEGRATION.md => CERRO-TORRE-INTEGRATION.adoc} (66%) create mode 100644 secured/php-aegis/docs/VALIDATION-PLAN.adoc delete mode 100644 secured/php-aegis/docs/VALIDATION-PLAN.md create mode 100644 secured/php-aegis/validation/README.adoc delete mode 100644 secured/php-aegis/validation/README.md create mode 100644 secured/php-aegis/validation/VALIDATION-REPORT.adoc delete mode 100644 secured/php-aegis/validation/VALIDATION-REPORT.md create mode 100644 sinople-theme/.meta/REQUIRED-FILES.adoc delete mode 100644 sinople-theme/.meta/REQUIRED-FILES.md create mode 100644 sinople-theme/ABI-FFI-README.adoc delete mode 100644 sinople-theme/ABI-FFI-README.md create mode 100644 sinople-theme/CODE_OF_CONDUCT.adoc delete mode 100644 sinople-theme/CODE_OF_CONDUCT.md delete mode 100644 sinople-theme/CONTRIBUTING.md create mode 100644 sinople-theme/CRYPTOGRAPHIC-INTEGRATION.adoc delete mode 100644 sinople-theme/CRYPTOGRAPHIC-INTEGRATION.md create mode 100644 sinople-theme/DOGFOODING-LESSONS.adoc delete mode 100644 sinople-theme/DOGFOODING-LESSONS.md delete mode 100644 sinople-theme/MAINTAINERS.md create mode 100644 sinople-theme/PROJECT_SUMMARY.adoc delete mode 100644 sinople-theme/PROJECT_SUMMARY.md create mode 100644 sinople-theme/RSR_AUDIT.adoc delete mode 100644 sinople-theme/RSR_AUDIT.md create mode 100644 sinople-theme/RSR_COMPLETION.adoc delete mode 100644 sinople-theme/RSR_COMPLETION.md create mode 100644 sinople-theme/SECURITY.adoc delete mode 100644 sinople-theme/SECURITY.md create mode 100644 sinople-theme/SECURITY_INTEGRATION.adoc delete mode 100644 sinople-theme/SECURITY_INTEGRATION.md create mode 100644 sinople-theme/STACK.adoc delete mode 100644 sinople-theme/STACK.md create mode 100644 sinople-theme/THEME-ENHANCEMENTS.adoc delete mode 100644 sinople-theme/THEME-ENHANCEMENTS.md rename sinople-theme/{THEME_TRANSPILATION_ARCHITECTURE.md => THEME_TRANSPILATION_ARCHITECTURE.adoc} (81%) create mode 100644 sinople-theme/TPCF.adoc delete mode 100644 sinople-theme/TPCF.md create mode 100644 sinople-theme/USAGE.adoc delete mode 100644 sinople-theme/USAGE.md create mode 100644 sinople-theme/wordpress/SECURITY_INTEGRATION.adoc delete mode 100644 sinople-theme/wordpress/SECURITY_INTEGRATION.md diff --git a/ARCHITECTURE.adoc b/ARCHITECTURE.adoc new file mode 100644 index 0000000..1c0a7a6 --- /dev/null +++ b/ARCHITECTURE.adoc @@ -0,0 +1,48 @@ +== Architecture + +=== Overview + +This repository follows a modular, maintainable architecture designed +for clarity, scalability, and long-term sustainability. + +=== Directory Structure + +.... +. +├── src/ # Source code +├── tests/ # Test suites +├── docs/ # Documentation +├── scripts/ # Utility scripts +├── config/ # Configuration files +├── LICENSE # License file +├── LICENSES/ # Full license texts +└── README.adoc # Project documentation +.... + +=== Design Principles + +* *Separation of Concerns*: Each module has a single responsibility +* *Testability*: Code is written to be easily testable +* *Documentation*: All public APIs are documented +* *Configuration*: Environment-specific settings are externalized + +=== Dependencies + +* External dependencies are minimized and clearly declared +* Version pinning is used for reproducibility + +=== Security Considerations + +* Sensitive data is never committed to the repository +* Secrets are managed through environment variables or secure vaults +* Regular dependency audits are performed + +=== Maintainability + +* Code follows consistent style guidelines +* Pull requests require review and CI checks +* Issues and discussions are tracked transparently + +''''' + +_Last updated: 2026-07-18_ diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md deleted file mode 100644 index 607e3d8..0000000 --- a/ARCHITECTURE.md +++ /dev/null @@ -1,47 +0,0 @@ -# Architecture - -## Overview - -This repository follows a modular, maintainable architecture designed for clarity, scalability, and long-term sustainability. - -## Directory Structure - -``` -. -├── src/ # Source code -├── tests/ # Test suites -├── docs/ # Documentation -├── scripts/ # Utility scripts -├── config/ # Configuration files -├── LICENSE # License file -├── LICENSES/ # Full license texts -└── README.adoc # Project documentation -``` - -## Design Principles - -- **Separation of Concerns**: Each module has a single responsibility -- **Testability**: Code is written to be easily testable -- **Documentation**: All public APIs are documented -- **Configuration**: Environment-specific settings are externalized - -## Dependencies - -- External dependencies are minimized and clearly declared -- Version pinning is used for reproducibility - -## Security Considerations - -- Sensitive data is never committed to the repository -- Secrets are managed through environment variables or secure vaults -- Regular dependency audits are performed - -## Maintainability - -- Code follows consistent style guidelines -- Pull requests require review and CI checks -- Issues and discussions are tracked transparently - ---- - -*Last updated: 2026-07-18* diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc new file mode 100644 index 0000000..e6e04ef --- /dev/null +++ b/CHANGELOG.adoc @@ -0,0 +1,75 @@ +== Changelog + +All notable changes to `+wordpress-tools+` will be documented in this +file. + +This file is generated from conventional commits by the +https://github.com/hyperpolymath/standards/blob/main/.github/workflows/changelog-reusable.yml[`+changelog-reusable.yml+`] +workflow (`+hyperpolymath/standards#206+`). Adopt the workflow in this +repo’s CI to keep this file in sync automatically — see +https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml[`+templates/cliff.toml+`] +for the canonical config. + +The format follows https://keepachangelog.com/en/1.1.0/[Keep a +Changelog]; this project aims to follow +https://semver.org/spec/v2.0.0.html[Semantic Versioning]. + +=== [Unreleased] + +==== Added + +* feat(crg): add crg-grade and crg-badge justfile recipes +* feat: add stapeln.toml container definition +* feat: add UX Justfile with doctor, tour, help-me, assail recipes +* feat: deploy UX Manifesto infrastructure +* feat: add CLADE.a2ml — clade taxonomy declaration +* feat: add mirror.yml workflow for GitLab/Bitbucket mirroring +* feat: consolidate 5 WordPress repos into wordpress-tools monorepo + +==== Fixed + +* fix(ci): sync hypatia-scan.yml to canonical (413: +env.HOME+Phase-2+SARIF) (#22) +* fix(ci): build Hypatia escript from repo root (estate dogfood drift) +* fix(ci): rsr-antipattern.yml duplicate heredoc (#19) +* fix: set correct Groove capability type (was: custom) +* fix(scorecard): enforce granular permissions and add fuzzing +placeholder +* fix(ci): Resolve workflow-linter self-matching and metadata issues +* fix: resolve panic-attack security findings in sinople theme +* fix: correct email jonathan.jewell → j.d.a.jewell +* fix: global AGPL-3.0-or-later → PMPL-1.0-or-later replacement +* fix: SPDX headers (AGPL→PMPL), email, author name + +==== Changed + +* refactor: migrate 6SCM → 6A2 (.scm → .a2ml format) + +==== Documentation + +* docs: record tech-debt audit findings (2026-05-26) (#28) +* docs(claude): add CLAUDE.md with Exemptions table (#17) +* docs: add TEST-NEEDS.md (CRG C) +* docs: add EXPLAINME.adoc — prove-it file backing README claims +* docs: add 0-AI-MANIFEST.a2ml (RSR compliance) + +==== CI + +* ci: fix nonexistent actions/upload-artifact SHA pin (#21) +* ci(antipattern): fix top-level dir matching + benchmarks/lsp/bench +filename allowlists (#16) +* ci(antipattern): TS check reads .claude/CLAUDE.md exemption table +(#15) +* ci(antipattern): broaden TS allowlist (cli/, mod.ts, lsp-server, +_vscode_, -*) (#14) +* ci(antipattern): allowlist legit TS bridge/adapter paths (#13) + +=== 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 2ef5d6d..0000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,69 +0,0 @@ - -# Changelog - -All notable changes to `wordpress-tools` will be documented in this file. - -This file is generated from conventional commits by the -[`changelog-reusable.yml`](https://github.com/hyperpolymath/standards/blob/main/.github/workflows/changelog-reusable.yml) -workflow (`hyperpolymath/standards#206`). Adopt the workflow in this repo's CI to keep this file in sync automatically — see -[`templates/cliff.toml`](https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml) -for the canonical config. - -The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); -this project aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - -## [Unreleased] - -### Added - -- feat(crg): add crg-grade and crg-badge justfile recipes -- feat: add stapeln.toml container definition -- feat: add UX Justfile with doctor, tour, help-me, assail recipes -- feat: deploy UX Manifesto infrastructure -- feat: add CLADE.a2ml — clade taxonomy declaration -- feat: add mirror.yml workflow for GitLab/Bitbucket mirroring -- feat: consolidate 5 WordPress repos into wordpress-tools monorepo - -### Fixed - -- fix(ci): sync hypatia-scan.yml to canonical (413: env.HOME+Phase-2+SARIF) (#22) -- fix(ci): build Hypatia escript from repo root (estate dogfood drift) -- fix(ci): rsr-antipattern.yml duplicate heredoc (#19) -- fix: set correct Groove capability type (was: custom) -- fix(scorecard): enforce granular permissions and add fuzzing placeholder -- fix(ci): Resolve workflow-linter self-matching and metadata issues -- fix: resolve panic-attack security findings in sinople theme -- fix: correct email jonathan.jewell → j.d.a.jewell -- fix: global AGPL-3.0-or-later → PMPL-1.0-or-later replacement -- fix: SPDX headers (AGPL→PMPL), email, author name - -### Changed - -- refactor: migrate 6SCM → 6A2 (.scm → .a2ml format) - -### Documentation - -- docs: record tech-debt audit findings (2026-05-26) (#28) -- docs(claude): add CLAUDE.md with Exemptions table (#17) -- docs: add TEST-NEEDS.md (CRG C) -- docs: add EXPLAINME.adoc — prove-it file backing README claims -- docs: add 0-AI-MANIFEST.a2ml (RSR compliance) - -### CI - -- ci: fix nonexistent actions/upload-artifact SHA pin (#21) -- ci(antipattern): fix top-level dir matching + benchmarks/lsp/bench filename allowlists (#16) -- ci(antipattern): TS check reads .claude/CLAUDE.md exemption table (#15) -- ci(antipattern): broaden TS allowlist (cli/, mod.ts, lsp-server, *vscode*, -*) (#14) -- ci(antipattern): allowlist legit TS bridge/adapter paths (#13) - -## 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..620de20 --- /dev/null +++ b/CODE_OF_CONDUCT.adoc @@ -0,0 +1,339 @@ +== Code of Conduct + +=== Our Pledge + +We as members, contributors, and leaders pledge to make participation in +language-bridges a harassment-free experience for everyone, regardless +of age, body size, visible or invisible disability, ethnicity, sex +characteristics, gender identity and expression, level of experience, +education, socio-economic status, nationality, personal appearance, +race, caste, colour, religion, or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, +welcoming, diverse, inclusive, and healthy community. + +We recognise that a thriving open source community requires +*psychological safety* — an environment where people can contribute, ask +questions, make mistakes, and learn without fear of ridicule or +retaliation. + +''''' + +=== Our Standards + +==== Expected Behaviour + +The following behaviours contribute to a positive environment: + +*Communication* - Using welcoming and inclusive language - Being +respectful of differing viewpoints and experiences - Giving and +gracefully accepting constructive feedback - Assuming good intent while +addressing impact - Communicating clearly and patiently, especially with +newcomers + +*Collaboration* - Focusing on what is best for the community - Showing +empathy and kindness toward other community members - Being +collaborative rather than competitive - Mentoring and supporting less +experienced contributors - Celebrating others’ contributions and +successes + +*Professionalism* - Accepting responsibility and apologising to those +affected by our mistakes - Learning from the experience and avoiding +repetition - Respecting others’ time and attention - Staying on topic in +project spaces - Following project guidelines and conventions + +*Accessibility* - Using plain language and avoiding unnecessary jargon - +Providing alt text for images and transcripts for audio/video - Being +patient with those using assistive technologies - Accommodating +different communication styles and needs - Recognising that not everyone +communicates the same way + +==== Unacceptable Behaviour + +The following behaviours are considered harassment and are unacceptable: + +*Harassment* - The use of sexualised language or imagery, and sexual +attention or advances of any kind - Trolling, insulting or derogatory +comments, and personal or political attacks - Public or private +harassment - Deliberate intimidation, stalking, or following (online or +in-person) - Unwelcome physical contact or simulated physical contact +(e.g., emoji) - Sustained disruption of talks, events, or online +discussions + +*Discrimination* - Discriminatory jokes and language - Posting or +threatening to post others’ personally identifying information +("`doxing`") - Advocating for, or encouraging, any of the above +behaviour - Microaggressions — subtle, often unintentional, +discriminatory comments or actions + +*Professional Misconduct* - Publishing others’ private information +without explicit permission - Misrepresenting affiliation or +contributions - Plagiarism or claiming credit for others’ work - +Retaliating against anyone who reports a Code of Conduct violation - +Other conduct which could reasonably be considered inappropriate in a +professional setting + +==== Grey Areas + +Some situations require judgement. When uncertain: + +* *Intent vs Impact*: Good intentions do not excuse harmful impact. +Focus on making things right. +* *Power Dynamics*: Those with more power (maintainers, employers, +experienced contributors) must be especially mindful of their impact. +* *Cultural Differences*: What’s acceptable varies by culture. When in +doubt, err on the side of caution and ask. +* *Humour*: Jokes at others’ expense are rarely funny to everyone. Punch +up, not down. + +''''' + +=== Scope + +This Code of Conduct applies within all community spaces, including: + +*Online Spaces* - Repository discussions, issues, and pull/merge +requests - Project chat channels (Matrix, Discord, Slack, IRC) - Mailing +lists and forums - Social media when representing the project - Video +calls and virtual meetings + +*In-Person Spaces* - Conferences, meetups, and events - Workshops and +training sessions - Any gathering where you represent the project + +*Representation* This Code of Conduct also applies when an individual is +officially representing the community in public spaces. Examples +include: + +* Using an official project email address +* Posting via an official social media account +* Acting as an appointed representative at an event +* Speaking on behalf of the project + +''''' + +=== Enforcement + +==== Reporting + +If you experience or witness unacceptable behaviour, or have any other +concerns, please report it as soon as possible. + +*How to Report* + +[width="99%",cols="30%,33%,37%",options="header",] +|=== +|Method |Details |Best For +|*Email* |\{\{CONDUCT_EMAIL}} |Detailed reports, sensitive matters + +|*Private Message* |Contact any maintainer directly |Quick questions, +minor issues + +|*Anonymous Form* |[Link to form if available] |When you need anonymity +|=== + +*What to Include* + +* Your contact information (unless anonymous) +* Names/usernames of those involved +* Description of what happened +* When and where it occurred +* Any witnesses +* Any supporting evidence (screenshots, links) +* How you would like us to respond (if you have a preference) + +*What Happens Next* + +[arabic] +. You will receive acknowledgment within *\{\{RESPONSE_TIME}}* +. The \{\{CONDUCT_TEAM}} will review the report +. We may ask for additional information +. We will determine appropriate action +. We will inform you of the outcome (respecting others’ privacy) + +==== Confidentiality + +All reports will be handled with discretion: + +* Reporter identity is protected by default +* Details are shared only with those who need to know +* We will ask before naming you in any communication +* Anonymous reports are accepted and investigated + +==== Conflicts of Interest + +If a \{\{CONDUCT_TEAM}} member is involved in an incident: + +* They will recuse themselves from the process +* Another maintainer or external party will handle the report +* We will disclose any potential conflicts + +''''' + +=== Enforcement Guidelines + +The \{\{CONDUCT_TEAM}} will follow these guidelines in determining +consequences: + +==== 1. Correction + +*Community Impact*: Use of inappropriate language or other behaviour +deemed unprofessional or unwelcome. + +*Consequence*: A private, written warning providing clarity around the +nature of the violation and an explanation of why the behaviour was +inappropriate. A public apology may be requested. + +*Duration*: Immediate + +==== 2. Warning + +*Community Impact*: A violation through a single incident or series of +actions. + +*Consequence*: A warning with consequences for continued behaviour. No +interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, for a specified period. This +includes avoiding interactions in community spaces as well as external +channels like social media. Violating these terms may lead to a +temporary or permanent ban. + +*Duration*: 1-4 weeks + +==== 3. Temporary Ban + +*Community Impact*: A serious violation of community standards, +including sustained inappropriate behaviour. + +*Consequence*: A temporary ban from any sort of interaction or public +communication with the community for a specified period. No public or +private interaction with the people involved, including unsolicited +interaction with those enforcing the Code of Conduct, is allowed during +this period. Violating these terms may lead to a permanent ban. + +*Duration*: 1-6 months + +==== 4. Permanent Ban + +*Community Impact*: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behaviour, harassment of an +individual, or aggression toward or disparagement of classes of +individuals. + +*Consequence*: A permanent ban from any sort of public interaction +within the community. + +*Duration*: Permanent (with appeal rights after 12 months) + +==== Enforcement Across Perimeters + +For contributors with elevated access (Perimeter 2 or 1): + +[cols=",",options="header",] +|=== +|Level |Additional Consequence +|Correction |Noted in contributor record +|Warning |Access privileges may be temporarily reduced +|Temporary Ban |Access reduced to Perimeter 3 for ban duration +|Permanent Ban |All access revoked +|=== + +''''' + +=== Appeals + +If you believe an enforcement decision was made in error: + +[arabic] +. *Wait 7 days* after the decision (cooling-off period) +. *Email* \{\{CONDUCT_EMAIL}} with subject line "`Appeal: [Original +Report ID]`" +. *Explain* why you believe the decision should be reconsidered +. *Provide* any new information not previously available + +*Appeals Process* + +* Appeals are reviewed by a different \{\{CONDUCT_TEAM}} member than the +original +* You will receive a response within 14 days +* The appeals decision is final +* You may only appeal once per incident + +*Grounds for Appeal* + +* Procedural errors in the original investigation +* New evidence not previously available +* Disproportionate response to the violation +* Misunderstanding of facts + +''''' + +=== Supporting Those Who Report + +We are committed to supporting those who report violations: + +*We Will* - Believe and take all reports seriously - Respect your +privacy and confidentiality preferences - Keep you informed of progress +(if you wish) - Take steps to protect you from retaliation - Provide +resources if you need support + +*We Will Not* - Require you to confront the person directly - Dismiss +reports without investigation - Reveal your identity without consent - +Tolerate retaliation against reporters - Rush you to make decisions + +''''' + +=== Prevention + +Beyond enforcement, we actively work to prevent issues: + +*Onboarding* - All contributors are expected to read this Code of +Conduct - Perimeter 2 applicants must confirm they’ve read and +understood it - Maintainers receive additional training on enforcement + +*Culture* - We model the behaviour we expect - We intervene early when +we see potential issues - We thank people for positive contributions - +We create opportunities for diverse voices + +*Review* - This Code of Conduct is reviewed annually - Community +feedback is welcomed - Changes are communicated clearly + +''''' + +=== Acknowledgments + +This Code of Conduct is adapted from: + +* https://www.contributor-covenant.org/[Contributor Covenant], version +2.1 +* https://www.djangoproject.com/conduct/[Django Code of Conduct] +* https://www.rust-lang.org/policies/code-of-conduct[Rust Code of +Conduct] +* https://www.python.org/psf/conduct/[Python Community Code of Conduct] + +We thank these communities for their leadership in creating welcoming +spaces. + +''''' + +=== Questions? + +If you have questions about this Code of Conduct: + +* Open a +https://github.com/hyperpolymath/language-bridges/discussions[Discussion] +(for general questions) +* Email \{\{CONDUCT_EMAIL}} (for private questions) +* Contact any maintainer directly + +''''' + +=== Summary + +*Be kind. Be respectful. Be collaborative.* + +We’re all here because we care about this project. Let’s make it a place +where everyone can do their best work. + +''''' + +Last updated: 2026 · Based on Contributor Covenant 2.1 diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md deleted file mode 100644 index ea1ea6c..0000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,331 +0,0 @@ - -# Code of Conduct - - - -## Our Pledge - -We as members, contributors, and leaders pledge to make participation in language-bridges a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, colour, religion, or sexual identity and orientation. - -We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. - -We recognise that a thriving open source community requires **psychological safety** — an environment where people can contribute, ask questions, make mistakes, and learn without fear of ridicule or retaliation. - ---- - -## Our Standards - -### Expected Behaviour - -The following behaviours contribute to a positive environment: - -**Communication** -- Using welcoming and inclusive language -- Being respectful of differing viewpoints and experiences -- Giving and gracefully accepting constructive feedback -- Assuming good intent while addressing impact -- Communicating clearly and patiently, especially with newcomers - -**Collaboration** -- Focusing on what is best for the community -- Showing empathy and kindness toward other community members -- Being collaborative rather than competitive -- Mentoring and supporting less experienced contributors -- Celebrating others' contributions and successes - -**Professionalism** -- Accepting responsibility and apologising to those affected by our mistakes -- Learning from the experience and avoiding repetition -- Respecting others' time and attention -- Staying on topic in project spaces -- Following project guidelines and conventions - -**Accessibility** -- Using plain language and avoiding unnecessary jargon -- Providing alt text for images and transcripts for audio/video -- Being patient with those using assistive technologies -- Accommodating different communication styles and needs -- Recognising that not everyone communicates the same way - -### Unacceptable Behaviour - -The following behaviours are considered harassment and are unacceptable: - -**Harassment** -- The use of sexualised language or imagery, and sexual attention or advances of any kind -- Trolling, insulting or derogatory comments, and personal or political attacks -- Public or private harassment -- Deliberate intimidation, stalking, or following (online or in-person) -- Unwelcome physical contact or simulated physical contact (e.g., emoji) -- Sustained disruption of talks, events, or online discussions - -**Discrimination** -- Discriminatory jokes and language -- Posting or threatening to post others' personally identifying information ("doxing") -- Advocating for, or encouraging, any of the above behaviour -- Microaggressions — subtle, often unintentional, discriminatory comments or actions - -**Professional Misconduct** -- Publishing others' private information without explicit permission -- Misrepresenting affiliation or contributions -- Plagiarism or claiming credit for others' work -- Retaliating against anyone who reports a Code of Conduct violation -- Other conduct which could reasonably be considered inappropriate in a professional setting - -### Grey Areas - -Some situations require judgement. When uncertain: - -- **Intent vs Impact**: Good intentions do not excuse harmful impact. Focus on making things right. -- **Power Dynamics**: Those with more power (maintainers, employers, experienced contributors) must be especially mindful of their impact. -- **Cultural Differences**: What's acceptable varies by culture. When in doubt, err on the side of caution and ask. -- **Humour**: Jokes at others' expense are rarely funny to everyone. Punch up, not down. - ---- - -## Scope - -This Code of Conduct applies within all community spaces, including: - -**Online Spaces** -- Repository discussions, issues, and pull/merge requests -- Project chat channels (Matrix, Discord, Slack, IRC) -- Mailing lists and forums -- Social media when representing the project -- Video calls and virtual meetings - -**In-Person Spaces** -- Conferences, meetups, and events -- Workshops and training sessions -- Any gathering where you represent the project - -**Representation** -This Code of Conduct also applies when an individual is officially representing the community in public spaces. Examples include: - -- Using an official project email address -- Posting via an official social media account -- Acting as an appointed representative at an event -- Speaking on behalf of the project - ---- - -## Enforcement - -### Reporting - -If you experience or witness unacceptable behaviour, or have any other concerns, please report it as soon as possible. - -**How to Report** - -| Method | Details | Best For | -|--------|---------|----------| -| **Email** | {{CONDUCT_EMAIL}} | Detailed reports, sensitive matters | -| **Private Message** | Contact any maintainer directly | Quick questions, minor issues | -| **Anonymous Form** | [Link to form if available] | When you need anonymity | - -**What to Include** - -- Your contact information (unless anonymous) -- Names/usernames of those involved -- Description of what happened -- When and where it occurred -- Any witnesses -- Any supporting evidence (screenshots, links) -- How you would like us to respond (if you have a preference) - -**What Happens Next** - -1. You will receive acknowledgment within **{{RESPONSE_TIME}}** -2. The {{CONDUCT_TEAM}} will review the report -3. We may ask for additional information -4. We will determine appropriate action -5. We will inform you of the outcome (respecting others' privacy) - -### Confidentiality - -All reports will be handled with discretion: - -- Reporter identity is protected by default -- Details are shared only with those who need to know -- We will ask before naming you in any communication -- Anonymous reports are accepted and investigated - -### Conflicts of Interest - -If a {{CONDUCT_TEAM}} member is involved in an incident: - -- They will recuse themselves from the process -- Another maintainer or external party will handle the report -- We will disclose any potential conflicts - ---- - -## Enforcement Guidelines - -The {{CONDUCT_TEAM}} will follow these guidelines in determining consequences: - -### 1. Correction - -**Community Impact**: Use of inappropriate language or other behaviour deemed unprofessional or unwelcome. - -**Consequence**: A private, written warning providing clarity around the nature of the violation and an explanation of why the behaviour was inappropriate. A public apology may be requested. - -**Duration**: Immediate - -### 2. Warning - -**Community Impact**: A violation through a single incident or series of actions. - -**Consequence**: A warning with consequences for continued behaviour. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban. - -**Duration**: 1-4 weeks - -### 3. Temporary Ban - -**Community Impact**: A serious violation of community standards, including sustained inappropriate behaviour. - -**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban. - -**Duration**: 1-6 months - -### 4. Permanent Ban - -**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behaviour, harassment of an individual, or aggression toward or disparagement of classes of individuals. - -**Consequence**: A permanent ban from any sort of public interaction within the community. - -**Duration**: Permanent (with appeal rights after 12 months) - -### Enforcement Across Perimeters - -For contributors with elevated access (Perimeter 2 or 1): - -| Level | Additional Consequence | -|-------|----------------------| -| Correction | Noted in contributor record | -| Warning | Access privileges may be temporarily reduced | -| Temporary Ban | Access reduced to Perimeter 3 for ban duration | -| Permanent Ban | All access revoked | - ---- - -## Appeals - -If you believe an enforcement decision was made in error: - -1. **Wait 7 days** after the decision (cooling-off period) -2. **Email** {{CONDUCT_EMAIL}} with subject line "Appeal: [Original Report ID]" -3. **Explain** why you believe the decision should be reconsidered -4. **Provide** any new information not previously available - -**Appeals Process** - -- Appeals are reviewed by a different {{CONDUCT_TEAM}} member than the original -- You will receive a response within 14 days -- The appeals decision is final -- You may only appeal once per incident - -**Grounds for Appeal** - -- Procedural errors in the original investigation -- New evidence not previously available -- Disproportionate response to the violation -- Misunderstanding of facts - ---- - -## Supporting Those Who Report - -We are committed to supporting those who report violations: - -**We Will** -- Believe and take all reports seriously -- Respect your privacy and confidentiality preferences -- Keep you informed of progress (if you wish) -- Take steps to protect you from retaliation -- Provide resources if you need support - -**We Will Not** -- Require you to confront the person directly -- Dismiss reports without investigation -- Reveal your identity without consent -- Tolerate retaliation against reporters -- Rush you to make decisions - ---- - -## Prevention - -Beyond enforcement, we actively work to prevent issues: - -**Onboarding** -- All contributors are expected to read this Code of Conduct -- Perimeter 2 applicants must confirm they've read and understood it -- Maintainers receive additional training on enforcement - -**Culture** -- We model the behaviour we expect -- We intervene early when we see potential issues -- We thank people for positive contributions -- We create opportunities for diverse voices - -**Review** -- This Code of Conduct is reviewed annually -- Community feedback is welcomed -- Changes are communicated clearly - ---- - -## Acknowledgments - -This Code of Conduct is adapted from: - -- [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1 -- [Django Code of Conduct](https://www.djangoproject.com/conduct/) -- [Rust Code of Conduct](https://www.rust-lang.org/policies/code-of-conduct) -- [Python Community Code of Conduct](https://www.python.org/psf/conduct/) - -We thank these communities for their leadership in creating welcoming spaces. - ---- - -## Questions? - -If you have questions about this Code of Conduct: - -- Open a [Discussion](https://github.com/hyperpolymath/language-bridges/discussions) (for general questions) -- Email {{CONDUCT_EMAIL}} (for private questions) -- Contact any maintainer directly - ---- - -## Summary - -**Be kind. Be respectful. Be collaborative.** - -We're all here because we care about this project. Let's make it a place where everyone can do their best work. - ---- - -Last updated: 2026 · Based on Contributor Covenant 2.1 diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc new file mode 100644 index 0000000..837244d --- /dev/null +++ b/CONTRIBUTING.adoc @@ -0,0 +1,109 @@ +== Clone the repository + +git clone https://github.com/hyperpolymath/language-bridges.git cd +language-bridges + +== Using Nix (recommended for reproducibility) + +nix develop + +== Or using toolbox/distrobox + +toolbox create language-bridges-dev toolbox enter language-bridges-dev # +Install dependencies manually + +== Verify setup + +just check # or: cargo check / mix compile / etc. just test # Run test +suite + +.... + +### Repository Structure +.... + +language-bridges/ ├── 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/language-bridges/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://github.com/hyperpolymath/language-bridges/labels/help%20wanted) — Community help needed +- [`documentation`](https://github.com/hyperpolymath/language-bridges/labels/documentation) — Docs improvements +- [`perimeter-3`](https://github.com/hyperpolymath/language-bridges/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 f0b9d94..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,120 +0,0 @@ - -# Clone the repository -git clone https://github.com/hyperpolymath/language-bridges.git -cd language-bridges - -# Using Nix (recommended for reproducibility) -nix develop - -# Or using toolbox/distrobox -toolbox create language-bridges-dev -toolbox enter language-bridges-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure -``` -language-bridges/ -├── 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/language-bridges/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://github.com/hyperpolymath/language-bridges/labels/help%20wanted) — Community help needed -- [`documentation`](https://github.com/hyperpolymath/language-bridges/labels/documentation) — Docs improvements -- [`perimeter-3`](https://github.com/hyperpolymath/language-bridges/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 index e41020d..9b836fb 100644 --- a/GOVERNANCE.adoc +++ b/GOVERNANCE.adoc @@ -1,162 +1,60 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell -= Governance Model -:toc: preamble +== Governance -This document describes the governance model for this repository. +=== Overview -== Overview +This project is governed by the following principles and structures to +ensure transparent, inclusive, and effective decision-making. -This repository follows a **Sole Maintainer Governance Model**: +=== Roles and Responsibilities -* Single maintainer (@hyperpolymath) has full authority over the project -* All contributions are welcome and reviewed by the maintainer -* Decisions are made transparently through GitHub issues and discussions -* The project adheres to the hyperpolymath estate policies where applicable +==== Maintainers -== Core Principles +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 -[cols="1,2"] -|=== -| Principle | Description +==== Contributors -| **Benevolent Dictatorship** | Maintainer has final decision authority but seeks community input +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 -| **Meritocracy** | Contributions are judged on technical merit, not contributor identity +=== Decision Making -| **Transparency** | All significant decisions are documented publicly +==== Minor Changes -| **Consensus-Seeking** | Maintainer prefers consensus but will decide when necessary +* Can be made by any maintainer +* Include bug fixes, documentation updates, dependency updates -| **Open Contribution** | Anyone can contribute via fork and pull request +==== Major Changes -|=== +* Require discussion in issues or pull requests +* Include new features, architectural changes, API changes +* Need approval from at least 2 maintainers -== Roles and Permissions +==== Breaking Changes -[cols="1,2,2"] -|=== -| Role | Permissions | Assignment +* Require RFC (Request for Comments) process +* Need approval from majority of maintainers +* Must include migration guide -| **Maintainer** | Write access, merge rights, admin | @hyperpolymath -| **Contributors** | Read access, fork, submit PRs | All GitHub users -| **Users** | Use the software, report issues | All GitHub users +=== Code of Conduct -|=== +All participants are expected to follow our Code of Conduct. Violations +can be reported to the maintainers. -== Decision Making Framework +=== Communication -=== Routine Decisions +* *Issues*: For bug reports and feature requests +* *Discussions*: For questions and general discussion +* *Pull Requests*: For code contributions -* Bug fixes -* Documentation improvements -* Minor feature additions -* Dependency updates +=== Licensing -**Process**: Maintainer reviews and merges PRs that meet quality standards. +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. -=== Significant Changes +''''' -* New major features -* API changes -* Architecture modifications -* Breaking changes - -**Process**: -. Open issue describing the change -. Discuss with community (minimum 72 hours) -. Maintainer makes final decision -. Document rationale in issue/PR - -=== Structural Decisions - -* Repository purpose/renaming -* License changes -* Ownership transfer -* Deprecation/archival - -**Process**: -. Extended discussion (minimum 1 week) -. Maintainer makes final decision -. Document in CHANGELOG and governance docs - -== Contribution Lifecycle - -[cols="1,2"] -|=== -| Stage | Process - -| **Ideation** | Open issue, discuss feasibility - -| **Development** | Fork, implement, test thoroughly - -| **Review** | Submit PR, maintainer reviews within 7 days - -| **Merge** | Maintainer merges or requests changes - -| **Release** | Maintainer publishes according to project conventions - -|=== - -== Conflict Resolution - -In case of disagreements: - -. Discuss in the relevant GitHub issue or PR -. Provide technical justification for positions -. Maintainer mediates and makes final decision -. Decision is documented and can be revisited later - -== Project Policies - -This repository adheres to hyperpolymath estate-wide policies: - -* **License**: MPL-2.0 for code, CC-BY-SA-4.0 for prose (per standards/LICENCE-POLICY.adoc) -* **Code of Conduct**: Follows hyperpolymath CODE_OF_CONDUCT.md -* **Security**: Follows hyperpolymath SECURITY.md -* **Contributing**: Follows hyperpolymath CONTRIBUTING.adoc conventions - -== Repository-Specific Conventions - -[cols="1,2"] -|=== -| Convention | Description - -| **Signing** | All commits must be signed (SSH or GPG) - -| **SPDX Headers** | All source files must have SPDX license identifiers - -| **Contractiles** | Mustfile, Trustfile, Intendfile, Adjustfile in root - -| **Machine Readable** | META.a2ml in .machine_readable/6a2/ - -| **CI/CD** | GitHub Actions workflows in .github/workflows/ - -|=== - -== Governance Evolution - -As the project grows, this governance model may evolve: - -* **Adding Co-Maintainers**: When contribution volume warrants it -* **Forming a Team**: For complex multi-maintainer projects -* **Adopting TPCF**: For large, multi-repository projects (see rhodium-standard-repositories) - -Changes to this document require the same process as Significant Changes above. - -== See Also - -* link:MAINTAINERS.adoc[Maintainers] -* link:CODE_OF_CONDUCT.md[Code of Conduct] -* link:CONTRIBUTING.adoc[Contributing Guide] -* link:https://github.com/hyperpolymath/standards/blob/main/LICENCE-POLICY.adoc[Estate License Policy] -* link:https://github.com/hyperpolymath/standards[rhodium-standard-repositories (TPCF)] - -== Changelog - -[cols="1,1,1"] -|=== -| Date | Change | By - -| 2026-06-07 | Initial governance model established | @hyperpolymath -|=== +_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..7d5132f --- /dev/null +++ b/PROOF-NEEDS.adoc @@ -0,0 +1,12 @@ +== 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 +\{\{PROJECT}}/\{\{AUTHOR}} 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 fd95f90..0000000 --- a/PROOF-NEEDS.md +++ /dev/null @@ -1,14 +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 {{PROJECT}}/{{AUTHOR}} 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/SECURITY.adoc b/SECURITY.adoc new file mode 100644 index 0000000..d9d9cae --- /dev/null +++ b/SECURITY.adoc @@ -0,0 +1,452 @@ +== Security Policy + +We take security seriously. We appreciate your efforts to responsibly +disclose vulnerabilities and will make every effort to acknowledge your +contributions. + +=== Table of Contents + +* link:#reporting-a-vulnerability[Reporting a Vulnerability] +* link:#what-to-include[What to Include] +* link:#response-timeline[Response Timeline] +* link:#disclosure-policy[Disclosure Policy] +* link:#scope[Scope] +* link:#safe-harbour[Safe Harbour] +* link:#recognition[Recognition] +* link:#security-updates[Security Updates] +* link:#security-best-practices[Security Best Practices] + +''''' + +=== Reporting a Vulnerability + +==== Preferred Method: GitHub Security Advisories + +The preferred method for reporting security vulnerabilities is through +GitHub’s Security Advisory feature: + +[arabic] +. Navigate to +https://github.com/hyperpolymath/language-bridges/security/advisories/new[Report +a Vulnerability] +. Click *"`Report a vulnerability`"* +. Complete the form with as much detail as possible +. Submit — we’ll receive a private notification + +This method ensures: + +* End-to-end encryption of your report +* Private discussion space for collaboration +* Coordinated disclosure tooling +* Automatic credit when the advisory is published + +==== Alternative: Encrypted Email + +If you cannot use GitHub Security Advisories, you may email us directly: + +[width="100%",cols="50%,50%",] +|=== +|*Email* |j.d.a.jewell@open.ac.uk +|*PGP Key* |https://hyperpolymath.github.io/pgp.asc[Download Public Key] +|*Fingerprint* |`+TBD+` +|=== + +[source,bash] +---- +# Import our PGP key +curl -sSL https://hyperpolymath.github.io/pgp.asc | gpg --import + +# Verify fingerprint +gpg --fingerprint j.d.a.jewell@open.ac.uk + +# Encrypt your report +gpg --armor --encrypt --recipient j.d.a.jewell@open.ac.uk report.txt +---- + +____ +*⚠️ Important:* Do not report security vulnerabilities through public +GitHub issues, pull requests, discussions, or social media. +____ + +''''' + +=== What to Include + +A good vulnerability report helps us understand and reproduce the issue +quickly. + +==== Required Information + +* *Description*: Clear explanation of the vulnerability +* *Impact*: What an attacker could achieve (confidentiality, integrity, +availability) +* *Affected versions*: Which versions/commits are affected +* *Reproduction steps*: Detailed steps to reproduce the issue + +==== Helpful Additional Information + +* *Proof of concept*: Code, scripts, or screenshots demonstrating the +vulnerability +* *Attack scenario*: Realistic attack scenario showing exploitability +* *CVSS score*: Your assessment of severity (use +https://www.first.org/cvss/calculator/3.1[CVSS 3.1 Calculator]) +* *CWE ID*: Common Weakness Enumeration identifier if known +* *Suggested fix*: If you have ideas for remediation +* *References*: Links to related vulnerabilities, research, or +advisories + +==== Example Report Structure + +[source,markdown] +---- +## Summary +[One-sentence description of the vulnerability] + +## Vulnerability Type +[e.g., SQL Injection, XSS, SSRF, Path Traversal, etc.] + +## Affected Component +[File path, function name, API endpoint, etc.] + +## Affected Versions +[Version range or specific commits] + +## Severity Assessment +- CVSS 3.1 Score: [X.X] +- CVSS Vector: [CVSS:3.1/AV:X/AC:X/PR:X/UI:X/S:X/C:X/I:X/A:X] + +## Description +[Detailed technical description] + +## Steps to Reproduce +1. [First step] +2. [Second step] +3. [...] + +## Proof of Concept +[Code, curl commands, screenshots, etc.] + +## Impact +[What can an attacker achieve?] + +## Suggested Remediation +[Optional: your ideas for fixing] + +## References +[Links to related issues, CVEs, research] +---- + +''''' + +=== Response Timeline + +We commit to the following response times: + +[width="100%",cols="24%,35%,41%",options="header",] +|=== +|Stage |Timeframe |Description +|*Initial Response* |48 hours |We acknowledge receipt and confirm we’re +investigating + +|*Triage* |7 days |We assess severity, confirm the vulnerability, and +estimate timeline + +|*Status Update* |Every 7 days |Regular updates on remediation progress + +|*Resolution* |90 days |Target for fix development and release (complex +issues may take longer) + +|*Disclosure* |90 days |Public disclosure after fix is available +(coordinated with you) +|=== + +____ +*Note:* These are targets, not guarantees. Complex vulnerabilities may +require more time. We’ll communicate openly about any delays. +____ + +''''' + +=== Disclosure Policy + +We follow *coordinated disclosure* (also known as responsible +disclosure): + +[arabic] +. *You report* the vulnerability privately +. *We acknowledge* and begin investigation +. *We develop* a fix and prepare a release +. *We coordinate* disclosure timing with you +. *We publish* security advisory and fix simultaneously +. *You may publish* your research after disclosure + +==== Our Commitments + +* We will not take legal action against researchers who follow this +policy +* We will work with you to understand and resolve the issue +* We will credit you in the security advisory (unless you prefer +anonymity) +* We will notify you before public disclosure +* We will publish advisories with sufficient detail for users to assess +risk + +==== Your Commitments + +* Report vulnerabilities promptly after discovery +* Give us reasonable time to address the issue before disclosure +* Do not access, modify, or delete data beyond what’s necessary to +demonstrate the vulnerability +* Do not degrade service availability (no DoS testing on production) +* Do not share vulnerability details with others until coordinated +disclosure + +==== Disclosure Timeline + +.... +Day 0 You report vulnerability +Day 1-2 We acknowledge receipt +Day 7 We confirm vulnerability and share initial assessment +Day 7-90 We develop and test fix +Day 90 Coordinated public disclosure + (earlier if fix is ready; later by mutual agreement) +.... + +If we cannot reach agreement on disclosure timing, we default to 90 days +from your initial report. + +''''' + +=== Scope + +==== In Scope ✅ + +The following are within scope for security research: + +* This repository (`+hyperpolymath/language-bridges+`) and all its code +* Official releases and packages published from this repository +* Documentation that could lead to security issues +* Build and deployment configurations in this repository +* Dependencies (report here, we’ll coordinate with upstream) + +==== Out of Scope ❌ + +The following are *not* in scope: + +* Third-party services we integrate with (report directly to them) +* Social engineering attacks against maintainers +* Physical security +* Denial of service attacks against production infrastructure +* Spam, phishing, or other non-technical attacks +* Issues already reported or publicly known +* Theoretical vulnerabilities without proof of concept + +==== Qualifying Vulnerabilities + +We’re particularly interested in: + +* Remote code execution +* SQL injection, command injection, code injection +* Authentication/authorisation bypass +* Cross-site scripting (XSS) and cross-site request forgery (CSRF) +* Server-side request forgery (SSRF) +* Path traversal / local file inclusion +* Information disclosure (credentials, PII, secrets) +* Cryptographic weaknesses +* Deserialisation vulnerabilities +* Memory safety issues (buffer overflows, use-after-free, etc.) +* Supply chain vulnerabilities (dependency confusion, etc.) +* Significant logic flaws + +==== Non-Qualifying Issues + +The following generally do not qualify as security vulnerabilities: + +* Missing security headers on non-sensitive pages +* Clickjacking on pages without sensitive actions +* Self-XSS (requires victim to paste code) +* Missing rate limiting (unless it enables a specific attack) +* Username/email enumeration (unless high-risk context) +* Missing cookie flags on non-sensitive cookies +* Software version disclosure +* Verbose error messages (unless exposing secrets) +* Best practice deviations without demonstrable impact + +''''' + +=== Safe Harbour + +We support security research conducted in good faith. + +==== Our Promise + +If you conduct security research in accordance with this policy: + +* ✅ We will not initiate legal action against you +* ✅ We will not report your activity to law enforcement +* ✅ We will work with you in good faith to resolve issues +* ✅ We consider your research authorised under the Computer Fraud and +Abuse Act (CFAA), UK Computer Misuse Act, and similar laws +* ✅ We waive any potential claim against you for circumvention of +security controls + +==== Good Faith Requirements + +To qualify for safe harbour, you must: + +* Comply with this security policy +* Report vulnerabilities promptly +* Avoid privacy violations (do not access others’ data) +* Avoid service degradation (no destructive testing) +* Not exploit vulnerabilities beyond proof-of-concept +* Not use vulnerabilities for profit (beyond bug bounties where offered) + +____ +*⚠️ Important:* This safe harbour does not extend to third-party +systems. Always check their policies before testing. +____ + +''''' + +=== Recognition + +We believe in recognising security researchers who help us improve. + +==== Hall of Fame + +Researchers who report valid vulnerabilities will be acknowledged in our +link:SECURITY-ACKNOWLEDGMENTS.md[Security Acknowledgments] (unless they +prefer anonymity). + +Recognition includes: + +* Your name (or chosen alias) +* Link to your website/profile (optional) +* Brief description of the vulnerability class +* Date of report + +==== What We Offer + +* ✅ Public credit in security advisories +* ✅ Acknowledgment in release notes +* ✅ Entry in our Hall of Fame +* ✅ Reference/recommendation letter upon request (for significant +findings) + +==== What We Don’t Currently Offer + +* ❌ Monetary bug bounties +* ❌ Hardware or swag +* ❌ Paid security research contracts + +____ +*Note:* We’re a community project with limited resources. Your +contributions help everyone who uses this software. +____ + +''''' + +=== Security Updates + +==== Receiving Updates + +To stay informed about security updates: + +* *Watch this repository*: Click "`Watch`" → "`Custom`" → Select +"`Security alerts`" +* *GitHub Security Advisories*: Published at +https://github.com/hyperpolymath/language-bridges/security/advisories[Security +Advisories] +* *Release notes*: Security fixes noted in link:CHANGELOG.md[CHANGELOG] + +==== Update Policy + +[cols=",",options="header",] +|=== +|Severity |Response +|*Critical/High* |Patch release as soon as fix is ready +|*Medium* |Included in next scheduled release (or earlier) +|*Low* |Included in next scheduled release +|=== + +==== Supported Versions + +[cols=",,",options="header",] +|=== +|Version |Supported |Notes +|`+main+` branch |✅ Yes |Latest development +|Latest release |✅ Yes |Current stable +|Previous minor release |✅ Yes |Security fixes backported +|Older versions |❌ No |Please upgrade +|=== + +''''' + +=== Security Best Practices + +When using language-bridges, we recommend: + +==== General + +* Keep dependencies up to date +* Use the latest stable release +* Subscribe to security notifications +* Review configuration against security documentation +* Follow principle of least privilege + +==== For Contributors + +* Never commit secrets, credentials, or API keys +* Use signed commits (`+git config commit.gpgsign true+`) +* Review dependencies before adding them +* Run security linters locally before pushing +* Report any concerns about existing code + +''''' + +=== Additional Resources + +* https://hyperpolymath.github.io/pgp.asc[Our PGP Public Key] +* https://github.com/hyperpolymath/language-bridges/security/advisories[Security +Advisories] +* link:CHANGELOG.md[Changelog] +* link:CONTRIBUTING.md[Contributing Guidelines] +* https://cve.mitre.org/[CVE Database] +* https://www.first.org/cvss/calculator/3.1[CVSS Calculator] + +''''' + +=== Contact + +[width="100%",cols="50%,50%",options="header",] +|=== +|Purpose |Contact +|*Security issues* +|https://github.com/hyperpolymath/language-bridges/security/advisories/new[Report +via GitHub] or j.d.a.jewell@open.ac.uk + +|*General questions* +|https://github.com/hyperpolymath/language-bridges/discussions[GitHub +Discussions] + +|*Other enquiries* |See link:README.md[README] for contact information +|=== + +''''' + +=== Policy Changes + +This security policy may be updated from time to time. Significant +changes will be: + +* Committed to this repository with a clear commit message +* Noted in the changelog +* Announced via GitHub Discussions (for major changes) + +''''' + +_Thank you for helping keep language-bridges and its users safe._ 🛡️ + +''''' + +Last updated: 2026 · Policy version: 1.0.0 diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index 36f61d2..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,410 +0,0 @@ - -# Security Policy - - - -We take security seriously. We appreciate your efforts to responsibly disclose vulnerabilities and will make every effort to acknowledge your contributions. - -## Table of Contents - -- [Reporting a Vulnerability](#reporting-a-vulnerability) -- [What to Include](#what-to-include) -- [Response Timeline](#response-timeline) -- [Disclosure Policy](#disclosure-policy) -- [Scope](#scope) -- [Safe Harbour](#safe-harbour) -- [Recognition](#recognition) -- [Security Updates](#security-updates) -- [Security Best Practices](#security-best-practices) - ---- - -## Reporting a Vulnerability - -### Preferred Method: GitHub Security Advisories - -The preferred method for reporting security vulnerabilities is through GitHub's Security Advisory feature: - -1. Navigate to [Report a Vulnerability](https://github.com/hyperpolymath/language-bridges/security/advisories/new) -2. Click **"Report a vulnerability"** -3. Complete the form with as much detail as possible -4. Submit — we'll receive a private notification - -This method ensures: - -- End-to-end encryption of your report -- Private discussion space for collaboration -- Coordinated disclosure tooling -- Automatic credit when the advisory is published - -### Alternative: Encrypted Email - -If you cannot use GitHub Security Advisories, you may email us directly: - -| | | -|---|---| -| **Email** | j.d.a.jewell@open.ac.uk | -| **PGP Key** | [Download Public Key](https://hyperpolymath.github.io/pgp.asc) | -| **Fingerprint** | `TBD` | - -```bash -# Import our PGP key -curl -sSL https://hyperpolymath.github.io/pgp.asc | gpg --import - -# Verify fingerprint -gpg --fingerprint j.d.a.jewell@open.ac.uk - -# Encrypt your report -gpg --armor --encrypt --recipient j.d.a.jewell@open.ac.uk report.txt -``` - -> **⚠️ Important:** Do not report security vulnerabilities through public GitHub issues, pull requests, discussions, or social media. - ---- - -## What to Include - -A good vulnerability report helps us understand and reproduce the issue quickly. - -### Required Information - -- **Description**: Clear explanation of the vulnerability -- **Impact**: What an attacker could achieve (confidentiality, integrity, availability) -- **Affected versions**: Which versions/commits are affected -- **Reproduction steps**: Detailed steps to reproduce the issue - -### Helpful Additional Information - -- **Proof of concept**: Code, scripts, or screenshots demonstrating the vulnerability -- **Attack scenario**: Realistic attack scenario showing exploitability -- **CVSS score**: Your assessment of severity (use [CVSS 3.1 Calculator](https://www.first.org/cvss/calculator/3.1)) -- **CWE ID**: Common Weakness Enumeration identifier if known -- **Suggested fix**: If you have ideas for remediation -- **References**: Links to related vulnerabilities, research, or advisories - -### Example Report Structure - -```markdown -## Summary -[One-sentence description of the vulnerability] - -## Vulnerability Type -[e.g., SQL Injection, XSS, SSRF, Path Traversal, etc.] - -## Affected Component -[File path, function name, API endpoint, etc.] - -## Affected Versions -[Version range or specific commits] - -## Severity Assessment -- CVSS 3.1 Score: [X.X] -- CVSS Vector: [CVSS:3.1/AV:X/AC:X/PR:X/UI:X/S:X/C:X/I:X/A:X] - -## Description -[Detailed technical description] - -## Steps to Reproduce -1. [First step] -2. [Second step] -3. [...] - -## Proof of Concept -[Code, curl commands, screenshots, etc.] - -## Impact -[What can an attacker achieve?] - -## Suggested Remediation -[Optional: your ideas for fixing] - -## References -[Links to related issues, CVEs, research] -``` - ---- - -## Response Timeline - -We commit to the following response times: - -| Stage | Timeframe | Description | -|-------|-----------|-------------| -| **Initial Response** | 48 hours | We acknowledge receipt and confirm we're investigating | -| **Triage** | 7 days | We assess severity, confirm the vulnerability, and estimate timeline | -| **Status Update** | Every 7 days | Regular updates on remediation progress | -| **Resolution** | 90 days | Target for fix development and release (complex issues may take longer) | -| **Disclosure** | 90 days | Public disclosure after fix is available (coordinated with you) | - -> **Note:** These are targets, not guarantees. Complex vulnerabilities may require more time. We'll communicate openly about any delays. - ---- - -## Disclosure Policy - -We follow **coordinated disclosure** (also known as responsible disclosure): - -1. **You report** the vulnerability privately -2. **We acknowledge** and begin investigation -3. **We develop** a fix and prepare a release -4. **We coordinate** disclosure timing with you -5. **We publish** security advisory and fix simultaneously -6. **You may publish** your research after disclosure - -### Our Commitments - -- We will not take legal action against researchers who follow this policy -- We will work with you to understand and resolve the issue -- We will credit you in the security advisory (unless you prefer anonymity) -- We will notify you before public disclosure -- We will publish advisories with sufficient detail for users to assess risk - -### Your Commitments - -- Report vulnerabilities promptly after discovery -- Give us reasonable time to address the issue before disclosure -- Do not access, modify, or delete data beyond what's necessary to demonstrate the vulnerability -- Do not degrade service availability (no DoS testing on production) -- Do not share vulnerability details with others until coordinated disclosure - -### Disclosure Timeline - -``` -Day 0 You report vulnerability -Day 1-2 We acknowledge receipt -Day 7 We confirm vulnerability and share initial assessment -Day 7-90 We develop and test fix -Day 90 Coordinated public disclosure - (earlier if fix is ready; later by mutual agreement) -``` - -If we cannot reach agreement on disclosure timing, we default to 90 days from your initial report. - ---- - -## Scope - -### In Scope ✅ - -The following are within scope for security research: - -- This repository (`hyperpolymath/language-bridges`) and all its code -- Official releases and packages published from this repository -- Documentation that could lead to security issues -- Build and deployment configurations in this repository -- Dependencies (report here, we'll coordinate with upstream) - -### Out of Scope ❌ - -The following are **not** in scope: - -- Third-party services we integrate with (report directly to them) -- Social engineering attacks against maintainers -- Physical security -- Denial of service attacks against production infrastructure -- Spam, phishing, or other non-technical attacks -- Issues already reported or publicly known -- Theoretical vulnerabilities without proof of concept - -### Qualifying Vulnerabilities - -We're particularly interested in: - -- Remote code execution -- SQL injection, command injection, code injection -- Authentication/authorisation bypass -- Cross-site scripting (XSS) and cross-site request forgery (CSRF) -- Server-side request forgery (SSRF) -- Path traversal / local file inclusion -- Information disclosure (credentials, PII, secrets) -- Cryptographic weaknesses -- Deserialisation vulnerabilities -- Memory safety issues (buffer overflows, use-after-free, etc.) -- Supply chain vulnerabilities (dependency confusion, etc.) -- Significant logic flaws - -### Non-Qualifying Issues - -The following generally do not qualify as security vulnerabilities: - -- Missing security headers on non-sensitive pages -- Clickjacking on pages without sensitive actions -- Self-XSS (requires victim to paste code) -- Missing rate limiting (unless it enables a specific attack) -- Username/email enumeration (unless high-risk context) -- Missing cookie flags on non-sensitive cookies -- Software version disclosure -- Verbose error messages (unless exposing secrets) -- Best practice deviations without demonstrable impact - ---- - -## Safe Harbour - -We support security research conducted in good faith. - -### Our Promise - -If you conduct security research in accordance with this policy: - -- ✅ We will not initiate legal action against you -- ✅ We will not report your activity to law enforcement -- ✅ We will work with you in good faith to resolve issues -- ✅ We consider your research authorised under the Computer Fraud and Abuse Act (CFAA), UK Computer Misuse Act, and similar laws -- ✅ We waive any potential claim against you for circumvention of security controls - -### Good Faith Requirements - -To qualify for safe harbour, you must: - -- Comply with this security policy -- Report vulnerabilities promptly -- Avoid privacy violations (do not access others' data) -- Avoid service degradation (no destructive testing) -- Not exploit vulnerabilities beyond proof-of-concept -- Not use vulnerabilities for profit (beyond bug bounties where offered) - -> **⚠️ Important:** This safe harbour does not extend to third-party systems. Always check their policies before testing. - ---- - -## Recognition - -We believe in recognising security researchers who help us improve. - -### Hall of Fame - -Researchers who report valid vulnerabilities will be acknowledged in our [Security Acknowledgments](SECURITY-ACKNOWLEDGMENTS.md) (unless they prefer anonymity). - -Recognition includes: - -- Your name (or chosen alias) -- Link to your website/profile (optional) -- Brief description of the vulnerability class -- Date of report - -### What We Offer - -- ✅ Public credit in security advisories -- ✅ Acknowledgment in release notes -- ✅ Entry in our Hall of Fame -- ✅ Reference/recommendation letter upon request (for significant findings) - -### What We Don't Currently Offer - -- ❌ Monetary bug bounties -- ❌ Hardware or swag -- ❌ Paid security research contracts - -> **Note:** We're a community project with limited resources. Your contributions help everyone who uses this software. - ---- - -## Security Updates - -### Receiving Updates - -To stay informed about security updates: - -- **Watch this repository**: Click "Watch" → "Custom" → Select "Security alerts" -- **GitHub Security Advisories**: Published at [Security Advisories](https://github.com/hyperpolymath/language-bridges/security/advisories) -- **Release notes**: Security fixes noted in [CHANGELOG](CHANGELOG.md) - -### Update Policy - -| Severity | Response | -|----------|----------| -| **Critical/High** | Patch release as soon as fix is ready | -| **Medium** | Included in next scheduled release (or earlier) | -| **Low** | Included in next scheduled release | - -### Supported Versions - - - -| Version | Supported | Notes | -|---------|-----------|-------| -| `main` branch | ✅ Yes | Latest development | -| Latest release | ✅ Yes | Current stable | -| Previous minor release | ✅ Yes | Security fixes backported | -| Older versions | ❌ No | Please upgrade | - ---- - -## Security Best Practices - -When using language-bridges, we recommend: - -### General - -- Keep dependencies up to date -- Use the latest stable release -- Subscribe to security notifications -- Review configuration against security documentation -- Follow principle of least privilege - -### For Contributors - -- Never commit secrets, credentials, or API keys -- Use signed commits (`git config commit.gpgsign true`) -- Review dependencies before adding them -- Run security linters locally before pushing -- Report any concerns about existing code - ---- - -## Additional Resources - -- [Our PGP Public Key](https://hyperpolymath.github.io/pgp.asc) -- [Security Advisories](https://github.com/hyperpolymath/language-bridges/security/advisories) -- [Changelog](CHANGELOG.md) -- [Contributing Guidelines](CONTRIBUTING.md) -- [CVE Database](https://cve.mitre.org/) -- [CVSS Calculator](https://www.first.org/cvss/calculator/3.1) - ---- - -## Contact - -| Purpose | Contact | -|---------|---------| -| **Security issues** | [Report via GitHub](https://github.com/hyperpolymath/language-bridges/security/advisories/new) or j.d.a.jewell@open.ac.uk | -| **General questions** | [GitHub Discussions](https://github.com/hyperpolymath/language-bridges/discussions) | -| **Other enquiries** | See [README](README.md) for contact information | - ---- - -## Policy Changes - -This security policy may be updated from time to time. Significant changes will be: - -- Committed to this repository with a clear commit message -- Noted in the changelog -- Announced via GitHub Discussions (for major changes) - ---- - -*Thank you for helping keep language-bridges and its users safe.* 🛡️ - ---- - -Last updated: 2026 · Policy version: 1.0.0 diff --git a/TEST-NEEDS.adoc b/TEST-NEEDS.adoc new file mode 100644 index 0000000..e1518f5 --- /dev/null +++ b/TEST-NEEDS.adoc @@ -0,0 +1,43 @@ +== TEST-NEEDS.md — wordpress-tools + +=== CRG Grade: C — ACHIEVED 2026-04-04 + +=== Current Test State + +[width="100%",cols="42%,29%,29%",options="header",] +|=== +|Category |Count |Notes +|Zig FFI tests |3 |Multiple subproject FFI layers (secured, +plugin-mapper, etc.) + +|PHP unit tests |3 |`+plugin-conflict-mapper/tests/unit/test-*.php+` + +|PHP integration tests |2 +|`+plugin-conflict-mapper/tests/integration/test-*.php+` + +|PHP validation tests |2 |php-aegis validation suite +|=== + +=== What’s Covered + +* [x] Zig FFI integration tests +* [x] PHP unit test framework +* [x] REST API integration tests +* [x] Cache validation tests +* [x] XSS security tests (CF7) +* [x] WordPress compatibility tests + +=== Still Missing (for CRG B+) + +* [ ] Plugin conflict fuzzing +* [ ] Security property tests +* [ ] Performance benchmarks +* [ ] Multi-version WordPress testing +* [ ] End-to-end plugin workflow tests + +=== Run Tests + +[source,bash] +---- +cd /var/mnt/eclipse/repos/wordpress-tools && bash plugin-conflict-mapper/bin/install-wp-tests.sh && cd plugin-conflict-mapper && phpunit +---- diff --git a/TEST-NEEDS.md b/TEST-NEEDS.md deleted file mode 100644 index ab3ff98..0000000 --- a/TEST-NEEDS.md +++ /dev/null @@ -1,39 +0,0 @@ - -# TEST-NEEDS.md — wordpress-tools - -## CRG Grade: C — ACHIEVED 2026-04-04 - -## Current Test State - -| Category | Count | Notes | -|----------|-------|-------| -| Zig FFI tests | 3 | Multiple subproject FFI layers (secured, plugin-mapper, etc.) | -| PHP unit tests | 3 | `plugin-conflict-mapper/tests/unit/test-*.php` | -| PHP integration tests | 2 | `plugin-conflict-mapper/tests/integration/test-*.php` | -| PHP validation tests | 2 | php-aegis validation suite | - -## What's Covered - -- [x] Zig FFI integration tests -- [x] PHP unit test framework -- [x] REST API integration tests -- [x] Cache validation tests -- [x] XSS security tests (CF7) -- [x] WordPress compatibility tests - -## Still Missing (for CRG B+) - -- [ ] Plugin conflict fuzzing -- [ ] Security property tests -- [ ] Performance benchmarks -- [ ] Multi-version WordPress testing -- [ ] End-to-end plugin workflow tests - -## Run Tests - -```bash -cd /var/mnt/eclipse/repos/wordpress-tools && bash plugin-conflict-mapper/bin/install-wp-tests.sh && cd plugin-conflict-mapper && phpunit -``` diff --git a/TOPOLOGY.md b/TOPOLOGY.adoc similarity index 86% rename from TOPOLOGY.md rename to TOPOLOGY.adoc index 7d10b7c..91aaedc 100644 --- a/TOPOLOGY.md +++ b/TOPOLOGY.adoc @@ -1,15 +1,8 @@ - - - +== wordpress-tools — Project Topology -# wordpress-tools — Project Topology +=== System Architecture -## System Architecture - -``` +.... ┌─────────────────────────────────────────┐ │ OPERATOR / ADMIN │ │ (WordPress Dashboard / CLI) │ @@ -41,11 +34,11 @@ Copyright (c) Jonathan D.A. Jewell │ Justfile Automation .machine_readable/ │ │ Best Practices 0-AI-MANIFEST.a2ml │ └─────────────────────────────────────────┘ -``` +.... -## Completion Dashboard +=== Completion Dashboard -``` +.... COMPONENT STATUS NOTES ───────────────────────────────── ────────────────── ───────────────────────────────── CORE TOOLING @@ -65,25 +58,26 @@ REPO INFRASTRUCTURE ───────────────────────────────────────────────────────────────────────────── OVERALL: ███████░░░ ~70% Stable toolset, Plugins refining -``` +.... -## Key Dependencies +=== Key Dependencies -``` +.... WordPress Core ───► praxis/ Framework ──► secured/ Hardening ──► Audit │ │ │ ▼ ▼ ▼ Plugins Set ─────► Conflict Mapper ────► sinople-theme -``` +.... -## 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..b405e65 --- /dev/null +++ b/docs/tech-debt-2026-05-26.adoc @@ -0,0 +1,71 @@ +== Tech-Debt Audit — wordpress-tools — 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 |22 +|`+docs/+` files |0 +|`+docs/+` LoC |0 +|CHANGELOG.md |N +|CONTRIBUTING.md |Y +|CODE_OF_CONDUCT.md |Y +|SECURITY.md |Y +|Severity |`+MEDIUM+` +|=== + +*Recommended next move:* introduce a `+docs/+` directory. The README at +22 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 ca2f7bd..0000000 --- a/docs/tech-debt-2026-05-26.md +++ /dev/null @@ -1,56 +0,0 @@ - -# Tech-Debt Audit — wordpress-tools — 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 | 22 | -| `docs/` files | 0 | -| `docs/` LoC | 0 | -| CHANGELOG.md | N | -| CONTRIBUTING.md | Y | -| CODE_OF_CONDUCT.md | Y | -| SECURITY.md | Y | -| Severity | `MEDIUM` | - -**Recommended next move:** introduce a `docs/` directory. The README at 22 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/journal-theme/.meta/REQUIRED-FILES.adoc b/journal-theme/.meta/REQUIRED-FILES.adoc new file mode 100644 index 0000000..3a85933 --- /dev/null +++ b/journal-theme/.meta/REQUIRED-FILES.adoc @@ -0,0 +1,58 @@ +== Required Repository Files + +The following files *MUST* be present and kept up-to-date in every +repository: + +=== Mandatory Dotfiles + +[cols=",",options="header",] +|=== +|File |Purpose +|`+.gitignore+` |Exclude build artifacts, secrets, and temp files +|`+.gitattributes+` |Enforce LF line endings and diff settings +|`+.editorconfig+` |Consistent editor settings across IDEs +|`+.tool-versions+` |asdf version pinning for reproducible builds +|=== + +=== Mandatory SCM Files + +[cols=",",options="header",] +|=== +|File |Purpose +|`+META.scm+` |Architecture decisions, development practices +|`+STATE.scm+` |Project state, phase, milestones +|`+ECOSYSTEM.scm+` |Ecosystem positioning, related projects +|`+PLAYBOOK.scm+` |Executable plans, procedures +|`+AGENTIC.scm+` |AI agent operational gating +|`+NEUROSYM.scm+` |Symbolic semantics, proof obligations +|=== + +=== Build System + +[cols=",",options="header",] +|=== +|File |Purpose +|`+justfile+` |Task runner (replaces Makefile) +|`+Mustfile+` |Deployment state contract +|=== + +*IMPORTANT*: Makefiles are FORBIDDEN. Use `+just+` for all tasks. + +=== Validation + +These files are checked by: - CI workflow validation - Pre-commit hooks +(when configured) - Repository standardization scripts + +=== Updates + +When updating these files: 1. Use templates from `+rsr-template-repo+` +as reference 2. Ensure SPDX license header is present 3. Test changes +locally before pushing 4. Keep language-specific sections relevant to +the repo + +=== See Also + +* https://github.com/hyperpolymath/rhodium-standard-repositories[RSR +(Rhodium Standard Repositories)] +* https://github.com/hyperpolymath/mustfile[Mustfile Specification] +* https://github.com/hyperpolymath/meta-scm[SCM Format Family] diff --git a/journal-theme/.meta/REQUIRED-FILES.md b/journal-theme/.meta/REQUIRED-FILES.md deleted file mode 100644 index 106daa9..0000000 --- a/journal-theme/.meta/REQUIRED-FILES.md +++ /dev/null @@ -1,57 +0,0 @@ - -# Required Repository Files - -The following files **MUST** be present and kept up-to-date in every repository: - -## Mandatory Dotfiles - -| File | Purpose | -|------|---------| -| `.gitignore` | Exclude build artifacts, secrets, and temp files | -| `.gitattributes` | Enforce LF line endings and diff settings | -| `.editorconfig` | Consistent editor settings across IDEs | -| `.tool-versions` | asdf version pinning for reproducible builds | - -## Mandatory SCM Files - -| File | Purpose | -|------|---------| -| `META.scm` | Architecture decisions, development practices | -| `STATE.scm` | Project state, phase, milestones | -| `ECOSYSTEM.scm` | Ecosystem positioning, related projects | -| `PLAYBOOK.scm` | Executable plans, procedures | -| `AGENTIC.scm` | AI agent operational gating | -| `NEUROSYM.scm` | Symbolic semantics, proof obligations | - -## Build System - -| File | Purpose | -|------|---------| -| `justfile` | Task runner (replaces Makefile) | -| `Mustfile` | Deployment state contract | - -**IMPORTANT**: Makefiles are FORBIDDEN. Use `just` for all tasks. - -## Validation - -These files are checked by: -- CI workflow validation -- Pre-commit hooks (when configured) -- Repository standardization scripts - -## Updates - -When updating these files: -1. Use templates from `rsr-template-repo` as reference -2. Ensure SPDX license header is present -3. Test changes locally before pushing -4. Keep language-specific sections relevant to the repo - -## See Also - -- [RSR (Rhodium Standard Repositories)](https://github.com/hyperpolymath/rhodium-standard-repositories) -- [Mustfile Specification](https://github.com/hyperpolymath/mustfile) -- [SCM Format Family](https://github.com/hyperpolymath/meta-scm) diff --git a/journal-theme/CODE_OF_CONDUCT.adoc b/journal-theme/CODE_OF_CONDUCT.adoc new file mode 100644 index 0000000..076a46d --- /dev/null +++ b/journal-theme/CODE_OF_CONDUCT.adoc @@ -0,0 +1,174 @@ +== 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, caste, color, 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 +* Using welcoming and inclusive language +* Being respectful of differing cultural backgrounds and norms + +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 +* Dismissing or attacking inclusion-focused requests or concerns + +=== 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 +*conduct@[your-domain]*. + +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.1, +available at +https://www.contributor-covenant.org/version/2/1/code_of_conduct.html. + +Community Impact Guidelines were inspired by +https://github.com/mozilla/diversity[Mozilla’s code of conduct +enforcement ladder]. + +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. + +''''' + +=== Additional: Emotional Safety & Tri-Perimeter Contribution Framework (TPCF) + +Sinople implements the *Tri-Perimeter Contribution Framework* (TPCF) to +provide graduated trust and emotional safety: + +==== Perimeter 1: Inner Sanctum (Maintainers Only) + +* *Access*: Write access to main/master branch +* *Responsibility*: Code review, release management, security responses +* *Requirements*: Established trust, demonstrated expertise, community +involvement + +==== Perimeter 2: Trusted Contributors (Collaborators) + +* *Access*: Write access to feature branches, review other PRs +* *Responsibility*: Regular contributions, helping newcomers, +documentation +* *Requirements*: 5+ merged PRs, consistent participation for 3+ months + +==== Perimeter 3: Community Sandbox (Open Contribution) + +* *Access*: Fork, PR submission, issue reporting +* *Responsibility*: Follow CoC, provide constructive feedback +* *Requirements*: GitHub account, agreement to CoC + +*Emotional Temperature*: We monitor contributor well-being and encourage +taking breaks when stressed. There is no penalty for stepping back. + +*Reversibility*: All contributions can be reverted if issues arise. +Experimentation is encouraged in Perimeter 3. + +''''' + +*Last Updated*: 2025-01-22 *Contact*: conduct@[your-domain] diff --git a/journal-theme/CODE_OF_CONDUCT.md b/journal-theme/CODE_OF_CONDUCT.md deleted file mode 100644 index 617b32e..0000000 --- a/journal-theme/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,170 +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, caste, color, 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 -* Using welcoming and inclusive language -* Being respectful of differing cultural backgrounds and norms - -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 -* Dismissing or attacking inclusion-focused requests or concerns - -## 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 -**conduct@[your-domain]**. - -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.1, available at -[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1]. - -Community Impact Guidelines were inspired by -[Mozilla's code of conduct enforcement ladder][Mozilla CoC]. - -For answers to common questions about this code of conduct, see the FAQ at -[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at -[https://www.contributor-covenant.org/translations][translations]. - -[homepage]: https://www.contributor-covenant.org -[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html -[Mozilla CoC]: https://github.com/mozilla/diversity -[FAQ]: https://www.contributor-covenant.org/faq -[translations]: https://www.contributor-covenant.org/translations - ---- - -## Additional: Emotional Safety & Tri-Perimeter Contribution Framework (TPCF) - -Sinople implements the **Tri-Perimeter Contribution Framework** (TPCF) to provide graduated trust and emotional safety: - -### Perimeter 1: Inner Sanctum (Maintainers Only) -- **Access**: Write access to main/master branch -- **Responsibility**: Code review, release management, security responses -- **Requirements**: Established trust, demonstrated expertise, community involvement - -### Perimeter 2: Trusted Contributors (Collaborators) -- **Access**: Write access to feature branches, review other PRs -- **Responsibility**: Regular contributions, helping newcomers, documentation -- **Requirements**: 5+ merged PRs, consistent participation for 3+ months - -### Perimeter 3: Community Sandbox (Open Contribution) -- **Access**: Fork, PR submission, issue reporting -- **Responsibility**: Follow CoC, provide constructive feedback -- **Requirements**: GitHub account, agreement to CoC - -**Emotional Temperature**: We monitor contributor well-being and encourage taking breaks when stressed. There is no penalty for stepping back. - -**Reversibility**: All contributions can be reverted if issues arise. Experimentation is encouraged in Perimeter 3. - ---- - -**Last Updated**: 2025-01-22 -**Contact**: conduct@[your-domain] diff --git a/journal-theme/CONTRIBUTING.adoc b/journal-theme/CONTRIBUTING.adoc index e9b1993..2633dcc 100644 --- a/journal-theme/CONTRIBUTING.adoc +++ b/journal-theme/CONTRIBUTING.adoc @@ -1,21 +1,109 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -// Copyright (c) Jonathan D.A. Jewell -= Contributing Guide +== Clone the repository -== Getting Started +git clone https://github.com/hyperpolymath/sinople-journal-theme.git cd +sinople-journal-theme -1. Fork the repository -2. Create a feature branch from `main` -3. Sign off commits (`git commit -s`) -4. Submit a pull request +== Using Nix (recommended for reproducibility) -== Commit Guidelines +nix develop -* Conventional commits: `type(scope): description` -* Sign all commits (DCO required) -* Atomic, focused commits +== Or using toolbox/distrobox -== License +toolbox create sinople-journal-theme-dev toolbox enter +sinople-journal-theme-dev # Install dependencies manually -Contributions licensed under project license. +== Verify setup +just check # or: cargo check / mix compile / etc. just test # Run test +suite + +.... + +### Repository Structure +.... + +sinople-journal-theme/ ├── 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/sinople-journal-theme/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://github.com/hyperpolymath/sinople-journal-theme/labels/help%20wanted) — Community help needed +- [`documentation`](https://github.com/hyperpolymath/sinople-journal-theme/labels/documentation) — Docs improvements +- [`perimeter-3`](https://github.com/hyperpolymath/sinople-journal-theme/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/journal-theme/CONTRIBUTING.md b/journal-theme/CONTRIBUTING.md deleted file mode 100644 index 1d2dfa8..0000000 --- a/journal-theme/CONTRIBUTING.md +++ /dev/null @@ -1,120 +0,0 @@ - -# Clone the repository -git clone https://github.com/hyperpolymath/sinople-journal-theme.git -cd sinople-journal-theme - -# Using Nix (recommended for reproducibility) -nix develop - -# Or using toolbox/distrobox -toolbox create sinople-journal-theme-dev -toolbox enter sinople-journal-theme-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure -``` -sinople-journal-theme/ -├── 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/sinople-journal-theme/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://github.com/hyperpolymath/sinople-journal-theme/labels/help%20wanted) — Community help needed -- [`documentation`](https://github.com/hyperpolymath/sinople-journal-theme/labels/documentation) — Docs improvements -- [`perimeter-3`](https://github.com/hyperpolymath/sinople-journal-theme/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/journal-theme/INSTALL.adoc b/journal-theme/INSTALL.adoc new file mode 100644 index 0000000..3ccbfb8 --- /dev/null +++ b/journal-theme/INSTALL.adoc @@ -0,0 +1,346 @@ +== Installation & Compatibility + +=== WordPress Compatibility Matrix + +[cols=",,,,",options="header",] +|=== +|Sinople Version |WordPress |PHP |MySQL/MariaDB |Status +|0.1.x |6.4 - 6.7 |8.1 - 8.4 |8.0+ / 10.5+ |Active Development +|=== + +==== Detailed Compatibility + +===== WordPress Versions + +[cols=",,",options="header",] +|=== +|WP Version |Compatibility |Notes +|6.7.x |Full |Tested, recommended +|6.6.x |Full |Tested +|6.5.x |Full |Tested +|6.4.x |Full |Minimum required +|6.3.x |Partial |Missing `+appearance-tools+` support +|< 6.3 |Unsupported |Block editor features unavailable +|=== + +===== PHP Versions + +[cols=",,",options="header",] +|=== +|PHP Version |Compatibility |Notes +|8.4.x |Full |Tested +|8.3.x |Full |Recommended +|8.2.x |Full |Tested +|8.1.x |Full |Minimum required +|8.0.x |Unsupported |EOL December 2023 +|7.x |Unsupported |Missing required features +|=== + +===== Database + +[cols=",,",options="header",] +|=== +|Database |Version |Notes +|MySQL |8.0+ |Recommended +|MariaDB |10.5+ |Recommended +|MySQL |5.7.x |Functional, not recommended +|=== + +===== Web Server + +[cols=",,",options="header",] +|=== +|Server |Compatibility |Notes +|Apache |2.4+ |`+.htaccess+` included +|Nginx |1.18+ |See nginx config below +|LiteSpeed |6.0+ |Full support +|Caddy |2.x |Full support +|=== + +''''' + +=== Installation + +==== Method 1: Manual Installation + +[source,bash] +---- +# Clone the repository +git clone https://github.com/hyperpolymath/sinople-theme.git + +# Navigate to your WordPress themes directory +cd /path/to/wordpress/wp-content/themes/ + +# Move or symlink the theme +mv /path/to/sinople-theme ./sinople +# or +ln -s /path/to/sinople-theme ./sinople +---- + +Then activate via *WordPress Admin > Appearance > Themes*. + +==== Method 2: Composer (Recommended for Development) + +Add to your `+composer.json+`: + +[source,json] +---- +{ + "repositories": [ + { + "type": "vcs", + "url": "https://github.com/hyperpolymath/sinople-theme" + } + ], + "require": { + "hyperpolymath/sinople-theme": "^0.1" + }, + "extra": { + "installer-paths": { + "wp-content/themes/{$name}/": ["type:wordpress-theme"] + } + } +} +---- + +Then run: + +[source,bash] +---- +composer install +---- + +==== Method 3: WordPress Admin Upload + +[arabic] +. Download the latest release as a ZIP file +. Go to *WordPress Admin > Appearance > Themes > Add New > Upload Theme* +. Select the ZIP file and click *Install Now* +. Activate the theme + +''''' + +=== Build Steps (Development) + +==== Prerequisites + +* PHP 8.1+ +* Composer 2.x +* Node.js 20+ (for CSS tooling, optional) + +==== Setup Development Environment + +[source,bash] +---- +# Clone the repository +git clone https://github.com/hyperpolymath/sinople-theme.git +cd sinople-theme + +# Install PHP dependencies +composer install + +# Verify installation +composer check +---- + +==== Available Commands + +[cols=",",options="header",] +|=== +|Command |Description +|`+composer install+` |Install all dependencies +|`+composer lint+` |Run PHP CodeSniffer (WPCS) +|`+composer format+` |Auto-fix coding standards issues +|`+composer analyze+` |Run PHPStan static analysis +|`+composer test+` |Run PHPUnit tests +|`+composer test:coverage+` |Run tests with coverage report +|`+composer audit+` |Check for security vulnerabilities +|`+composer check+` |Run lint + analyze + test +|=== + +==== Running Tests + +[source,bash] +---- +# Run all tests +composer test + +# Run with coverage +composer test:coverage + +# Run specific test file +./vendor/bin/phpunit tests/php/test-accessibility.php + +# Run specific test method +./vendor/bin/phpunit --filter test_skip_link_output +---- + +==== Code Quality + +[source,bash] +---- +# Check coding standards +composer lint + +# Auto-fix issues +composer format + +# Static analysis +composer analyze +---- + +''''' + +=== Recommended Plugins + +These plugins enhance Sinople’s IndieWeb and semantic capabilities: + +==== IndieWeb Stack + +[width="99%",cols="30%,33%,37%",options="header",] +|=== +|Plugin |Purpose |Required +|https://wordpress.org/plugins/webmention/[Webmention] |Send/receive +webmentions |Recommended + +|https://wordpress.org/plugins/semantic-linkbacks/[Semantic-Linkbacks] +|Rich webmention display |Recommended + +|https://wordpress.org/plugins/indieauth/[IndieAuth] |Decentralized +authentication |Optional + +|https://wordpress.org/plugins/micropub/[Micropub] |Post from external +clients |Optional + +|https://wordpress.org/plugins/indieweb-post-kinds/[Post Kinds] |Post +type taxonomy |Recommended + +|https://wordpress.org/plugins/syndication-links/[Syndication Links] +|POSSE support |Optional +|=== + +==== Accessibility + +[width="100%",cols="48%,52%",options="header",] +|=== +|Plugin |Purpose +|https://wordpress.org/plugins/wp-accessibility/[WP Accessibility] +|Additional a11y features + +|https://wordpress.org/plugins/pojo-accessibility/[One Click +Accessibility] |User-facing controls +|=== + +''''' + +=== Server Configuration + +==== Nginx Configuration + +[source,nginx] +---- +# Add to your server block for semantic endpoints +location = /void.rdf { + rewrite ^ /index.php?void=1 last; +} + +location = /.well-known/void { + rewrite ^ /index.php?void=1 last; +} + +location = /feed/ndjson { + rewrite ^ /index.php?ndjson=1 last; +} + +location = /feed/capnproto { + rewrite ^ /index.php?capnproto=1 last; +} + +# Security headers (recommended) +add_header X-Content-Type-Options "nosniff" always; +add_header X-Frame-Options "SAMEORIGIN" always; +add_header Referrer-Policy "strict-origin-when-cross-origin" always; +---- + +==== Apache Configuration + +The theme includes `+.htaccess+` support. Ensure `+mod_rewrite+` is +enabled: + +[source,bash] +---- +sudo a2enmod rewrite +sudo systemctl restart apache2 +---- + +''''' + +=== Post-Installation + +[arabic] +. *Activate the theme* via WordPress Admin +. *Flush permalinks*: Settings > Permalinks > Save Changes +. *Configure menus*: Appearance > Menus +. *Install IndieWeb plugins* (optional but recommended) +. *Test accessibility*: Run WAVE or axe DevTools + +==== Verify Installation + +Check these endpoints after activation: + +* `+https://yoursite.com/void.rdf+` - VoID dataset description +* `+https://yoursite.com/feed/ndjson+` - NDJSON feed +* `+https://yoursite.com/.well-known/void+` - Well-known VoID endpoint + +''''' + +=== Troubleshooting + +==== Common Issues + +*Theme not appearing in admin* - Ensure `+style.css+` exists with valid +theme header - Check file permissions (755 for directories, 644 for +files) + +*Permalinks not working* - Flush permalinks: Settings > Permalinks > +Save Changes - Verify `+.htaccess+` is writable (Apache) - Check Nginx +rewrite rules + +*PHP version errors* - Sinople requires PHP 8.1+ - Check version: +`+php -v+` - Update PHP or contact your host + +*Composer install fails* - Ensure Composer 2.x: `+composer --version+` - +Clear cache: `+composer clear-cache+` - Try with verbose: +`+composer install -vvv+` + +==== Getting Help + +* https://github.com/hyperpolymath/sinople-theme/issues[GitHub Issues] +* https://github.com/hyperpolymath/sinople-theme/blob/main/docs/[Documentation] + +''''' + +=== Updating + +==== Via Git + +[source,bash] +---- +cd wp-content/themes/sinople +git pull origin main +composer install --no-dev +---- + +==== Via Composer + +[source,bash] +---- +composer update hyperpolymath/sinople-theme +---- + +==== Post-Update + +[arabic] +. Clear any caching plugins +. Flush permalinks if semantic endpoints changed +. Test site functionality diff --git a/journal-theme/INSTALL.md b/journal-theme/INSTALL.md deleted file mode 100644 index f2875b8..0000000 --- a/journal-theme/INSTALL.md +++ /dev/null @@ -1,310 +0,0 @@ - -# Installation & Compatibility - -## WordPress Compatibility Matrix - -| Sinople Version | WordPress | PHP | MySQL/MariaDB | Status | -|-----------------|-----------|-----|---------------|--------| -| 0.1.x | 6.4 - 6.7 | 8.1 - 8.4 | 8.0+ / 10.5+ | Active Development | - -### Detailed Compatibility - -#### WordPress Versions - -| WP Version | Compatibility | Notes | -|------------|---------------|-------| -| 6.7.x | Full | Tested, recommended | -| 6.6.x | Full | Tested | -| 6.5.x | Full | Tested | -| 6.4.x | Full | Minimum required | -| 6.3.x | Partial | Missing `appearance-tools` support | -| < 6.3 | Unsupported | Block editor features unavailable | - -#### PHP Versions - -| PHP Version | Compatibility | Notes | -|-------------|---------------|-------| -| 8.4.x | Full | Tested | -| 8.3.x | Full | Recommended | -| 8.2.x | Full | Tested | -| 8.1.x | Full | Minimum required | -| 8.0.x | Unsupported | EOL December 2023 | -| 7.x | Unsupported | Missing required features | - -#### Database - -| Database | Version | Notes | -|----------|---------|-------| -| MySQL | 8.0+ | Recommended | -| MariaDB | 10.5+ | Recommended | -| MySQL | 5.7.x | Functional, not recommended | - -#### Web Server - -| Server | Compatibility | Notes | -|--------|---------------|-------| -| Apache | 2.4+ | `.htaccess` included | -| Nginx | 1.18+ | See nginx config below | -| LiteSpeed | 6.0+ | Full support | -| Caddy | 2.x | Full support | - ---- - -## Installation - -### Method 1: Manual Installation - -```bash -# Clone the repository -git clone https://github.com/hyperpolymath/sinople-theme.git - -# Navigate to your WordPress themes directory -cd /path/to/wordpress/wp-content/themes/ - -# Move or symlink the theme -mv /path/to/sinople-theme ./sinople -# or -ln -s /path/to/sinople-theme ./sinople -``` - -Then activate via **WordPress Admin > Appearance > Themes**. - -### Method 2: Composer (Recommended for Development) - -Add to your `composer.json`: - -```json -{ - "repositories": [ - { - "type": "vcs", - "url": "https://github.com/hyperpolymath/sinople-theme" - } - ], - "require": { - "hyperpolymath/sinople-theme": "^0.1" - }, - "extra": { - "installer-paths": { - "wp-content/themes/{$name}/": ["type:wordpress-theme"] - } - } -} -``` - -Then run: - -```bash -composer install -``` - -### Method 3: WordPress Admin Upload - -1. Download the latest release as a ZIP file -2. Go to **WordPress Admin > Appearance > Themes > Add New > Upload Theme** -3. Select the ZIP file and click **Install Now** -4. Activate the theme - ---- - -## Build Steps (Development) - -### Prerequisites - -- PHP 8.1+ -- Composer 2.x -- Node.js 20+ (for CSS tooling, optional) - -### Setup Development Environment - -```bash -# Clone the repository -git clone https://github.com/hyperpolymath/sinople-theme.git -cd sinople-theme - -# Install PHP dependencies -composer install - -# Verify installation -composer check -``` - -### Available Commands - -| Command | Description | -|---------|-------------| -| `composer install` | Install all dependencies | -| `composer lint` | Run PHP CodeSniffer (WPCS) | -| `composer format` | Auto-fix coding standards issues | -| `composer analyze` | Run PHPStan static analysis | -| `composer test` | Run PHPUnit tests | -| `composer test:coverage` | Run tests with coverage report | -| `composer audit` | Check for security vulnerabilities | -| `composer check` | Run lint + analyze + test | - -### Running Tests - -```bash -# Run all tests -composer test - -# Run with coverage -composer test:coverage - -# Run specific test file -./vendor/bin/phpunit tests/php/test-accessibility.php - -# Run specific test method -./vendor/bin/phpunit --filter test_skip_link_output -``` - -### Code Quality - -```bash -# Check coding standards -composer lint - -# Auto-fix issues -composer format - -# Static analysis -composer analyze -``` - ---- - -## Recommended Plugins - -These plugins enhance Sinople's IndieWeb and semantic capabilities: - -### IndieWeb Stack - -| Plugin | Purpose | Required | -|--------|---------|----------| -| [Webmention](https://wordpress.org/plugins/webmention/) | Send/receive webmentions | Recommended | -| [Semantic-Linkbacks](https://wordpress.org/plugins/semantic-linkbacks/) | Rich webmention display | Recommended | -| [IndieAuth](https://wordpress.org/plugins/indieauth/) | Decentralized authentication | Optional | -| [Micropub](https://wordpress.org/plugins/micropub/) | Post from external clients | Optional | -| [Post Kinds](https://wordpress.org/plugins/indieweb-post-kinds/) | Post type taxonomy | Recommended | -| [Syndication Links](https://wordpress.org/plugins/syndication-links/) | POSSE support | Optional | - -### Accessibility - -| Plugin | Purpose | -|--------|---------| -| [WP Accessibility](https://wordpress.org/plugins/wp-accessibility/) | Additional a11y features | -| [One Click Accessibility](https://wordpress.org/plugins/pojo-accessibility/) | User-facing controls | - ---- - -## Server Configuration - -### Nginx Configuration - -```nginx -# Add to your server block for semantic endpoints -location = /void.rdf { - rewrite ^ /index.php?void=1 last; -} - -location = /.well-known/void { - rewrite ^ /index.php?void=1 last; -} - -location = /feed/ndjson { - rewrite ^ /index.php?ndjson=1 last; -} - -location = /feed/capnproto { - rewrite ^ /index.php?capnproto=1 last; -} - -# Security headers (recommended) -add_header X-Content-Type-Options "nosniff" always; -add_header X-Frame-Options "SAMEORIGIN" always; -add_header Referrer-Policy "strict-origin-when-cross-origin" always; -``` - -### Apache Configuration - -The theme includes `.htaccess` support. Ensure `mod_rewrite` is enabled: - -```bash -sudo a2enmod rewrite -sudo systemctl restart apache2 -``` - ---- - -## Post-Installation - -1. **Activate the theme** via WordPress Admin -2. **Flush permalinks**: Settings > Permalinks > Save Changes -3. **Configure menus**: Appearance > Menus -4. **Install IndieWeb plugins** (optional but recommended) -5. **Test accessibility**: Run WAVE or axe DevTools - -### Verify Installation - -Check these endpoints after activation: - -- `https://yoursite.com/void.rdf` - VoID dataset description -- `https://yoursite.com/feed/ndjson` - NDJSON feed -- `https://yoursite.com/.well-known/void` - Well-known VoID endpoint - ---- - -## Troubleshooting - -### Common Issues - -**Theme not appearing in admin** -- Ensure `style.css` exists with valid theme header -- Check file permissions (755 for directories, 644 for files) - -**Permalinks not working** -- Flush permalinks: Settings > Permalinks > Save Changes -- Verify `.htaccess` is writable (Apache) -- Check Nginx rewrite rules - -**PHP version errors** -- Sinople requires PHP 8.1+ -- Check version: `php -v` -- Update PHP or contact your host - -**Composer install fails** -- Ensure Composer 2.x: `composer --version` -- Clear cache: `composer clear-cache` -- Try with verbose: `composer install -vvv` - -### Getting Help - -- [GitHub Issues](https://github.com/hyperpolymath/sinople-theme/issues) -- [Documentation](https://github.com/hyperpolymath/sinople-theme/blob/main/docs/) - ---- - -## Updating - -### Via Git - -```bash -cd wp-content/themes/sinople -git pull origin main -composer install --no-dev -``` - -### Via Composer - -```bash -composer update hyperpolymath/sinople-theme -``` - -### Post-Update - -1. Clear any caching plugins -2. Flush permalinks if semantic endpoints changed -3. Test site functionality diff --git a/journal-theme/MAINTAINERS.adoc b/journal-theme/MAINTAINERS.adoc index aa23a55..b2c3cf4 100644 --- a/journal-theme/MAINTAINERS.adoc +++ b/journal-theme/MAINTAINERS.adoc @@ -1,48 +1,145 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -// Copyright (c) Jonathan D.A. Jewell -= Maintainers -:toc: preamble +== Maintainers -This document lists the maintainers of this project and their responsibilities. +This document lists the maintainers of the Sinople WordPress theme +project. -== Current Maintainers +=== Active Maintainers -[cols="2,3,2",options="header"] -|=== -| Name | Role | Contact +==== Lead Maintainer -| Jonathan D.A. Jewell -| Lead Maintainer -| https://github.com/hyperpolymath[@hyperpolymath] -|=== +* *Jonathan* (https://github.com/hyperpolymath[@hyperpolymath]) +** *Role*: Project founder, architecture, security, accessibility +** *Timezone*: UTC +** *Focus*: Core theme, WCAG compliance, semantic web integration +** *Contact*: [your-email] -== Responsibilities +=== Emeritus Maintainers -Maintainers are responsible for: +(Previous maintainers who have stepped down will be listed here with +gratitude) -* Reviewing and merging pull requests -* Triaging issues and feature requests -* Ensuring code quality and security standards -* Managing releases and versioning -* Upholding the project's code of conduct +=== Maintainer Responsibilities -== Becoming a Maintainer +==== Code Review -Contributors who demonstrate: +* Review pull requests within 7 days +* Provide constructive, actionable feedback +* Ensure code meets quality standards (WCAG 2.3 AAA, security, +performance) +* Test changes in local development environment -* Consistent, high-quality contributions -* Understanding of the project's goals and standards -* Constructive participation in discussions -* Commitment to the project's long-term health +==== Release Management -May be invited to become maintainers at the discretion of existing maintainers. +* Create releases following semantic versioning +* Update CHANGELOG.md with all changes +* Tag releases in git +* Deploy to WordPress.org theme directory (when approved) +* Announce releases on social media/blog -== Decision Making +==== Security -* Routine decisions (bug fixes, minor improvements) can be made by any maintainer -* Significant changes require discussion and consensus among maintainers -* Breaking changes or major features should be discussed in issues before implementation +* Respond to security reports within 24 hours +* Coordinate security patches and disclosures +* Monitor dependency vulnerabilities +* Review and approve security-related PRs immediately -== Contact +==== Community -For questions about project governance, open an issue or contact the maintainers listed above. +* Answer questions in issues and discussions +* Help onboard new contributors +* Enforce Code of Conduct fairly and transparently +* Foster inclusive, welcoming environment + +==== Documentation + +* Keep documentation up-to-date +* Review documentation PRs +* Ensure all features are documented +* Maintain README, CLAUDE.md, and deployment guides + +=== Becoming a Maintainer + +Maintainership is earned through consistent, high-quality contributions +and community involvement. + +==== Criteria + +[arabic] +. *Technical Excellence*: Demonstrated expertise in WordPress, PHP, +accessibility, or security +. *Consistent Contribution*: 20+ merged PRs or equivalent +documentation/community work +. *Community Involvement*: Helpful in issues, welcoming to newcomers, +upholds CoC +. *Time Commitment*: Available to review PRs and respond to issues +regularly +. *Trust*: Established track record of responsible behavior + +==== Process + +[arabic] +. *Nomination*: Current maintainer nominates candidate or candidate +self-nominates +. *Discussion*: Maintainers discuss in private channel +. *Vote*: Consensus required (all current maintainers approve) +. *Onboarding*: New maintainer added to GitHub team, granted repository +access +. *Announcement*: Public announcement in README and MAINTAINERS.md + +=== Stepping Down + +Maintainers may step down at any time, no questions asked. We value +well-being over productivity. + +==== Process + +[arabic] +. *Notification*: Email other maintainers with effective date +. *Transition*: Transfer ongoing responsibilities to other maintainers +. *Recognition*: Move to Emeritus list with thanks +. *Access Removal*: Repository access removed (can be restored if +returning) + +=== Contact + +For maintainer-related questions: *maintainers@[your-domain]* + +=== Decision-Making Process + +==== Consensus Model + +* *Small changes*: Any maintainer can merge after review +* *Medium changes*: Two maintainer approvals required +* *Large changes*: All maintainers must approve +* *Breaking changes*: Community RFC, 7-day comment period, then +consensus + +==== Conflict Resolution + +[arabic] +. *Discussion*: Maintainers discuss privately to find common ground +. *Mediation*: If unresolved, invite neutral third party +. *Vote*: Last resort - majority vote (requires 2/3 supermajority) +. *Transparency*: Decision and rationale documented publicly + +=== Tri-Perimeter Contribution Framework (TPCF) + +Maintainers operate in *Perimeter 1 (Inner Sanctum)*. + +==== Responsibilities + +* *Security*: Handle security reports, review security PRs +* *Releases*: Create releases, manage branches, deploy +* *Governance*: Enforce CoC, resolve conflicts, guide project direction +* *Community*: Mentor Perimeter 2 contributors, welcome Perimeter 3 +newcomers + +==== Rights + +* *Write access*: Direct push to protected branches (with care) +* *Admin access*: Repository settings, GitHub Actions secrets +* *Release signing*: GPG keys for signed releases + +''''' + +*Last Updated*: 2025-01-22 *Maintainer Count*: 1 active, 0 emeritus diff --git a/journal-theme/MAINTAINERS.md b/journal-theme/MAINTAINERS.md deleted file mode 100644 index 3ec3a4b..0000000 --- a/journal-theme/MAINTAINERS.md +++ /dev/null @@ -1,119 +0,0 @@ - -# Maintainers - -This document lists the maintainers of the Sinople WordPress theme project. - -## Active Maintainers - -### Lead Maintainer -- **Jonathan** ([@hyperpolymath](https://github.com/hyperpolymath)) - - **Role**: Project founder, architecture, security, accessibility - - **Timezone**: UTC - - **Focus**: Core theme, WCAG compliance, semantic web integration - - **Contact**: [your-email] - -## Emeritus Maintainers - -(Previous maintainers who have stepped down will be listed here with gratitude) - -## Maintainer Responsibilities - -### Code Review -- Review pull requests within 7 days -- Provide constructive, actionable feedback -- Ensure code meets quality standards (WCAG 2.3 AAA, security, performance) -- Test changes in local development environment - -### Release Management -- Create releases following semantic versioning -- Update CHANGELOG.md with all changes -- Tag releases in git -- Deploy to WordPress.org theme directory (when approved) -- Announce releases on social media/blog - -### Security -- Respond to security reports within 24 hours -- Coordinate security patches and disclosures -- Monitor dependency vulnerabilities -- Review and approve security-related PRs immediately - -### Community -- Answer questions in issues and discussions -- Help onboard new contributors -- Enforce Code of Conduct fairly and transparently -- Foster inclusive, welcoming environment - -### Documentation -- Keep documentation up-to-date -- Review documentation PRs -- Ensure all features are documented -- Maintain README, CLAUDE.md, and deployment guides - -## Becoming a Maintainer - -Maintainership is earned through consistent, high-quality contributions and community involvement. - -### Criteria -1. **Technical Excellence**: Demonstrated expertise in WordPress, PHP, accessibility, or security -2. **Consistent Contribution**: 20+ merged PRs or equivalent documentation/community work -3. **Community Involvement**: Helpful in issues, welcoming to newcomers, upholds CoC -4. **Time Commitment**: Available to review PRs and respond to issues regularly -5. **Trust**: Established track record of responsible behavior - -### Process -1. **Nomination**: Current maintainer nominates candidate or candidate self-nominates -2. **Discussion**: Maintainers discuss in private channel -3. **Vote**: Consensus required (all current maintainers approve) -4. **Onboarding**: New maintainer added to GitHub team, granted repository access -5. **Announcement**: Public announcement in README and MAINTAINERS.md - -## Stepping Down - -Maintainers may step down at any time, no questions asked. We value well-being over productivity. - -### Process -1. **Notification**: Email other maintainers with effective date -2. **Transition**: Transfer ongoing responsibilities to other maintainers -3. **Recognition**: Move to Emeritus list with thanks -4. **Access Removal**: Repository access removed (can be restored if returning) - -## Contact - -For maintainer-related questions: **maintainers@[your-domain]** - -## Decision-Making Process - -### Consensus Model -- **Small changes**: Any maintainer can merge after review -- **Medium changes**: Two maintainer approvals required -- **Large changes**: All maintainers must approve -- **Breaking changes**: Community RFC, 7-day comment period, then consensus - -### Conflict Resolution -1. **Discussion**: Maintainers discuss privately to find common ground -2. **Mediation**: If unresolved, invite neutral third party -3. **Vote**: Last resort - majority vote (requires 2/3 supermajority) -4. **Transparency**: Decision and rationale documented publicly - -## Tri-Perimeter Contribution Framework (TPCF) - -Maintainers operate in **Perimeter 1 (Inner Sanctum)**. - -### Responsibilities -- **Security**: Handle security reports, review security PRs -- **Releases**: Create releases, manage branches, deploy -- **Governance**: Enforce CoC, resolve conflicts, guide project direction -- **Community**: Mentor Perimeter 2 contributors, welcome Perimeter 3 newcomers - -### Rights -- **Write access**: Direct push to protected branches (with care) -- **Admin access**: Repository settings, GitHub Actions secrets -- **Release signing**: GPG keys for signed releases - ---- - -**Last Updated**: 2025-01-22 -**Maintainer Count**: 1 active, 0 emeritus diff --git a/journal-theme/README-DEPLOYMENT.md b/journal-theme/README-DEPLOYMENT.adoc similarity index 55% rename from journal-theme/README-DEPLOYMENT.md rename to journal-theme/README-DEPLOYMENT.adoc index 7acf5cb..a1ca5ad 100644 --- a/journal-theme/README-DEPLOYMENT.md +++ b/journal-theme/README-DEPLOYMENT.adoc @@ -1,14 +1,11 @@ - -# 🚀 Sinople Theme - Deployment Guide +== 🚀 Sinople Theme - Deployment Guide -## Quick Start with Podman +=== Quick Start with Podman -### Development Environment +==== Development Environment -```bash +[source,bash] +---- # Copy environment template cp .env.example .env @@ -19,11 +16,12 @@ nano .env podman-compose -f docker-compose.dev.yml up --build # Access at http://localhost:8080 -``` +---- -### Production Deployment +==== Production Deployment -```bash +[source,bash] +---- # Generate SSL certificates (if not using Let's Encrypt) mkdir -p config/ssl openssl req -x509 -nodes -days 365 -newkey rsa:2048 \ @@ -43,13 +41,14 @@ podman-compose -f docker-compose.prod.yml up -d # View logs podman-compose -f docker-compose.prod.yml logs -f -``` +---- -## Container Security +=== Container Security -### Firewall Configuration (iptables) +==== Firewall Configuration (iptables) -```bash +[source,bash] +---- # Allow only necessary ports sudo iptables -A INPUT -p tcp --dport 443 -j ACCEPT # HTTPS sudo iptables -A INPUT -p tcp --dport 80 -j ACCEPT # HTTP @@ -62,53 +61,60 @@ sudo iptables -P OUTPUT ACCEPT # Save rules sudo iptables-save > /etc/iptables/rules.v4 -``` +---- -### Container Network Isolation +==== Container Network Isolation -All internal services run on isolated `sinople_internal` network with no external access except via nginx reverse proxy. +All internal services run on isolated `+sinople_internal+` network with +no external access except via nginx reverse proxy. -## BEAM Integration (Elixir/Erlang) +=== BEAM Integration (Elixir/Erlang) -### Starting the BEAM Container +==== Starting the BEAM Container -```bash +[source,bash] +---- # Start RabbitMQ and BEAM containers podman-compose -f docker-compose.dev.yml up -d rabbitmq beam # Check BEAM logs podman logs -f sinople-beam -``` +---- -### Message Queue Integration +==== Message Queue Integration -WordPress posts automatically publish to RabbitMQ queue `sinople.posts` in Ecto-compatible format. +WordPress posts automatically publish to RabbitMQ queue +`+sinople.posts+` in Ecto-compatible format. -## Build System +=== Build System -### Install Dependencies +==== Install Dependencies -```bash +[source,bash] +---- npm install -``` +---- -### Development Build +==== Development Build -```bash +[source,bash] +---- npm run dev -``` +---- -### Production Build +==== Production Build -```bash +[source,bash] +---- npm run build -``` +---- -### WASM Compilation +==== WASM Compilation Requires Rust toolchain: -```bash +[source,bash] +---- # Install Rust curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh @@ -121,82 +127,90 @@ cargo build --release --target wasm32-unknown-unknown # Optimize (requires wasm-opt) wasm-opt -Oz -o dist/sinople.wasm target/wasm32-unknown-unknown/release/sinople_wasm.wasm -``` +---- -## Performance Optimization +=== Performance Optimization -### Enable Redis Cache +==== Enable Redis Cache -Already configured in docker-compose. WordPress will use Redis for object caching. +Already configured in docker-compose. WordPress will use Redis for +object caching. -### CDN Configuration +==== CDN Configuration -1. Build optimized assets: `npm run build` -2. Upload `assets/css/min/` and `assets/js/dist/` to CDN -3. Update `functions.php` with CDN URLs +[arabic] +. Build optimized assets: `+npm run build+` +. Upload `+assets/css/min/+` and `+assets/js/dist/+` to CDN +. Update `+functions.php+` with CDN URLs -## Security Checklist +=== Security Checklist -- [ ] Update all passwords in `.env` -- [ ] Generate strong `WORDPRESS_DB_PASSWORD` and `RABBITMQ_PASS` -- [ ] Configure SSL certificates (Let's Encrypt recommended) -- [ ] Review and adjust CSP headers in nginx config -- [ ] Enable fail2ban for brute force protection -- [ ] Set up automated backups -- [ ] Configure firewall rules -- [ ] Review container capabilities in docker-compose -- [ ] Enable AppArmor/SELinux profiles -- [ ] Scan containers for vulnerabilities: `podman scan sinople-theme:latest` +* [ ] Update all passwords in `+.env+` +* [ ] Generate strong `+WORDPRESS_DB_PASSWORD+` and `+RABBITMQ_PASS+` +* [ ] Configure SSL certificates (Let’s Encrypt recommended) +* [ ] Review and adjust CSP headers in nginx config +* [ ] Enable fail2ban for brute force protection +* [ ] Set up automated backups +* [ ] Configure firewall rules +* [ ] Review container capabilities in docker-compose +* [ ] Enable AppArmor/SELinux profiles +* [ ] Scan containers for vulnerabilities: +`+podman scan sinople-theme:latest+` -## Monitoring +=== Monitoring -### Health Checks +==== Health Checks -```bash +[source,bash] +---- # Check all services podman-compose -f docker-compose.prod.yml ps # Manual health check curl https://your-domain.com/health -``` +---- -### Logs +==== Logs -```bash +[source,bash] +---- # View all logs podman-compose logs -f # View specific service podman logs -f sinople-wordpress-prod -``` +---- -## Backup & Restore +=== Backup & Restore -### Backup +==== Backup -```bash +[source,bash] +---- # Database backup podman exec sinople-db-prod mysqldump -u $DB_USER -p$DB_PASSWORD sinople > backup-$(date +%Y%m%d).sql # WordPress uploads tar -czf uploads-$(date +%Y%m%d).tar.gz -C /var/lib/containers/storage/volumes/ wordpress_data -``` +---- -### Restore +==== Restore -```bash +[source,bash] +---- # Restore database podman exec -i sinople-db-prod mysql -u $DB_USER -p$DB_PASSWORD sinople < backup.sql # Restore uploads tar -xzf uploads.tar.gz -C /var/lib/containers/storage/volumes/ -``` +---- -## Troubleshooting +=== Troubleshooting -### Container Won't Start +==== Container Won’t Start -```bash +[source,bash] +---- # Check logs podman logs sinople-wordpress @@ -205,21 +219,23 @@ podman exec sinople-wordpress ls -la /var/www/html # Verify network podman network inspect sinople_internal -``` +---- -### WASM Not Loading +==== WASM Not Loading -1. Check CSP headers allow `wasm-unsafe-eval` -2. Verify WASM file exists in `assets/js/dist/` -3. Check browser console for errors +[arabic] +. Check CSP headers allow `+wasm-unsafe-eval+` +. Verify WASM file exists in `+assets/js/dist/+` +. Check browser console for errors -### Performance Issues +==== Performance Issues -1. Enable Redis caching -2. Optimize images (use WebP) -3. Enable Gzip/Brotli compression -4. Use CDN for static assets +[arabic] +. Enable Redis caching +. Optimize images (use WebP) +. Enable Gzip/Brotli compression +. Use CDN for static assets -## License +=== License GPL-3.0 for code, CC BY 4.0 for content diff --git a/journal-theme/RSR-COMPLIANCE.adoc b/journal-theme/RSR-COMPLIANCE.adoc new file mode 100644 index 0000000..a4d0716 --- /dev/null +++ b/journal-theme/RSR-COMPLIANCE.adoc @@ -0,0 +1,406 @@ +== RSR (Rhodium Standard Repository) Compliance + +*Status*: 🥈 *Silver Level* ✅ | Targeting: 🥇 Gold Level + +This document tracks compliance with the Rhodium Standard Repository +(RSR) framework. + +=== Compliance Overview + +[width="100%",cols="40%,32%,28%",options="header",] +|=== +|Category |Status |Notes +|*Type Safety* |✅ Bronze |PHP 8.1+, strict, Rust, + +|*Memory Safety* |✅ Bronze |Rust ownership model, zero unsafe blocks in +WASM + +|*Offline-First* |✅ Bronze |No mandatory external dependencies, works +air-gapped + +|*Documentation* |✅ Bronze |20+ markdown files, comprehensive coverage + +|*Security* |✅ Silver |OWASP Top 10, seccomp, strict headers, CVE +monitoring + +|*Testing* |✅ Bronze |PHPUnit, Jest, Cargo tests with >80% coverage +target + +|*CI/CD* |✅ Bronze |GitHub Actions, GitLab CI, Dependabot, Renovate + +|*Licensing* |✅ Bronze |GPL-3.0, clear LICENSE file + +|*Community* |✅ Bronze |CoC, CONTRIBUTING.md, MAINTAINERS.md + +|*Accessibility* |✅ Gold |WCAG 2.3 AAA compliance + +|*Interoperability* |✅ Gold |5 serialization formats, RPC, BEAM +integration +|=== + +*Overall*: Silver Level ✅ (11/11 categories at Bronze+, 3 at Silver+, 2 +at Gold) + +=== Detailed Compliance + +==== 1. Type Safety ✅ Bronze + +*Requirement*: Static type checking in at least one primary language + +*Implementation*: - ✅ *PHP 8.1+*: Strict types, +declare(strict_types=1), type hints, return types - ✅ ****: Strict mode +enabled, no implicit any, all functions typed - ✅ *Rust*: Compile-time +type checking, no runtime type errors - ✅ ****: Sound type system, type +inference, no runtime exceptions - ✅ *Elixir*: Typespecs with Dialyzer +for static analysis + +*Verification*: + +[source,bash] +---- +# PHP (WordPress Coding Standards) +composer install +./vendor/bin/phpcs --standard=WordPress . + +# +npm run lint:js + +# Rust +cd assets/wasm && cargo check + +# +npm run build: +---- + +==== 2. Memory Safety ✅ Bronze + +*Requirement*: No memory corruption vulnerabilities (buffer overflows, +use-after-free, etc.) + +*Implementation*: - ✅ *Rust*: Ownership model, borrow checker, no +unsafe blocks in lib.rs - ✅ *PHP*: Memory-managed, no manual memory +management - ✅ */JavaScript*: Garbage-collected, no manual memory +management - ✅ *Container*: Read-only filesystem, tmpfs for necessary +writes + +*Verification*: + +[source,bash] +---- +# Rust safety check +cd assets/wasm +cargo clippy -- -D warnings +cargo audit + +# Container security scan +podman scan sinople-theme:latest +---- + +==== 3. Offline-First ✅ Bronze + +*Requirement*: No mandatory external dependencies, works without +internet + +*Implementation*: - ✅ *No external API calls* in core functionality - +✅ *Service Worker*: Offline support with cache-first strategy - ✅ +*Local fonts*: System fonts, no Google Fonts by default - ✅ +*Consent-based external resources*: External embeds require user consent +- ✅ *Build system*: Can build completely offline (after initial npm +install) + +*Verification*: + +[source,bash] +---- +# Disconnect network +sudo ifconfig eth0 down + +# Build should still work (if node_modules exists) +npm run build + +# Theme should render (WordPress must be local) +---- + +==== 4. Documentation ✅ Bronze + +*Requirement*: README, LICENSE, CONTRIBUTING, CODE_OF_CONDUCT, SECURITY + +*Implementation*: - ✅ *README.md*: Comprehensive project overview, +features, installation - ✅ *LICENSE*: GPL-3.0 (code), CC BY 4.0 +(content) - ✅ *CONTRIBUTING.md*: Contribution guidelines, coding +standards - ✅ *CODE_OF_CONDUCT.md*: Contributor Covenant 2.1 + TPCF - +✅ *SECURITY.md*: Vulnerability reporting, threat model, roadmap - ✅ +*MAINTAINERS.md*: Governance, decision-making, contact info - ✅ +*CHANGELOG.md*: All changes documented, semantic versioning - ✅ +*CLAUDE.md*: AI assistant guide, development guidelines - ✅ +*README-DEPLOYMENT.md*: Full deployment instructions - ✅ +*.well-known/security.txt*: RFC 9116 compliant - ✅ +*.well-known/ai.txt*: AI training policies - ✅ +*.well-known/humans.txt*: Human attribution, tech stack + +*Total*: 18 documentation files + +==== 5. Security ✅ Silver (exceeds Bronze) + +*Requirement*: Basic security practices, no known vulnerabilities + +*Implementation*: - ✅ *OWASP Top 10 2021*: All mitigations implemented +- ✅ *Security headers*: CSP, COEP, COOP, CORP, HSTS, Permissions-Policy +- ✅ *Container security*: Seccomp, AppArmor, capability dropping, +non-root user - ✅ *Input validation*: All user input sanitized, +prepared statements - ✅ *Dependency scanning*: npm audit, cargo audit, +composer audit (manual) - ✅ *CVE monitoring*: Chainguard Wolfi +(continuously patched base images) - ✅ *Vulnerability disclosure*: +security.txt, SECURITY.md with 24h response SLA - ✅ *Threat model*: +Documented in SECURITY.md - ⚠️ *Automated scanning*: Need to add +Dependabot/Renovate (roadmap) + +==== 6. Testing ✅ Bronze + +*Requirement*: Unit tests, integration tests, >80% coverage + +*Implementation*: - ✅ *PHPUnit*: Comprehensive test suite for inc/ +modules - SinopleTestCase base class with WordPress test helpers - +test-setup.php: Reading time, post classes, query vars, rewrite rules - +test-semantic.php: JSON-LD, Open Graph, Twitter Cards, breadcrumbs - +test-accessibility.php: Skip links, ARIA attributes, screen reader text +- test-security.php: Security headers, CSP, input sanitization, nonces - +test-indieweb.php: Microformats, h-card, webmentions, JSON Feed, POSSE - +test-serialization.php: NDJSON, FlatBuffers, Cap’n Proto, BEAM interop - +✅ *Jest*: /JavaScript test suite - accessibility.test.ts: Font size +controls, theme toggle, contrast mode - features.test.ts: View +Transitions, WASM, Container Queries, :has() - wasm.test.ts: Reading +time, HTML sanitization, password hashing - ✅ *Cargo test*: Rust WASM +test suite configured - ✅ *Test infrastructure*: phpunit.xml, +jest.config.js, bootstrap files - ✅ *Coverage reporting*: HTML, text, +clover, LCOV formats - ✅ *CI integration*: Tests run on every push/PR + +*Verification*: + +[source,bash] +---- +# PHP tests +composer install --dev +vendor/bin/phpunit --coverage-text --testdox + +# JavaScript tests +npm ci +npm test -- --coverage + +# Rust tests +cd assets/wasm && cargo test + +# All tests via justfile +just test +---- + +==== 7. CI/CD ✅ Bronze + +*Requirement*: Automated builds, tests, linting, security scans + +*Implementation*: - ✅ *GitHub Actions*: Comprehensive CI/CD pipeline - +`+.github/workflows/ci.yml+`: Multi-job parallel pipeline - PHP linting +(PHPCS, PHPStan) - PHP tests (matrix: PHP 8.1/8.2/8.3 × WP +6.4/6.5/latest) - JavaScript linting (ESLint, Stylelint) - JavaScript +tests (Jest with coverage) - Rust tests (cargo test, clippy, rustfmt) - +Build assets (all languages) - Security audit (npm, composer, cargo) - +Container build & Trivy scan - Accessibility tests (Playwright) - +`+.github/workflows/release.yml+`: Automated releases - Build production +package - Generate SBOM (CycloneDX) - Container image build & push to +GHCR - Image signing with cosign - ✅ *GitLab CI*: Complete pipeline +with parallel jobs - `+.gitlab-ci.yml+`: 5 stages (lint, test, security, +build, deploy) - PHP/JS/Rust linting in parallel - PHP test matrix (3 +PHP versions) - Security audits (npm, composer, cargo, Trivy) - +Container builds - Manual deployment to dev/prod - ✅ *Dependabot*: +Automated dependency updates - `+.github/dependabot.yml+`: npm, +composer, cargo, GitHub Actions - Weekly schedule - Auto-merge for +patches/minors - ✅ *Renovate*: Alternative dependency manager - +`+.github/renovate.json+`: Grouped updates, vulnerability alerts - ✅ +*Build automation*: justfile with 40+ recipes - ✅ *Coverage reporting*: +Codecov integration + +*Verification*: + +[source,bash] +---- +# Trigger CI locally (requires act) +act push + +# View workflows +gh workflow list + +# Manual justfile commands +just check # Quick validation +just test # All tests +just build # Production build +---- + +==== 8. Licensing ✅ Bronze + +*Requirement*: Clear, OSI-approved license + +*Implementation*: - ✅ *LICENSE file*: GPL-3.0-or-later (OSI-approved) - +✅ *License headers*: All PHP files have GPL-3.0 header - ✅ *Dual +licensing*: Code (GPL-3.0), content/docs (CC BY 4.0) - ✅ *Dependency +licensing*: All compatible with GPL-3.0 - ✅ *License documentation*: +README, CLAUDE.md, humans.txt + +==== 9. Community ✅ Bronze + +*Requirement*: Code of Conduct, contribution guidelines, maintainer info + +*Implementation*: - ✅ *CODE_OF_CONDUCT.md*: Contributor Covenant 2.1 - +✅ *CONTRIBUTING.md*: Detailed contribution guidelines - ✅ +*MAINTAINERS.md*: Governance model, contact info - ✅ *TPCF*: +Tri-Perimeter Contribution Framework implemented - Perimeter 1 (Inner +Sanctum): Maintainers only - Perimeter 2 (Trusted Contributors): +Collaborators with write access - Perimeter 3 (Community Sandbox): Open +contribution (current level) - ✅ *Issue templates*: (Would add in +GitHub/GitLab) - ✅ *PR templates*: (Would add in GitHub/GitLab) + +==== 10. Accessibility ✅ Gold (exceeds Silver) + +*Requirement*: Basic keyboard navigation, WCAG 2.1 AA minimum + +*Implementation*: - ✅ *WCAG 2.3 AAA*: Highest accessibility standard - +✅ *Keyboard navigation*: All interactive elements keyboard-accessible - +✅ *Screen reader*: Full ARIA support, semantic HTML - ✅ *Focus +indicators*: Visible 3px outline, customizable - ✅ *Color contrast*: +AAA ratios (7:1 for normal text, 4.5:1 for large) - ✅ *Motion*: +prefers-reduced-motion respected - ✅ *Font sizing*: User-adjustable +(80%-150%) - ✅ *Dark mode*: System preference + manual toggle - ✅ +*High contrast*: Manual toggle for enhanced visibility - ✅ *Skip +links*: To main content, navigation, footer - ✅ *Semantic HTML*: Proper +heading hierarchy, landmarks + +==== 11. Interoperability ✅ Gold (exceeds Silver) + +*Requirement*: Standard formats, documented APIs + +*Implementation*: - ✅ *Multiple serialization formats*: - NDJSON +(streaming, line-delimited JSON) - FlatBuffers (zero-copy, +cross-language) - Cap’n Proto (RPC, highest performance) - JSON-LD +(semantic web) - RDF/Turtle (linked data) - ✅ *Standard protocols*: - +HTTP/2, HTTP/3 (QUIC) - REST APIs (WordPress) - RPC (Cap’n Proto) - SSE +(Server-Sent Events for streaming) - WebSockets-ready (via RabbitMQ) - +✅ *BEAM integration*: Ecto schemas, RabbitMQ consumer, Elixir/Erlang +interop - ✅ *Microformats v2*: h-entry, h-card, IndieWeb-compliant - ✅ +*Open standards*: Schema.org, Open Graph, Dublin Core, FOAF - ✅ *VoID +dataset*: Machine-readable dataset description + +=== TPCF Implementation + +==== Perimeter 3: Community Sandbox ✅ (Current) + +* *Access*: Public fork, PR submission, issue reporting +* *Security*: No write access to main repository +* *Emotional Safety*: No judgment, experimentation encouraged +* *Reversibility*: All contributions can be reverted if issues arise + +*Current Status*: Open for community contributions + +==== Perimeter 2: Trusted Contributors (Roadmap) + +* *Requirements*: 5+ merged PRs, 3+ months consistent participation +* *Access*: Write access to feature branches, PR review rights +* *Timeline*: After 3-6 months of active contribution + +==== Perimeter 1: Inner Sanctum (Maintainers Only) + +* *Current*: 1 maintainer (Jonathan/@hyperpolymath) +* *Access*: Write access to main branch, release management +* *Responsibilities*: Security, releases, governance, community + +=== Silver Level Achievement ✅ + +*Achieved*: 2025-01-23 + +==== Completed Requirements + +[arabic] +. ✅ *Testing*: Automated test suite implemented +* PHPUnit: 6 test classes covering all inc/ modules +* Jest: 3 test suites for modules +* Cargo test: Rust WASM testing configured +* Coverage reporting: HTML, text, clover, LCOV +. ✅ *CI/CD*: Complete pipelines operational +* GitHub Actions: Multi-job CI with matrix testing +* GitLab CI: 5-stage pipeline with parallel jobs +* Automated releases with SBOM generation +* Container signing with cosign +. ✅ *Dependency automation*: Fully configured +* Dependabot: npm, composer, cargo, GitHub Actions +* Renovate: Grouped updates, vulnerability alerts +. ✅ *Build system*: Modern justfile with 40+ recipes + +=== Roadmap to Gold Level + +*Target*: Q4 2025 + +==== Requirements + +[arabic] +. *Formal verification*: SPARK proofs for critical security functions +. *Fuzzing*: AFL/libFuzzer for input validation +. *Third-party audit*: External security audit +. *SBOM*: Automated Software Bill of Materials generation +. *Signed releases*: cosign/sigstore container signing +. *Community metrics*: Active contributors, response times, issue +resolution + +=== Verification Commands + +[source,bash] +---- +# Clone repository +git clone https://github.com/hyperpolymath/sinople-theme +cd sinople-theme + +# Check offline capability (must have node_modules first) +npm ci # Install dependencies +npm run build # Should work offline after this + +# Run linting +npm run lint + +# Check security +npm audit +cargo audit (in assets/wasm/) + +# Build containers +podman build -t sinople-theme:test -f Containerfile . + +# Scan container +podman scan sinople-theme:test + +# Check accessibility +# (Manual: Use WAVE, axe DevTools in browser) + +# Verify serialization endpoints +curl https://your-domain.com/feed/ndjson +curl https://your-domain.com/feed/capnproto?cp_format=json +curl https://your-domain.com/void.rdf +---- + +=== Compliance Checklist + +* [x] Type Safety (Bronze) ✅ +* [x] Memory Safety (Bronze) ✅ +* [x] Offline-First (Bronze) ✅ +* [x] Documentation (Bronze) ✅ - 20+ files +* [x] Security (Silver) ✅ - Exceeds Bronze +* [x] Testing (Bronze) ✅ - PHPUnit, Jest, Cargo +* [x] CI/CD (Bronze) ✅ - GitHub Actions, GitLab CI, Dependabot +* [x] Licensing (Bronze) ✅ +* [x] Community (Bronze) ✅ +* [x] Accessibility (Gold) ✅ - WCAG 2.3 AAA +* [x] Interoperability (Gold) ✅ - 5 serialization formats + +*Current Level*: 🥈 Silver (11/11 categories at Bronze+) *Next Target*: +🥇 Gold (formal verification, fuzzing, third-party audit) + +''''' + +*Last Updated*: 2025-01-23 *Silver Level Achieved*: 2025-01-23 *Verified +By*: Jonathan (@hyperpolymath) + Claude (Anthropic AI) *Next Review*: +2025-02-23 (monthly) diff --git a/journal-theme/RSR-COMPLIANCE.md b/journal-theme/RSR-COMPLIANCE.md deleted file mode 100644 index 8b63408..0000000 --- a/journal-theme/RSR-COMPLIANCE.md +++ /dev/null @@ -1,398 +0,0 @@ - -# RSR (Rhodium Standard Repository) Compliance - -**Status**: 🥈 **Silver Level** ✅ | Targeting: 🥇 Gold Level - -This document tracks compliance with the Rhodium Standard Repository (RSR) framework. - -## Compliance Overview - -| Category | Status | Notes | -|----------|--------|-------| -| **Type Safety** | ✅ Bronze | PHP 8.1+, strict, Rust, | -| **Memory Safety** | ✅ Bronze | Rust ownership model, zero unsafe blocks in WASM | -| **Offline-First** | ✅ Bronze | No mandatory external dependencies, works air-gapped | -| **Documentation** | ✅ Bronze | 20+ markdown files, comprehensive coverage | -| **Security** | ✅ Silver | OWASP Top 10, seccomp, strict headers, CVE monitoring | -| **Testing** | ✅ Bronze | PHPUnit, Jest, Cargo tests with >80% coverage target | -| **CI/CD** | ✅ Bronze | GitHub Actions, GitLab CI, Dependabot, Renovate | -| **Licensing** | ✅ Bronze | GPL-3.0, clear LICENSE file | -| **Community** | ✅ Bronze | CoC, CONTRIBUTING.md, MAINTAINERS.md | -| **Accessibility** | ✅ Gold | WCAG 2.3 AAA compliance | -| **Interoperability** | ✅ Gold | 5 serialization formats, RPC, BEAM integration | - -**Overall**: Silver Level ✅ (11/11 categories at Bronze+, 3 at Silver+, 2 at Gold) - -## Detailed Compliance - -### 1. Type Safety ✅ Bronze - -**Requirement**: Static type checking in at least one primary language - -**Implementation**: -- ✅ **PHP 8.1+**: Strict types, declare(strict_types=1), type hints, return types -- ✅ ****: Strict mode enabled, no implicit any, all functions typed -- ✅ **Rust**: Compile-time type checking, no runtime type errors -- ✅ ****: Sound type system, type inference, no runtime exceptions -- ✅ **Elixir**: Typespecs with Dialyzer for static analysis - -**Verification**: -```bash -# PHP (WordPress Coding Standards) -composer install -./vendor/bin/phpcs --standard=WordPress . - -# -npm run lint:js - -# Rust -cd assets/wasm && cargo check - -# -npm run build: -``` - -### 2. Memory Safety ✅ Bronze - -**Requirement**: No memory corruption vulnerabilities (buffer overflows, use-after-free, etc.) - -**Implementation**: -- ✅ **Rust**: Ownership model, borrow checker, no unsafe blocks in lib.rs -- ✅ **PHP**: Memory-managed, no manual memory management -- ✅ **/JavaScript**: Garbage-collected, no manual memory management -- ✅ **Container**: Read-only filesystem, tmpfs for necessary writes - -**Verification**: -```bash -# Rust safety check -cd assets/wasm -cargo clippy -- -D warnings -cargo audit - -# Container security scan -podman scan sinople-theme:latest -``` - -### 3. Offline-First ✅ Bronze - -**Requirement**: No mandatory external dependencies, works without internet - -**Implementation**: -- ✅ **No external API calls** in core functionality -- ✅ **Service Worker**: Offline support with cache-first strategy -- ✅ **Local fonts**: System fonts, no Google Fonts by default -- ✅ **Consent-based external resources**: External embeds require user consent -- ✅ **Build system**: Can build completely offline (after initial npm install) - -**Verification**: -```bash -# Disconnect network -sudo ifconfig eth0 down - -# Build should still work (if node_modules exists) -npm run build - -# Theme should render (WordPress must be local) -``` - -### 4. Documentation ✅ Bronze - -**Requirement**: README, LICENSE, CONTRIBUTING, CODE_OF_CONDUCT, SECURITY - -**Implementation**: -- ✅ **README.md**: Comprehensive project overview, features, installation -- ✅ **LICENSE**: GPL-3.0 (code), CC BY 4.0 (content) -- ✅ **CONTRIBUTING.md**: Contribution guidelines, coding standards -- ✅ **CODE_OF_CONDUCT.md**: Contributor Covenant 2.1 + TPCF -- ✅ **SECURITY.md**: Vulnerability reporting, threat model, roadmap -- ✅ **MAINTAINERS.md**: Governance, decision-making, contact info -- ✅ **CHANGELOG.md**: All changes documented, semantic versioning -- ✅ **CLAUDE.md**: AI assistant guide, development guidelines -- ✅ **README-DEPLOYMENT.md**: Full deployment instructions -- ✅ **.well-known/security.txt**: RFC 9116 compliant -- ✅ **.well-known/ai.txt**: AI training policies -- ✅ **.well-known/humans.txt**: Human attribution, tech stack - -**Total**: 18 documentation files - -### 5. Security ✅ Silver (exceeds Bronze) - -**Requirement**: Basic security practices, no known vulnerabilities - -**Implementation**: -- ✅ **OWASP Top 10 2021**: All mitigations implemented -- ✅ **Security headers**: CSP, COEP, COOP, CORP, HSTS, Permissions-Policy -- ✅ **Container security**: Seccomp, AppArmor, capability dropping, non-root user -- ✅ **Input validation**: All user input sanitized, prepared statements -- ✅ **Dependency scanning**: npm audit, cargo audit, composer audit (manual) -- ✅ **CVE monitoring**: Chainguard Wolfi (continuously patched base images) -- ✅ **Vulnerability disclosure**: security.txt, SECURITY.md with 24h response SLA -- ✅ **Threat model**: Documented in SECURITY.md -- ⚠️ **Automated scanning**: Need to add Dependabot/Renovate (roadmap) - -### 6. Testing ✅ Bronze - -**Requirement**: Unit tests, integration tests, >80% coverage - -**Implementation**: -- ✅ **PHPUnit**: Comprehensive test suite for inc/ modules - - SinopleTestCase base class with WordPress test helpers - - test-setup.php: Reading time, post classes, query vars, rewrite rules - - test-semantic.php: JSON-LD, Open Graph, Twitter Cards, breadcrumbs - - test-accessibility.php: Skip links, ARIA attributes, screen reader text - - test-security.php: Security headers, CSP, input sanitization, nonces - - test-indieweb.php: Microformats, h-card, webmentions, JSON Feed, POSSE - - test-serialization.php: NDJSON, FlatBuffers, Cap'n Proto, BEAM interop -- ✅ **Jest**: /JavaScript test suite - - accessibility.test.ts: Font size controls, theme toggle, contrast mode - - features.test.ts: View Transitions, WASM, Container Queries, :has() - - wasm.test.ts: Reading time, HTML sanitization, password hashing -- ✅ **Cargo test**: Rust WASM test suite configured -- ✅ **Test infrastructure**: phpunit.xml, jest.config.js, bootstrap files -- ✅ **Coverage reporting**: HTML, text, clover, LCOV formats -- ✅ **CI integration**: Tests run on every push/PR - -**Verification**: -```bash -# PHP tests -composer install --dev -vendor/bin/phpunit --coverage-text --testdox - -# JavaScript tests -npm ci -npm test -- --coverage - -# Rust tests -cd assets/wasm && cargo test - -# All tests via justfile -just test -``` - -### 7. CI/CD ✅ Bronze - -**Requirement**: Automated builds, tests, linting, security scans - -**Implementation**: -- ✅ **GitHub Actions**: Comprehensive CI/CD pipeline - - `.github/workflows/ci.yml`: Multi-job parallel pipeline - - PHP linting (PHPCS, PHPStan) - - PHP tests (matrix: PHP 8.1/8.2/8.3 × WP 6.4/6.5/latest) - - JavaScript linting (ESLint, Stylelint) - - JavaScript tests (Jest with coverage) - - Rust tests (cargo test, clippy, rustfmt) - - Build assets (all languages) - - Security audit (npm, composer, cargo) - - Container build & Trivy scan - - Accessibility tests (Playwright) - - `.github/workflows/release.yml`: Automated releases - - Build production package - - Generate SBOM (CycloneDX) - - Container image build & push to GHCR - - Image signing with cosign -- ✅ **GitLab CI**: Complete pipeline with parallel jobs - - `.gitlab-ci.yml`: 5 stages (lint, test, security, build, deploy) - - PHP/JS/Rust linting in parallel - - PHP test matrix (3 PHP versions) - - Security audits (npm, composer, cargo, Trivy) - - Container builds - - Manual deployment to dev/prod -- ✅ **Dependabot**: Automated dependency updates - - `.github/dependabot.yml`: npm, composer, cargo, GitHub Actions - - Weekly schedule - - Auto-merge for patches/minors -- ✅ **Renovate**: Alternative dependency manager - - `.github/renovate.json`: Grouped updates, vulnerability alerts -- ✅ **Build automation**: justfile with 40+ recipes -- ✅ **Coverage reporting**: Codecov integration - -**Verification**: -```bash -# Trigger CI locally (requires act) -act push - -# View workflows -gh workflow list - -# Manual justfile commands -just check # Quick validation -just test # All tests -just build # Production build -``` - -### 8. Licensing ✅ Bronze - -**Requirement**: Clear, OSI-approved license - -**Implementation**: -- ✅ **LICENSE file**: GPL-3.0-or-later (OSI-approved) -- ✅ **License headers**: All PHP files have GPL-3.0 header -- ✅ **Dual licensing**: Code (GPL-3.0), content/docs (CC BY 4.0) -- ✅ **Dependency licensing**: All compatible with GPL-3.0 -- ✅ **License documentation**: README, CLAUDE.md, humans.txt - -### 9. Community ✅ Bronze - -**Requirement**: Code of Conduct, contribution guidelines, maintainer info - -**Implementation**: -- ✅ **CODE_OF_CONDUCT.md**: Contributor Covenant 2.1 -- ✅ **CONTRIBUTING.md**: Detailed contribution guidelines -- ✅ **MAINTAINERS.md**: Governance model, contact info -- ✅ **TPCF**: Tri-Perimeter Contribution Framework implemented - - Perimeter 1 (Inner Sanctum): Maintainers only - - Perimeter 2 (Trusted Contributors): Collaborators with write access - - Perimeter 3 (Community Sandbox): Open contribution (current level) -- ✅ **Issue templates**: (Would add in GitHub/GitLab) -- ✅ **PR templates**: (Would add in GitHub/GitLab) - -### 10. Accessibility ✅ Gold (exceeds Silver) - -**Requirement**: Basic keyboard navigation, WCAG 2.1 AA minimum - -**Implementation**: -- ✅ **WCAG 2.3 AAA**: Highest accessibility standard -- ✅ **Keyboard navigation**: All interactive elements keyboard-accessible -- ✅ **Screen reader**: Full ARIA support, semantic HTML -- ✅ **Focus indicators**: Visible 3px outline, customizable -- ✅ **Color contrast**: AAA ratios (7:1 for normal text, 4.5:1 for large) -- ✅ **Motion**: prefers-reduced-motion respected -- ✅ **Font sizing**: User-adjustable (80%-150%) -- ✅ **Dark mode**: System preference + manual toggle -- ✅ **High contrast**: Manual toggle for enhanced visibility -- ✅ **Skip links**: To main content, navigation, footer -- ✅ **Semantic HTML**: Proper heading hierarchy, landmarks - -### 11. Interoperability ✅ Gold (exceeds Silver) - -**Requirement**: Standard formats, documented APIs - -**Implementation**: -- ✅ **Multiple serialization formats**: - - NDJSON (streaming, line-delimited JSON) - - FlatBuffers (zero-copy, cross-language) - - Cap'n Proto (RPC, highest performance) - - JSON-LD (semantic web) - - RDF/Turtle (linked data) -- ✅ **Standard protocols**: - - HTTP/2, HTTP/3 (QUIC) - - REST APIs (WordPress) - - RPC (Cap'n Proto) - - SSE (Server-Sent Events for streaming) - - WebSockets-ready (via RabbitMQ) -- ✅ **BEAM integration**: Ecto schemas, RabbitMQ consumer, Elixir/Erlang interop -- ✅ **Microformats v2**: h-entry, h-card, IndieWeb-compliant -- ✅ **Open standards**: Schema.org, Open Graph, Dublin Core, FOAF -- ✅ **VoID dataset**: Machine-readable dataset description - -## TPCF Implementation - -### Perimeter 3: Community Sandbox ✅ (Current) -- **Access**: Public fork, PR submission, issue reporting -- **Security**: No write access to main repository -- **Emotional Safety**: No judgment, experimentation encouraged -- **Reversibility**: All contributions can be reverted if issues arise - -**Current Status**: Open for community contributions - -### Perimeter 2: Trusted Contributors (Roadmap) -- **Requirements**: 5+ merged PRs, 3+ months consistent participation -- **Access**: Write access to feature branches, PR review rights -- **Timeline**: After 3-6 months of active contribution - -### Perimeter 1: Inner Sanctum (Maintainers Only) -- **Current**: 1 maintainer (Jonathan/@hyperpolymath) -- **Access**: Write access to main branch, release management -- **Responsibilities**: Security, releases, governance, community - -## Silver Level Achievement ✅ - -**Achieved**: 2025-01-23 - -### Completed Requirements -1. ✅ **Testing**: Automated test suite implemented - - PHPUnit: 6 test classes covering all inc/ modules - - Jest: 3 test suites for modules - - Cargo test: Rust WASM testing configured - - Coverage reporting: HTML, text, clover, LCOV -2. ✅ **CI/CD**: Complete pipelines operational - - GitHub Actions: Multi-job CI with matrix testing - - GitLab CI: 5-stage pipeline with parallel jobs - - Automated releases with SBOM generation - - Container signing with cosign -3. ✅ **Dependency automation**: Fully configured - - Dependabot: npm, composer, cargo, GitHub Actions - - Renovate: Grouped updates, vulnerability alerts -4. ✅ **Build system**: Modern justfile with 40+ recipes - -## Roadmap to Gold Level - -**Target**: Q4 2025 - -### Requirements -1. **Formal verification**: SPARK proofs for critical security functions -2. **Fuzzing**: AFL/libFuzzer for input validation -3. **Third-party audit**: External security audit -4. **SBOM**: Automated Software Bill of Materials generation -5. **Signed releases**: cosign/sigstore container signing -6. **Community metrics**: Active contributors, response times, issue resolution - -## Verification Commands - -```bash -# Clone repository -git clone https://github.com/hyperpolymath/sinople-theme -cd sinople-theme - -# Check offline capability (must have node_modules first) -npm ci # Install dependencies -npm run build # Should work offline after this - -# Run linting -npm run lint - -# Check security -npm audit -cargo audit (in assets/wasm/) - -# Build containers -podman build -t sinople-theme:test -f Containerfile . - -# Scan container -podman scan sinople-theme:test - -# Check accessibility -# (Manual: Use WAVE, axe DevTools in browser) - -# Verify serialization endpoints -curl https://your-domain.com/feed/ndjson -curl https://your-domain.com/feed/capnproto?cp_format=json -curl https://your-domain.com/void.rdf -``` - -## Compliance Checklist - -- [x] Type Safety (Bronze) ✅ -- [x] Memory Safety (Bronze) ✅ -- [x] Offline-First (Bronze) ✅ -- [x] Documentation (Bronze) ✅ - 20+ files -- [x] Security (Silver) ✅ - Exceeds Bronze -- [x] Testing (Bronze) ✅ - PHPUnit, Jest, Cargo -- [x] CI/CD (Bronze) ✅ - GitHub Actions, GitLab CI, Dependabot -- [x] Licensing (Bronze) ✅ -- [x] Community (Bronze) ✅ -- [x] Accessibility (Gold) ✅ - WCAG 2.3 AAA -- [x] Interoperability (Gold) ✅ - 5 serialization formats - -**Current Level**: 🥈 Silver (11/11 categories at Bronze+) -**Next Target**: 🥇 Gold (formal verification, fuzzing, third-party audit) - ---- - -**Last Updated**: 2025-01-23 -**Silver Level Achieved**: 2025-01-23 -**Verified By**: Jonathan (@hyperpolymath) + Claude (Anthropic AI) -**Next Review**: 2025-02-23 (monthly) diff --git a/journal-theme/RSR-SILVER-ACHIEVEMENT.adoc b/journal-theme/RSR-SILVER-ACHIEVEMENT.adoc new file mode 100644 index 0000000..3fb62ce --- /dev/null +++ b/journal-theme/RSR-SILVER-ACHIEVEMENT.adoc @@ -0,0 +1,414 @@ +== 🥈 RSR Silver Level Achievement Report + +*Date*: 2025-01-23 *Status*: *ACHIEVED* ✅ *Level*: Silver (11/11 +categories at Bronze or higher) *Previous Level*: Bronze (9/11 +categories) + +''''' + +=== Executive Summary + +The Sinople WordPress theme has successfully achieved *RSR Silver Level +compliance*, meeting all 11 required categories at Bronze level or +higher. This represents a significant milestone in software quality, +security, and maintainability. + +==== Key Achievements + +* ✅ *Comprehensive automated testing* across 3 programming languages +* ✅ *Multi-platform CI/CD pipelines* (GitHub Actions + GitLab CI) +* ✅ *Automated dependency management* (Dependabot + Renovate) +* ✅ *Modern build system* (justfile with 40+ recipes) +* ✅ *All tests passing* with >80% coverage targets +* ✅ *Security automation* (Trivy, dependency audits, SBOM generation) + +''''' + +=== Compliance Scorecard + +[cols=",,,",options="header",] +|=== +|Category |Level |Status |Change +|Type Safety |Bronze |✅ |Maintained +|Memory Safety |Bronze |✅ |Maintained +|Offline-First |Bronze |✅ |Maintained +|Documentation |Bronze |✅ |Enhanced (+2 files) +|Security |*Silver* |✅ |Maintained +|*Testing* |Bronze |✅ |*NEW* ⬆️ +|*CI/CD* |Bronze |✅ |*NEW* ⬆️ +|Licensing |Bronze |✅ |Maintained +|Community |Bronze |✅ |Maintained +|Accessibility |*Gold* |✅ |Maintained +|Interoperability |*Gold* |✅ |Maintained +|=== + +*Overall*: 11/11 Bronze+ (100%), 3/11 Silver+ (27%), 2/11 Gold (18%) + +''''' + +=== What Changed + +==== 1. Testing Infrastructure (Bronze ✅) + +*Previous*: Manual testing only *Now*: Comprehensive automated test +suites + +===== PHPUnit (PHP Testing) + +* *6 test classes* covering all `+inc/+` modules +* *100+ test methods* for theme functionality +* *WordPress integration* via test suite +* *Coverage reporting* in multiple formats (HTML, text, clover) + +Files created: - `+phpunit.xml+` - PHPUnit configuration - +`+tests/bootstrap.php+` - WordPress test suite loader - +`+tests/php/SinopleTestCase.php+` - Base test class with helpers - +`+tests/php/test-setup.php+` - Setup & utility tests - +`+tests/php/test-semantic.php+` - Semantic web tests - +`+tests/php/test-accessibility.php+` - WCAG compliance tests - +`+tests/php/test-security.php+` - Security tests - +`+tests/php/test-indieweb.php+` - IndieWeb tests - +`+tests/php/test-serialization.php+` - Serialization tests - +`+bin/install-wp-tests.sh+` - WordPress test suite installer + +===== Jest (JavaScript/ Testing) + +* *3 comprehensive test suites* for browser features +* *Mocked environment* (localStorage, matchMedia, observers) +* *80% coverage target* with threshold enforcement + +Files created: - `+jest.config.js+` - Jest configuration with ts-jest - +`+tests/js/setup.ts+` - Test environment setup - +`+tests/js/accessibility.test.ts+` - Accessibility controls tests - +`+tests/js/features.test.ts+` - Feature detection tests - +`+tests/js/wasm.test.ts+` - WebAssembly integration tests + +===== Cargo (Rust/WASM Testing) + +* Configured for `+wasm32-unknown-unknown+` target +* Integrated into CI pipeline + +==== 2. CI/CD Pipelines (Bronze ✅) + +*Previous*: Manual builds and deploys *Now*: Fully automated +multi-platform CI/CD + +===== GitHub Actions + +Created `+.github/workflows/ci.yml+` with *10 parallel jobs*: + +[arabic] +. *PHP Lint*: PHPCS + PHPStan with WordPress standards +. *PHP Tests*: Matrix (PHP 8.1/8.2/8.3 × WordPress 6.4/6.5/latest) = 9 +jobs +. *JavaScript Lint*: ESLint + Stylelint +. *JavaScript Tests*: Jest with coverage upload to Codecov +. *Rust Tests*: cargo test + clippy + rustfmt +. *Build*: Compile all assets (SCSS, , WASM, ) +. *Security Audit*: npm audit + composer audit + cargo audit +. *Container*: Docker build + Trivy vulnerability scan +. *Accessibility*: Playwright tests (placeholder) + +Created `+.github/workflows/release.yml+` for *automated releases*: - +Production asset compilation - Distribution package creation - SBOM +generation (CycloneDX) - Container image push to GitHub Container +Registry - *Image signing with cosign* (supply chain security) + +===== GitLab CI + +Created `+.gitlab-ci.yml+` with *5-stage pipeline*: + +*Stages*: 1. *Lint* (parallel): PHP, JavaScript, Rust 2. *Test* +(parallel): PHP matrix, Jest, Cargo 3. *Security* (parallel): +npm/composer/cargo audit, Trivy 4. *Build*: Assets, containers, SBOM 5. +*Deploy*: Manual dev/prod deployment + +*Features*: - Parallel job execution for speed - Test matrix for +compatibility validation - Coverage reporting with badges - Artifact +caching for dependencies - Manual deployment gates + +===== Dependency Automation + +Created `+.github/dependabot.yml+`: - *4 package ecosystems*: npm, +composer, cargo, GitHub Actions - *Weekly schedule*: Mondays at 9am UTC +- *Auto-merge*: Patches and minors - *Security alerts*: Immediate +notifications - *Grouped updates*: By category (testing, linting, build +tools) + +Created `+.github/renovate.json+`: - *Alternative* to Dependabot with +more features - *OSV vulnerability alerts*: Real-time security +notifications - *Lock file maintenance*: Monthly updates - *Semantic +commits*: Conventional commit format - *Grouped updates*: WordPress +packages, testing libraries, etc. + +==== 3. Build System Enhancement + +Created `+justfile+` (modern alternative to Makefile): - *40+ recipes* +for all development tasks - *Self-documenting*: `+just --list+` shows +all commands - *Categories*: - Build & Development: `+build+`, `+dev+`, +`+clean+`, `+watch+` - Testing: `+test+`, `+test-php+`, `+test-js+`, +`+test-rust+` - Linting: `+lint+`, `+lint-php+`, `+lint-js+`, +`+lint-rust+` - Security: `+audit+`, `+scan+` - Containers: +`+container-build+`, `+container-dev+`, `+container-prod+` - Deployment: +`+deploy-dev+`, `+deploy-prod+` - Documentation: `+docs+`, +`+serve-docs+` - Utilities: `+install+`, `+update+`, `+outdated+`, +`+release+`, `+package+` - *RSR validation*: `+validate+` (checks +compliance) + +==== 4. Configuration Files + +*Created*: - `+composer.json+`: PHP dependency management with dev +dependencies - PHPUnit 10.5, PHPCS, PHPStan, WordPress standards - +Autoloading for all `+inc/+` modules - Scripts: `+lint+`, `+analyze+`, +`+test+`, `+audit+` - `+phpstan.neon+`: Level 8 static analysis +(strictest) - `+package.json+`: Updated with Jest dependencies and test +scripts - jest, ts-jest, @testing-library, identity-obj-proxy - Scripts: +`+test+`, `+test:watch+`, `+test:coverage+`, `+test:ci+` + +==== 5. Documentation + +*Created*: - `+TESTING.md+` (300+ lines): Comprehensive testing guide - +Prerequisites and setup - Running tests (all languages) - Test structure +and organization - Coverage targets and checking - Writing new tests +(examples) - Debugging tests - CI integration - Best practices + +*Updated*: - `+RSR-COMPLIANCE.md+`: Complete rewrite of Testing and +CI/CD sections - Detailed implementation notes - Verification commands - +Silver Level Achievement section - Updated compliance checklist (all 11 +items checked) - Roadmap to Gold Level + +''''' + +=== How to Use + +==== Running Tests Locally + +[source,bash] +---- +# Quick validation (recommended before commit) +just check + +# Run all tests +just test + +# Run specific test suites +just test-php # PHPUnit tests +just test-js # Jest tests +just test-rust # Cargo tests + +# With coverage reports +vendor/bin/phpunit --coverage-text --testdox +npm run test:coverage +---- + +==== CI/CD + +*Automatic triggers*: - Every push to `+main+` or `+develop+` - Every +pull request - Weekly schedule (Mondays 9am UTC) - Tagged releases +(v__.__) + +*Manual triggers*: + +[source,bash] +---- +# Trigger GitHub Actions locally (requires 'act') +act push + +# View workflow runs +gh run list + +# Deploy to development (manual approval required) +just deploy-dev + +# Deploy to production (manual approval required) +just deploy-prod +---- + +==== Dependency Updates + +*Automatic* (via Dependabot/Renovate): - Pull requests created weekly +for updates - Auto-merged for patches/minors (after tests pass) - +Security alerts create immediate PRs + +*Manual*: + +[source,bash] +---- +# Check for outdated dependencies +just outdated + +# Update all dependencies +just update + +# Audit for vulnerabilities +just audit +---- + +''''' + +=== Statistics + +==== Files Created/Modified + +* *26 files changed* +* *3,484 insertions* +* *74 deletions* + +==== New Files by Category + +*Testing* (13 files): - 1 PHPUnit config - 1 Jest config - 1 PHPStan +config - 7 PHP test classes - 4 JavaScript test files + +*CI/CD* (5 files): - 2 GitHub Actions workflows - 1 GitLab CI config - 1 +Dependabot config - 1 Renovate config + +*Build* (2 files): - 1 Justfile - 1 Composer config + +*Documentation* (2 files): - 1 TESTING.md - 1 RSR-SILVER-ACHIEVEMENT.md +(this file) + +*Scripts* (1 file): - 1 WordPress test installer + +*Modified* (2 files): - package.json (Jest dependencies) - +RSR-COMPLIANCE.md (Silver achievement) + +==== Test Coverage + +*PHPUnit*: - 6 test classes - 100+ test methods - Targets: >80% line +coverage, >80% branch coverage + +*Jest*: - 3 test suites - 30+ test cases - Enforced thresholds: 80% +branches/functions/lines/statements + +*Total*: - 3 programming languages tested - 9 PHP versions × WordPress +versions matrix = extensive compatibility - Parallel execution for speed + +''''' + +=== What This Means + +==== For Development + +✅ *Confidence in changes*: Every commit tested automatically ✅ *Fast +feedback*: Parallel CI jobs complete in <10 minutes ✅ *Consistent +quality*: Same tests run locally and in CI ✅ *Easy onboarding*: +`+just --list+` shows all commands ✅ *Dependency safety*: Automatic +security updates + +==== For Security + +✅ *Vulnerability scanning*: Trivy scans container images ✅ *Dependency +audits*: npm/composer/cargo audit on every push ✅ *SBOM generation*: +Software Bill of Materials for supply chain ✅ *Image signing*: Cosign +signatures for container trust ✅ *Automated updates*: Dependabot for +security patches + +==== For Compliance + +✅ *Auditable*: All tests documented and reproducible ✅ *Verifiable*: +CI logs prove tests ran and passed ✅ *Automated*: No manual steps +required ✅ *Comprehensive*: 11/11 categories at Bronze or higher ✅ +*Industry standards*: OWASP, WCAG 2.3 AAA, GPL-3.0 + +==== For Users + +✅ *Higher quality*: Bugs caught before release ✅ *Better +accessibility*: WCAG 2.3 AAA validated ✅ *Security*: Vulnerabilities +detected and patched quickly ✅ *Stability*: Regression tests prevent +breaking changes ✅ *Trust*: Transparent testing and compliance + +''''' + +=== Roadmap to Gold Level + +*Target*: Q4 2025 + +==== Requirements for Gold + +[arabic] +. *Formal Verification*: SPARK proofs for critical security functions +. *Fuzzing*: AFL/libFuzzer for input validation +. *Third-Party Audit*: External security audit with report +. *SBOM Automation*: Continuous SBOM generation and publishing +. *Community Metrics*: Active contributors, response times, issue +resolution + +==== Estimated Effort + +* Formal verification: 80 hours +* Fuzzing infrastructure: 40 hours +* Third-party audit: External ($5,000-$15,000) +* SBOM automation: 16 hours (already partially done) +* Community metrics: 24 hours + +*Total*: ~160 hours + external audit + +''''' + +=== Verification + +==== RSR Silver Level Checklist + +* [x] *Type Safety* (Bronze) ✅ +* [x] *Memory Safety* (Bronze) ✅ +* [x] *Offline-First* (Bronze) ✅ +* [x] *Documentation* (Bronze) ✅ +* [x] *Security* (Silver) ✅ +* [x] *Testing* (Bronze) ✅ ← *NEW* +* [x] *CI/CD* (Bronze) ✅ ← *NEW* +* [x] *Licensing* (Bronze) ✅ +* [x] *Community* (Bronze) ✅ +* [x] *Accessibility* (Gold) ✅ +* [x] *Interoperability* (Gold) ✅ + +*Result*: 11/11 categories at Bronze or higher = *Silver Level* ✅ + +==== Commands to Verify + +[source,bash] +---- +# Check all tests pass +just test + +# Validate RSR compliance +just validate + +# Check build works +just build + +# Audit security +just audit + +# View CI status (GitHub) +gh workflow view ci + +# View test coverage +vendor/bin/phpunit --coverage-text +npm run test:coverage +---- + +''''' + +=== Conclusion + +The Sinople WordPress theme has successfully achieved *RSR Silver Level +compliance*, demonstrating: + +* *Automated quality assurance* across multiple languages +* *Security-first development* with continuous scanning +* *Professional CI/CD* on multiple platforms +* *Comprehensive testing* with high coverage targets +* *Modern build tooling* for developer experience +* *Industry-standard compliance* (WCAG, OWASP, GPL) + +This achievement provides a *solid foundation* for: - Future Gold level +certification - Third-party security audits - Enterprise adoption - Open +source contribution - WordPress.org theme directory submission + +*Verified by*: Jonathan (@hyperpolymath) + Claude (Anthropic AI) +*Achievement Date*: 2025-01-23 *Commit*: 7217396 *Branch*: +`+claude/create-claude-md-01EywDFR5aHnSVtZhshCXxqc+` + +''''' + +🎉 *Congratulations on achieving RSR Silver Level!* 🥈 diff --git a/journal-theme/RSR-SILVER-ACHIEVEMENT.md b/journal-theme/RSR-SILVER-ACHIEVEMENT.md deleted file mode 100644 index 53c6149..0000000 --- a/journal-theme/RSR-SILVER-ACHIEVEMENT.md +++ /dev/null @@ -1,449 +0,0 @@ - -# 🥈 RSR Silver Level Achievement Report - -**Date**: 2025-01-23 -**Status**: **ACHIEVED** ✅ -**Level**: Silver (11/11 categories at Bronze or higher) -**Previous Level**: Bronze (9/11 categories) - ---- - -## Executive Summary - -The Sinople WordPress theme has successfully achieved **RSR Silver Level compliance**, meeting all 11 required categories at Bronze level or higher. This represents a significant milestone in software quality, security, and maintainability. - -### Key Achievements - -- ✅ **Comprehensive automated testing** across 3 programming languages -- ✅ **Multi-platform CI/CD pipelines** (GitHub Actions + GitLab CI) -- ✅ **Automated dependency management** (Dependabot + Renovate) -- ✅ **Modern build system** (justfile with 40+ recipes) -- ✅ **All tests passing** with >80% coverage targets -- ✅ **Security automation** (Trivy, dependency audits, SBOM generation) - ---- - -## Compliance Scorecard - -| Category | Level | Status | Change | -|----------|-------|--------|--------| -| Type Safety | Bronze | ✅ | Maintained | -| Memory Safety | Bronze | ✅ | Maintained | -| Offline-First | Bronze | ✅ | Maintained | -| Documentation | Bronze | ✅ | Enhanced (+2 files) | -| Security | **Silver** | ✅ | Maintained | -| **Testing** | Bronze | ✅ | **NEW** ⬆️ | -| **CI/CD** | Bronze | ✅ | **NEW** ⬆️ | -| Licensing | Bronze | ✅ | Maintained | -| Community | Bronze | ✅ | Maintained | -| Accessibility | **Gold** | ✅ | Maintained | -| Interoperability | **Gold** | ✅ | Maintained | - -**Overall**: 11/11 Bronze+ (100%), 3/11 Silver+ (27%), 2/11 Gold (18%) - ---- - -## What Changed - -### 1. Testing Infrastructure (Bronze ✅) - -**Previous**: Manual testing only -**Now**: Comprehensive automated test suites - -#### PHPUnit (PHP Testing) -- **6 test classes** covering all `inc/` modules -- **100+ test methods** for theme functionality -- **WordPress integration** via test suite -- **Coverage reporting** in multiple formats (HTML, text, clover) - -Files created: -- `phpunit.xml` - PHPUnit configuration -- `tests/bootstrap.php` - WordPress test suite loader -- `tests/php/SinopleTestCase.php` - Base test class with helpers -- `tests/php/test-setup.php` - Setup & utility tests -- `tests/php/test-semantic.php` - Semantic web tests -- `tests/php/test-accessibility.php` - WCAG compliance tests -- `tests/php/test-security.php` - Security tests -- `tests/php/test-indieweb.php` - IndieWeb tests -- `tests/php/test-serialization.php` - Serialization tests -- `bin/install-wp-tests.sh` - WordPress test suite installer - -#### Jest (JavaScript/ Testing) -- **3 comprehensive test suites** for browser features -- **Mocked environment** (localStorage, matchMedia, observers) -- **80% coverage target** with threshold enforcement - -Files created: -- `jest.config.js` - Jest configuration with ts-jest -- `tests/js/setup.ts` - Test environment setup -- `tests/js/accessibility.test.ts` - Accessibility controls tests -- `tests/js/features.test.ts` - Feature detection tests -- `tests/js/wasm.test.ts` - WebAssembly integration tests - -#### Cargo (Rust/WASM Testing) -- Configured for `wasm32-unknown-unknown` target -- Integrated into CI pipeline - -### 2. CI/CD Pipelines (Bronze ✅) - -**Previous**: Manual builds and deploys -**Now**: Fully automated multi-platform CI/CD - -#### GitHub Actions -Created `.github/workflows/ci.yml` with **10 parallel jobs**: - -1. **PHP Lint**: PHPCS + PHPStan with WordPress standards -2. **PHP Tests**: Matrix (PHP 8.1/8.2/8.3 × WordPress 6.4/6.5/latest) = 9 jobs -3. **JavaScript Lint**: ESLint + Stylelint -4. **JavaScript Tests**: Jest with coverage upload to Codecov -5. **Rust Tests**: cargo test + clippy + rustfmt -6. **Build**: Compile all assets (SCSS, , WASM, ) -7. **Security Audit**: npm audit + composer audit + cargo audit -8. **Container**: Docker build + Trivy vulnerability scan -9. **Accessibility**: Playwright tests (placeholder) - -Created `.github/workflows/release.yml` for **automated releases**: -- Production asset compilation -- Distribution package creation -- SBOM generation (CycloneDX) -- Container image push to GitHub Container Registry -- **Image signing with cosign** (supply chain security) - -#### GitLab CI -Created `.gitlab-ci.yml` with **5-stage pipeline**: - -**Stages**: -1. **Lint** (parallel): PHP, JavaScript, Rust -2. **Test** (parallel): PHP matrix, Jest, Cargo -3. **Security** (parallel): npm/composer/cargo audit, Trivy -4. **Build**: Assets, containers, SBOM -5. **Deploy**: Manual dev/prod deployment - -**Features**: -- Parallel job execution for speed -- Test matrix for compatibility validation -- Coverage reporting with badges -- Artifact caching for dependencies -- Manual deployment gates - -#### Dependency Automation - -Created `.github/dependabot.yml`: -- **4 package ecosystems**: npm, composer, cargo, GitHub Actions -- **Weekly schedule**: Mondays at 9am UTC -- **Auto-merge**: Patches and minors -- **Security alerts**: Immediate notifications -- **Grouped updates**: By category (testing, linting, build tools) - -Created `.github/renovate.json`: -- **Alternative** to Dependabot with more features -- **OSV vulnerability alerts**: Real-time security notifications -- **Lock file maintenance**: Monthly updates -- **Semantic commits**: Conventional commit format -- **Grouped updates**: WordPress packages, testing libraries, etc. - -### 3. Build System Enhancement - -Created `justfile` (modern alternative to Makefile): -- **40+ recipes** for all development tasks -- **Self-documenting**: `just --list` shows all commands -- **Categories**: - - Build & Development: `build`, `dev`, `clean`, `watch` - - Testing: `test`, `test-php`, `test-js`, `test-rust` - - Linting: `lint`, `lint-php`, `lint-js`, `lint-rust` - - Security: `audit`, `scan` - - Containers: `container-build`, `container-dev`, `container-prod` - - Deployment: `deploy-dev`, `deploy-prod` - - Documentation: `docs`, `serve-docs` - - Utilities: `install`, `update`, `outdated`, `release`, `package` - - **RSR validation**: `validate` (checks compliance) - -### 4. Configuration Files - -**Created**: -- `composer.json`: PHP dependency management with dev dependencies - - PHPUnit 10.5, PHPCS, PHPStan, WordPress standards - - Autoloading for all `inc/` modules - - Scripts: `lint`, `analyze`, `test`, `audit` -- `phpstan.neon`: Level 8 static analysis (strictest) -- `package.json`: Updated with Jest dependencies and test scripts - - jest, ts-jest, @testing-library, identity-obj-proxy - - Scripts: `test`, `test:watch`, `test:coverage`, `test:ci` - -### 5. Documentation - -**Created**: -- `TESTING.md` (300+ lines): Comprehensive testing guide - - Prerequisites and setup - - Running tests (all languages) - - Test structure and organization - - Coverage targets and checking - - Writing new tests (examples) - - Debugging tests - - CI integration - - Best practices - -**Updated**: -- `RSR-COMPLIANCE.md`: Complete rewrite of Testing and CI/CD sections - - Detailed implementation notes - - Verification commands - - Silver Level Achievement section - - Updated compliance checklist (all 11 items checked) - - Roadmap to Gold Level - ---- - -## How to Use - -### Running Tests Locally - -```bash -# Quick validation (recommended before commit) -just check - -# Run all tests -just test - -# Run specific test suites -just test-php # PHPUnit tests -just test-js # Jest tests -just test-rust # Cargo tests - -# With coverage reports -vendor/bin/phpunit --coverage-text --testdox -npm run test:coverage -``` - -### CI/CD - -**Automatic triggers**: -- Every push to `main` or `develop` -- Every pull request -- Weekly schedule (Mondays 9am UTC) -- Tagged releases (v*.*) - -**Manual triggers**: -```bash -# Trigger GitHub Actions locally (requires 'act') -act push - -# View workflow runs -gh run list - -# Deploy to development (manual approval required) -just deploy-dev - -# Deploy to production (manual approval required) -just deploy-prod -``` - -### Dependency Updates - -**Automatic** (via Dependabot/Renovate): -- Pull requests created weekly for updates -- Auto-merged for patches/minors (after tests pass) -- Security alerts create immediate PRs - -**Manual**: -```bash -# Check for outdated dependencies -just outdated - -# Update all dependencies -just update - -# Audit for vulnerabilities -just audit -``` - ---- - -## Statistics - -### Files Created/Modified - -- **26 files changed** -- **3,484 insertions** -- **74 deletions** - -### New Files by Category - -**Testing** (13 files): -- 1 PHPUnit config -- 1 Jest config -- 1 PHPStan config -- 7 PHP test classes -- 4 JavaScript test files - -**CI/CD** (5 files): -- 2 GitHub Actions workflows -- 1 GitLab CI config -- 1 Dependabot config -- 1 Renovate config - -**Build** (2 files): -- 1 Justfile -- 1 Composer config - -**Documentation** (2 files): -- 1 TESTING.md -- 1 RSR-SILVER-ACHIEVEMENT.md (this file) - -**Scripts** (1 file): -- 1 WordPress test installer - -**Modified** (2 files): -- package.json (Jest dependencies) -- RSR-COMPLIANCE.md (Silver achievement) - -### Test Coverage - -**PHPUnit**: -- 6 test classes -- 100+ test methods -- Targets: >80% line coverage, >80% branch coverage - -**Jest**: -- 3 test suites -- 30+ test cases -- Enforced thresholds: 80% branches/functions/lines/statements - -**Total**: -- 3 programming languages tested -- 9 PHP versions × WordPress versions matrix = extensive compatibility -- Parallel execution for speed - ---- - -## What This Means - -### For Development - -✅ **Confidence in changes**: Every commit tested automatically -✅ **Fast feedback**: Parallel CI jobs complete in <10 minutes -✅ **Consistent quality**: Same tests run locally and in CI -✅ **Easy onboarding**: `just --list` shows all commands -✅ **Dependency safety**: Automatic security updates - -### For Security - -✅ **Vulnerability scanning**: Trivy scans container images -✅ **Dependency audits**: npm/composer/cargo audit on every push -✅ **SBOM generation**: Software Bill of Materials for supply chain -✅ **Image signing**: Cosign signatures for container trust -✅ **Automated updates**: Dependabot for security patches - -### For Compliance - -✅ **Auditable**: All tests documented and reproducible -✅ **Verifiable**: CI logs prove tests ran and passed -✅ **Automated**: No manual steps required -✅ **Comprehensive**: 11/11 categories at Bronze or higher -✅ **Industry standards**: OWASP, WCAG 2.3 AAA, GPL-3.0 - -### For Users - -✅ **Higher quality**: Bugs caught before release -✅ **Better accessibility**: WCAG 2.3 AAA validated -✅ **Security**: Vulnerabilities detected and patched quickly -✅ **Stability**: Regression tests prevent breaking changes -✅ **Trust**: Transparent testing and compliance - ---- - -## Roadmap to Gold Level - -**Target**: Q4 2025 - -### Requirements for Gold - -1. **Formal Verification**: SPARK proofs for critical security functions -2. **Fuzzing**: AFL/libFuzzer for input validation -3. **Third-Party Audit**: External security audit with report -4. **SBOM Automation**: Continuous SBOM generation and publishing -5. **Community Metrics**: Active contributors, response times, issue resolution - -### Estimated Effort - -- Formal verification: 80 hours -- Fuzzing infrastructure: 40 hours -- Third-party audit: External ($5,000-$15,000) -- SBOM automation: 16 hours (already partially done) -- Community metrics: 24 hours - -**Total**: ~160 hours + external audit - ---- - -## Verification - -### RSR Silver Level Checklist - -- [x] **Type Safety** (Bronze) ✅ -- [x] **Memory Safety** (Bronze) ✅ -- [x] **Offline-First** (Bronze) ✅ -- [x] **Documentation** (Bronze) ✅ -- [x] **Security** (Silver) ✅ -- [x] **Testing** (Bronze) ✅ ← **NEW** -- [x] **CI/CD** (Bronze) ✅ ← **NEW** -- [x] **Licensing** (Bronze) ✅ -- [x] **Community** (Bronze) ✅ -- [x] **Accessibility** (Gold) ✅ -- [x] **Interoperability** (Gold) ✅ - -**Result**: 11/11 categories at Bronze or higher = **Silver Level** ✅ - -### Commands to Verify - -```bash -# Check all tests pass -just test - -# Validate RSR compliance -just validate - -# Check build works -just build - -# Audit security -just audit - -# View CI status (GitHub) -gh workflow view ci - -# View test coverage -vendor/bin/phpunit --coverage-text -npm run test:coverage -``` - ---- - -## Conclusion - -The Sinople WordPress theme has successfully achieved **RSR Silver Level compliance**, demonstrating: - -- **Automated quality assurance** across multiple languages -- **Security-first development** with continuous scanning -- **Professional CI/CD** on multiple platforms -- **Comprehensive testing** with high coverage targets -- **Modern build tooling** for developer experience -- **Industry-standard compliance** (WCAG, OWASP, GPL) - -This achievement provides a **solid foundation** for: -- Future Gold level certification -- Third-party security audits -- Enterprise adoption -- Open source contribution -- WordPress.org theme directory submission - -**Verified by**: Jonathan (@hyperpolymath) + Claude (Anthropic AI) -**Achievement Date**: 2025-01-23 -**Commit**: 7217396 -**Branch**: `claude/create-claude-md-01EywDFR5aHnSVtZhshCXxqc` - ---- - -🎉 **Congratulations on achieving RSR Silver Level!** 🥈 diff --git a/journal-theme/SECURITY.adoc b/journal-theme/SECURITY.adoc new file mode 100644 index 0000000..fad64a1 --- /dev/null +++ b/journal-theme/SECURITY.adoc @@ -0,0 +1,207 @@ +== Security Policy + +=== Supported Versions + +[cols=",",options="header",] +|=== +|Version |Supported +|0.1.x |:white_check_mark: +|=== + +=== Security Model + +Sinople theme implements defense-in-depth with multiple security layers: + +==== 1. *Strict Security Headers* + +* Content-Security-Policy (CSP) with `+wasm-unsafe-eval+` only (no +`+unsafe-inline+`, no `+unsafe-eval+`) +* Cross-Origin-Embedder-Policy (COEP): `+require-corp+` +* Cross-Origin-Opener-Policy (COOP): `+same-origin+` +* Cross-Origin-Resource-Policy (CORP): `+same-origin+` +* Strict-Transport-Security (HSTS) with preload +* Permissions-Policy (all dangerous features disabled) + +==== 2. *Container Security* + +* *Chainguard Wolfi* base images (supply chain verified) +* *Seccomp* profile limiting syscalls to necessary minimum +* *AppArmor/SELinux* profiles for mandatory access control +* *Capability dropping*: ALL capabilities dropped, only essential added +* *Read-only filesystem* with tmpfs for necessary writes +* *Non-root user* (UID 10001) +* *Network isolation*: Internal services on isolated bridge network + +==== 3. *Input Validation* + +* All user input sanitized via WordPress escaping functions +* File upload validation with MIME type checking +* SVG sanitization to prevent XSS +* SQL injection prevention via prepared statements (WordPress WPDB) +* Command injection prevention (no shell execution of user input) + +==== 4. *Privacy Protection* + +* *Partitioned cookies* (CHIPS) for cross-site tracking prevention +* *IP anonymization* in logs and comments +* *Do Not Track* (DNT) header respect +* *No external resources* without explicit user consent +* *ECH (Encrypted Client Hello)* readiness + +==== 5. *OWASP Top 10 Mitigation* + +* ✅ A01:2021 Broken Access Control - WordPress capability system + RBAC +* ✅ A02:2021 Cryptographic Failures - TLS 1.3, modern ciphers, HSTS +* ✅ A03:2021 Injection - Prepared statements, input sanitization, CSP +* ✅ A04:2021 Insecure Design - Security-by-default architecture +* ✅ A05:2021 Security Misconfiguration - Hardened defaults, header +automation +* ✅ A06:2021 Vulnerable Components - Chainguard Wolfi (minimal, +patched) +* ✅ A07:2021 Authentication Failures - WordPress authentication + rate +limiting +* ✅ A08:2021 Software/Data Integrity - Subresource Integrity (SRI), +signed containers +* ✅ A09:2021 Logging Failures - Structured logging, security event +monitoring +* ✅ A10:2021 SSRF - No outbound requests without validation, internal +network isolation + +=== Reporting a Vulnerability + +*Please DO NOT open public issues for security vulnerabilities.* + +==== Preferred Method + +Send vulnerability reports to: *security@[your-domain]* (Replace with +actual security contact) + +==== Information to Include + +[arabic] +. *Description*: Detailed explanation of the vulnerability +. *Impact*: Potential security impact (confidentiality, integrity, +availability) +. *Reproduction*: Step-by-step instructions to reproduce +. *Affected versions*: Which versions are vulnerable +. *Suggested fix*: If you have a proposed solution + +==== Response Timeline + +* *24 hours*: Initial acknowledgment +* *7 days*: Preliminary assessment and triage +* *30 days*: Fix development and testing +* *60 days*: Public disclosure (coordinated) + +==== PGP Key + +.... +-----BEGIN PGP PUBLIC KEY BLOCK----- +(Add your PGP public key here for encrypted communication) +-----END PGP PUBLIC KEY BLOCK----- +.... + +=== Security Best Practices for Users + +==== Production Deployment + +[arabic] +. *Use HTTPS only* with valid SSL/TLS certificates (Let’s Encrypt +recommended) +. *Enable all security headers* via nginx/Apache configuration +. *Set strong database passwords* (minimum 32 characters, randomly +generated) +. *Enable fail2ban* for brute force protection +. *Configure firewall* to allow only ports 80, 443, 22 +. *Regular updates*: Keep WordPress core, plugins, and theme updated +. *Backup regularly*: Automated daily backups with off-site storage +. *Monitor logs*: Set up log monitoring and alerting +. *Scan containers*: `+podman scan sinople-theme:latest+` before +deployment +. *Review CSP*: Adjust Content-Security-Policy for your specific needs + +==== Development + +[arabic] +. *Never commit secrets* to version control +. *Use `+.env+` files* for sensitive configuration (add to +`+.gitignore+`) +. *Enable WordPress debug mode* only in development +. *Use development docker-compose* (not production config) +. *Scan dependencies*: `+npm audit+`, `+cargo audit+`, +`+composer audit+` + +=== Threat Model + +==== Assets + +* *User data*: Posts, comments, user accounts, personal information +* *Authentication*: Session tokens, cookies, API keys +* *Content*: Published articles, images, custom taxonomies +* *Configuration*: Database credentials, API secrets + +==== Threats + +* *XSS*: Mitigated by CSP, output escaping, input sanitization +* *SQL Injection*: Mitigated by prepared statements, parameterized +queries +* *CSRF*: Mitigated by WordPress nonces, SameSite cookies +* *RCE*: Mitigated by file upload validation, no `+eval()+`, seccomp +* *SSRF*: Mitigated by input validation, network isolation +* *DoS*: Mitigated by rate limiting, resource limits, fail2ban +* *Supply Chain*: Mitigated by Chainguard Wolfi, SRI, dependency +scanning + +==== Assumptions + +* *WordPress core is secure*: We rely on WordPress security team +* *Server is hardened*: Firewall, SELinux/AppArmor enabled +* *TLS terminates at reverse proxy*: Nginx handles SSL/TLS +* *Database is isolated*: Not exposed to internet + +=== Security Roadmap + +==== v0.2 (Q2 2025) + +* [ ] Automated security scanning in CI/CD +* [ ] Dependency vulnerability monitoring (Dependabot/Renovate) +* [ ] SBOM (Software Bill of Materials) generation +* [ ] Signed containers (cosign/sigstore) + +==== v0.3 (Q3 2025) + +* [ ] FIDO2/WebAuthn support for 2FA +* [ ] Audit logging with tamper-evident storage +* [ ] Security dashboard in WordPress admin +* [ ] Automated penetration testing + +==== v1.0 (Q4 2025) + +* [ ] SOC 2 Type II compliance documentation +* [ ] Bug bounty program +* [ ] Third-party security audit +* [ ] OSSF Best Practices badge (passing level) + +=== Acknowledgments + +We thank the security research community for responsible disclosure. + +==== Hall of Fame + +(Security researchers who have reported vulnerabilities will be listed +here) + +=== References + +* https://owasp.org/Top10/[OWASP Top 10 2021] +* https://owasp.org/www-project-application-security-verification-standard/[OWASP +ASVS 4.0] +* https://cwe.mitre.org/top25/[CWE Top 25] +* https://www.nist.gov/cyberframework[NIST Cybersecurity Framework] +* https://wordpress.org/support/article/hardening-wordpress/[WordPress +Security Best Practices] + +''''' + +*Last Updated*: 2025-01-22 *Security Contact*: security@[your-domain] +*PGP Fingerprint*: (Add fingerprint here) diff --git a/journal-theme/SECURITY.md b/journal-theme/SECURITY.md deleted file mode 100644 index 3931e66..0000000 --- a/journal-theme/SECURITY.md +++ /dev/null @@ -1,171 +0,0 @@ - -# Security Policy - -## Supported Versions - -| Version | Supported | -| ------- | ------------------ | -| 0.1.x | :white_check_mark: | - -## Security Model - -Sinople theme implements defense-in-depth with multiple security layers: - -### 1. **Strict Security Headers** -- Content-Security-Policy (CSP) with `wasm-unsafe-eval` only (no `unsafe-inline`, no `unsafe-eval`) -- Cross-Origin-Embedder-Policy (COEP): `require-corp` -- Cross-Origin-Opener-Policy (COOP): `same-origin` -- Cross-Origin-Resource-Policy (CORP): `same-origin` -- Strict-Transport-Security (HSTS) with preload -- Permissions-Policy (all dangerous features disabled) - -### 2. **Container Security** -- **Chainguard Wolfi** base images (supply chain verified) -- **Seccomp** profile limiting syscalls to necessary minimum -- **AppArmor/SELinux** profiles for mandatory access control -- **Capability dropping**: ALL capabilities dropped, only essential added -- **Read-only filesystem** with tmpfs for necessary writes -- **Non-root user** (UID 10001) -- **Network isolation**: Internal services on isolated bridge network - -### 3. **Input Validation** -- All user input sanitized via WordPress escaping functions -- File upload validation with MIME type checking -- SVG sanitization to prevent XSS -- SQL injection prevention via prepared statements (WordPress WPDB) -- Command injection prevention (no shell execution of user input) - -### 4. **Privacy Protection** -- **Partitioned cookies** (CHIPS) for cross-site tracking prevention -- **IP anonymization** in logs and comments -- **Do Not Track** (DNT) header respect -- **No external resources** without explicit user consent -- **ECH (Encrypted Client Hello)** readiness - -### 5. **OWASP Top 10 Mitigation** -- ✅ A01:2021 Broken Access Control - WordPress capability system + RBAC -- ✅ A02:2021 Cryptographic Failures - TLS 1.3, modern ciphers, HSTS -- ✅ A03:2021 Injection - Prepared statements, input sanitization, CSP -- ✅ A04:2021 Insecure Design - Security-by-default architecture -- ✅ A05:2021 Security Misconfiguration - Hardened defaults, header automation -- ✅ A06:2021 Vulnerable Components - Chainguard Wolfi (minimal, patched) -- ✅ A07:2021 Authentication Failures - WordPress authentication + rate limiting -- ✅ A08:2021 Software/Data Integrity - Subresource Integrity (SRI), signed containers -- ✅ A09:2021 Logging Failures - Structured logging, security event monitoring -- ✅ A10:2021 SSRF - No outbound requests without validation, internal network isolation - -## Reporting a Vulnerability - -**Please DO NOT open public issues for security vulnerabilities.** - -### Preferred Method -Send vulnerability reports to: **security@[your-domain]** -(Replace with actual security contact) - -### Information to Include -1. **Description**: Detailed explanation of the vulnerability -2. **Impact**: Potential security impact (confidentiality, integrity, availability) -3. **Reproduction**: Step-by-step instructions to reproduce -4. **Affected versions**: Which versions are vulnerable -5. **Suggested fix**: If you have a proposed solution - -### Response Timeline -- **24 hours**: Initial acknowledgment -- **7 days**: Preliminary assessment and triage -- **30 days**: Fix development and testing -- **60 days**: Public disclosure (coordinated) - -### PGP Key -``` ------BEGIN PGP PUBLIC KEY BLOCK----- -(Add your PGP public key here for encrypted communication) ------END PGP PUBLIC KEY BLOCK----- -``` - -## Security Best Practices for Users - -### Production Deployment -1. **Use HTTPS only** with valid SSL/TLS certificates (Let's Encrypt recommended) -2. **Enable all security headers** via nginx/Apache configuration -3. **Set strong database passwords** (minimum 32 characters, randomly generated) -4. **Enable fail2ban** for brute force protection -5. **Configure firewall** to allow only ports 80, 443, 22 -6. **Regular updates**: Keep WordPress core, plugins, and theme updated -7. **Backup regularly**: Automated daily backups with off-site storage -8. **Monitor logs**: Set up log monitoring and alerting -9. **Scan containers**: `podman scan sinople-theme:latest` before deployment -10. **Review CSP**: Adjust Content-Security-Policy for your specific needs - -### Development -1. **Never commit secrets** to version control -2. **Use `.env` files** for sensitive configuration (add to `.gitignore`) -3. **Enable WordPress debug mode** only in development -4. **Use development docker-compose** (not production config) -5. **Scan dependencies**: `npm audit`, `cargo audit`, `composer audit` - -## Threat Model - -### Assets -- **User data**: Posts, comments, user accounts, personal information -- **Authentication**: Session tokens, cookies, API keys -- **Content**: Published articles, images, custom taxonomies -- **Configuration**: Database credentials, API secrets - -### Threats -- **XSS**: Mitigated by CSP, output escaping, input sanitization -- **SQL Injection**: Mitigated by prepared statements, parameterized queries -- **CSRF**: Mitigated by WordPress nonces, SameSite cookies -- **RCE**: Mitigated by file upload validation, no `eval()`, seccomp -- **SSRF**: Mitigated by input validation, network isolation -- **DoS**: Mitigated by rate limiting, resource limits, fail2ban -- **Supply Chain**: Mitigated by Chainguard Wolfi, SRI, dependency scanning - -### Assumptions -- **WordPress core is secure**: We rely on WordPress security team -- **Server is hardened**: Firewall, SELinux/AppArmor enabled -- **TLS terminates at reverse proxy**: Nginx handles SSL/TLS -- **Database is isolated**: Not exposed to internet - -## Security Roadmap - -### v0.2 (Q2 2025) -- [ ] Automated security scanning in CI/CD -- [ ] Dependency vulnerability monitoring (Dependabot/Renovate) -- [ ] SBOM (Software Bill of Materials) generation -- [ ] Signed containers (cosign/sigstore) - -### v0.3 (Q3 2025) -- [ ] FIDO2/WebAuthn support for 2FA -- [ ] Audit logging with tamper-evident storage -- [ ] Security dashboard in WordPress admin -- [ ] Automated penetration testing - -### v1.0 (Q4 2025) -- [ ] SOC 2 Type II compliance documentation -- [ ] Bug bounty program -- [ ] Third-party security audit -- [ ] OSSF Best Practices badge (passing level) - -## Acknowledgments - -We thank the security research community for responsible disclosure. - -### Hall of Fame -(Security researchers who have reported vulnerabilities will be listed here) - -## References - -- [OWASP Top 10 2021](https://owasp.org/Top10/) -- [OWASP ASVS 4.0](https://owasp.org/www-project-application-security-verification-standard/) -- [CWE Top 25](https://cwe.mitre.org/top25/) -- [NIST Cybersecurity Framework](https://www.nist.gov/cyberframework) -- [WordPress Security Best Practices](https://wordpress.org/support/article/hardening-wordpress/) - ---- - -**Last Updated**: 2025-01-22 -**Security Contact**: security@[your-domain] -**PGP Fingerprint**: (Add fingerprint here) diff --git a/journal-theme/TESTING.md b/journal-theme/TESTING.adoc similarity index 60% rename from journal-theme/TESTING.md rename to journal-theme/TESTING.adoc index 486a957..8a9f0b2 100644 --- a/journal-theme/TESTING.md +++ b/journal-theme/TESTING.adoc @@ -1,63 +1,64 @@ - -# Testing Guide +== Testing Guide -This document provides comprehensive guidance for running tests in the Sinople theme. +This document provides comprehensive guidance for running tests in the +Sinople theme. -## Overview +=== Overview -Sinople implements a multi-language test suite covering: -- **PHP** (WordPress theme code) - PHPUnit -- **JavaScript/** - Jest -- **Rust** (WebAssembly) - cargo test +Sinople implements a multi-language test suite covering: - *PHP* +(WordPress theme code) - PHPUnit - *JavaScript/* - Jest - *Rust* +(WebAssembly) - cargo test -## Prerequisites +=== Prerequisites -### PHP Testing +==== PHP Testing -```bash +[source,bash] +---- # Install Composer dependencies composer install --dev # Install WordPress test suite bash bin/install-wp-tests.sh wordpress_test root '' localhost latest -``` +---- -Required environment variables: -- `WP_TESTS_DIR` - Path to WordPress test library (default: `/tmp/wordpress-tests-lib`) -- `WP_CORE_DIR` - Path to WordPress core (default: `/tmp/wordpress`) +Required environment variables: - `+WP_TESTS_DIR+` - Path to WordPress +test library (default: `+/tmp/wordpress-tests-lib+`) - `+WP_CORE_DIR+` - +Path to WordPress core (default: `+/tmp/wordpress+`) -### JavaScript Testing +==== JavaScript Testing -```bash +[source,bash] +---- # Install npm dependencies npm ci -``` +---- -### Rust Testing +==== Rust Testing -```bash +[source,bash] +---- # Install Rust and wasm target rustup target add wasm32-unknown-unknown -``` +---- -## Running Tests +=== Running Tests -### Quick Start +==== Quick Start -```bash +[source,bash] +---- # Run all tests (via justfile) just test # Quick validation before commit just check -``` +---- -### PHP Tests +==== PHP Tests -```bash +[source,bash] +---- # Run all PHP tests vendor/bin/phpunit @@ -72,11 +73,12 @@ vendor/bin/phpunit --coverage-html coverage/html --coverage-text # Via npm npm run test:php -``` +---- -### JavaScript Tests +==== JavaScript Tests -```bash +[source,bash] +---- # Run all JavaScript tests npm test @@ -91,11 +93,12 @@ npm test -- accessibility.test.ts # Update snapshots npm test -- -u -``` +---- -### Rust Tests +==== Rust Tests -```bash +[source,bash] +---- cd assets/wasm # Run all tests @@ -109,13 +112,13 @@ cargo test test_sanitize_html # Run tests for WASM target cargo test --target wasm32-unknown-unknown -``` +---- -## Test Structure +=== Test Structure -### PHP Tests (`tests/php/`) +==== PHP Tests (`+tests/php/+`) -``` +.... tests/php/ ├── SinopleTestCase.php # Base test case class ├── test-setup.php # Setup & utility functions @@ -124,13 +127,14 @@ tests/php/ ├── test-security.php # Security headers, sanitization ├── test-indieweb.php # Microformats, webmentions └── test-serialization.php # NDJSON, FlatBuffers, Cap'n Proto -``` +.... -#### Base Test Case +===== Base Test Case -All test classes extend `SinopleTestCase`, which provides: +All test classes extend `+SinopleTestCase+`, which provides: -```php +[source,php] +---- // Create test post $post_id = $this->create_test_post([ 'post_title' => 'Test Post', @@ -148,21 +152,21 @@ $this->assertHasMicroformat($html, 'h-entry'); // Assert ARIA attributes $this->assertHasAriaAttribute($html, 'aria-label'); -``` +---- -### JavaScript Tests (`tests/js/`) +==== JavaScript Tests (`+tests/js/+`) -``` +.... tests/js/ ├── setup.ts # Jest setup & mocks ├── accessibility.test.ts # Font size, theme toggle, keyboard nav ├── features.test.ts # Feature detection └── wasm.test.ts # WebAssembly integration -``` +.... -#### Test Utilities +===== Test Utilities -``` +.... // Mock window.sinople global window.sinople = { features: { viewTransitions: true, wasm: true }, @@ -175,19 +179,20 @@ localStorage.setItem('sinople_theme', 'dark'); // Mock matchMedia window.matchMedia = jest.fn()... -``` +.... -## Coverage Targets +=== Coverage Targets -### Bronze Level Requirements (Current) +==== Bronze Level Requirements (Current) -- **PHP**: Target >80% coverage -- **JavaScript**: Target >80% coverage -- **Rust**: Target >80% coverage +* *PHP*: Target >80% coverage +* *JavaScript*: Target >80% coverage +* *Rust*: Target >80% coverage -### Checking Coverage +==== Checking Coverage -```bash +[source,bash] +---- # PHP coverage vendor/bin/phpunit --coverage-text @@ -197,34 +202,31 @@ npm run test:coverage # View HTML reports open coverage/html/index.html # PHP open coverage/js/index.html # JavaScript -``` +---- -## Continuous Integration +=== Continuous Integration -### GitHub Actions +==== GitHub Actions -Tests run automatically on: -- Every push to `main` or `develop` -- Every pull request -- Weekly schedule (Mondays at 9am UTC) +Tests run automatically on: - Every push to `+main+` or `+develop+` - +Every pull request - Weekly schedule (Mondays at 9am UTC) -View: `.github/workflows/ci.yml` +View: `+.github/workflows/ci.yml+` -### GitLab CI +==== GitLab CI -Tests run in parallel across: -- 3 PHP versions (8.1, 8.2, 8.3) -- Multiple WordPress versions (6.4, 6.5, latest) -- Security scans -- Container builds +Tests run in parallel across: - 3 PHP versions (8.1, 8.2, 8.3) - +Multiple WordPress versions (6.4, 6.5, latest) - Security scans - +Container builds -View: `.gitlab-ci.yml` +View: `+.gitlab-ci.yml+` -## Writing Tests +=== Writing Tests -### PHP Test Example +==== PHP Test Example -```php +[source,php] +---- class Test_My_Feature extends SinopleTestCase { /** * Test feature works correctly @@ -238,11 +240,11 @@ class Test_My_Feature extends SinopleTestCase { $this->assertEquals('expected', get_post_meta($post_id, 'key', true)); } } -``` +---- -### JavaScript Test Example +==== JavaScript Test Example -``` +.... describe('My Feature', () => { beforeEach(() => { document.body.innerHTML = `
`; @@ -255,11 +257,12 @@ describe('My Feature', () => { expect(element.classList.contains('active')).toBe(true); }); }); -``` +.... -### Rust Test Example +==== Rust Test Example -```rust +[source,rust] +---- #[cfg(test)] mod tests { use super::*; @@ -270,13 +273,14 @@ mod tests { assert_eq!(result, "expected"); } } -``` +---- -## Debugging Tests +=== Debugging Tests -### PHP +==== PHP -```bash +[source,bash] +---- # Run with verbose output vendor/bin/phpunit --verbose @@ -285,11 +289,12 @@ vendor/bin/phpunit --filter test_method_name # Enable debugging output vendor/bin/phpunit --debug -``` +---- -### JavaScript +==== JavaScript -```bash +[source,bash] +---- # Run with verbose output npm test -- --verbose @@ -298,11 +303,12 @@ node --inspect-brk node_modules/.bin/jest --runInBand # Run specific test npm test -- -t "test name pattern" -``` +---- -### Rust +==== Rust -```bash +[source,bash] +---- # Show println! output cargo test -- --nocapture @@ -311,53 +317,56 @@ cargo test -- --ignored # Show test execution time cargo test -- --show-output -``` +---- -## Common Issues +=== Common Issues -### WordPress Test Suite Not Found +==== WordPress Test Suite Not Found -```bash +[source,bash] +---- # Install WordPress test suite bash bin/install-wp-tests.sh wordpress_test root '' localhost latest # Or set custom path export WP_TESTS_DIR=/path/to/wordpress-tests-lib -``` +---- -### Database Connection Issues +==== Database Connection Issues -```bash +[source,bash] +---- # Check MySQL/MariaDB is running systemctl status mariadb # Create test database manually mysql -u root -e "CREATE DATABASE wordpress_test" -``` +---- -### Jest Configuration Issues +==== Jest Configuration Issues -```bash +[source,bash] +---- # Clear Jest cache npm test -- --clearCache # Run with no cache npm test -- --no-cache -``` +---- -## Test Data +=== Test Data -### Fixtures +==== Fixtures -Test data and fixtures should be placed in: -- `tests/php/fixtures/` - PHP test data -- `tests/js/__fixtures__/` - JavaScript test data +Test data and fixtures should be placed in: - `+tests/php/fixtures/+` - +PHP test data - `+tests/js/__fixtures__/+` - JavaScript test data -### Factories +==== Factories Use WordPress factory methods in PHP tests: -```php +[source,php] +---- // Create post $this->factory()->post->create(['post_title' => 'Test']); @@ -366,23 +375,25 @@ $this->factory()->user->create(['role' => 'editor']); // Create term $this->factory()->term->create(['taxonomy' => 'emotion']); -``` +---- -## Performance Testing +=== Performance Testing -```bash +[source,bash] +---- # Run with timing information vendor/bin/phpunit --log-junit junit.xml # Rust benchmarks cd assets/wasm && cargo bench -``` +---- -## Accessibility Testing +=== Accessibility Testing For manual accessibility testing: -```bash +[source,bash] +---- # Run accessibility test scripts npm run test:a11y @@ -390,46 +401,52 @@ npm run test:a11y # - WAVE (https://wave.webaim.org/) # - axe DevTools (browser extension) # - NVDA/JAWS/VoiceOver screen readers -``` +---- -## Security Testing +=== Security Testing -```bash +[source,bash] +---- # Run security tests npm run test:security # Manual security scans just scan just audit -``` +---- -## Best Practices +=== Best Practices -1. **Write descriptive test names** - Test names should clearly describe what is being tested -2. **One assertion per test** - Keep tests focused and atomic -3. **Use factories** - Don't create test data manually -4. **Clean up after tests** - Use `tearDown()` methods -5. **Mock external dependencies** - Don't rely on external APIs -6. **Test edge cases** - Empty inputs, null values, boundary conditions -7. **Keep tests fast** - Slow tests discourage running them frequently -8. **Test behavior, not implementation** - Focus on what, not how +[arabic] +. *Write descriptive test names* - Test names should clearly describe +what is being tested +. *One assertion per test* - Keep tests focused and atomic +. *Use factories* - Don’t create test data manually +. *Clean up after tests* - Use `+tearDown()+` methods +. *Mock external dependencies* - Don’t rely on external APIs +. *Test edge cases* - Empty inputs, null values, boundary conditions +. *Keep tests fast* - Slow tests discourage running them frequently +. *Test behavior, not implementation* - Focus on what, not how -## Resources +=== Resources -- [PHPUnit Documentation](https://phpunit.de/documentation.html) -- [WordPress Testing Handbook](https://make.wordpress.org/core/handbook/testing/) -- [Jest Documentation](https://jestjs.io/docs/getting-started) -- [Rust Testing Guide](https://doc.rust-lang.org/book/ch11-00-testing.html) -- [Testing Library](https://testing-library.com/) +* https://phpunit.de/documentation.html[PHPUnit Documentation] +* https://make.wordpress.org/core/handbook/testing/[WordPress Testing +Handbook] +* https://jestjs.io/docs/getting-started[Jest Documentation] +* https://doc.rust-lang.org/book/ch11-00-testing.html[Rust Testing +Guide] +* https://testing-library.com/[Testing Library] -## Contributing +=== Contributing When contributing tests: -1. Ensure tests pass locally before pushing -2. Add tests for new features -3. Update tests when modifying existing features -4. Aim for >80% code coverage -5. Follow existing test patterns and conventions +[arabic] +. Ensure tests pass locally before pushing +. Add tests for new features +. Update tests when modifying existing features +. Aim for >80% code coverage +. Follow existing test patterns and conventions -See `CONTRIBUTING.md` for more details. +See `+CONTRIBUTING.md+` for more details. diff --git a/journal-theme/changelog.adoc b/journal-theme/changelog.adoc new file mode 100644 index 0000000..d0f06a5 --- /dev/null +++ b/journal-theme/changelog.adoc @@ -0,0 +1,21 @@ +== 🧶 Changelog + +All notable changes to this project will be documented here. + +This project follows a "`threaded`" versioning system inspired by +narrative iteration. + +=== [0.1-threaded] — 2025-07-21 + +==== Added + +* Initial theme scaffold: `+style.css+`, `+functions.php+`, +`+index.php+` +* `+README.md+` with poetic structure and IndieWeb integration +* Accessibility features: skip links, dark/light toggle, font scaling +* Semantic folder with `+metadata.jsonld+` and draft `+sinople.ttl+` +* Licensing (GPL v3 / CC BY 4.0) + +==== Intent + +Stitched the first veil of _Sinople_—resistance, mist, and memory +embodied in a CSS-first foundation. diff --git a/journal-theme/changelog.md b/journal-theme/changelog.md deleted file mode 100644 index 635fb9c..0000000 --- a/journal-theme/changelog.md +++ /dev/null @@ -1,20 +0,0 @@ - -# 🧶 Changelog - -All notable changes to this project will be documented here. -This project follows a “threaded” versioning system inspired by narrative iteration. - -## [0.1-threaded] — 2025-07-21 - -### Added -- Initial theme scaffold: `style.css`, `functions.php`, `index.php` -- `README.md` with poetic structure and IndieWeb integration -- Accessibility features: skip links, dark/light toggle, font scaling -- Semantic folder with `metadata.jsonld` and draft `sinople.ttl` -- Licensing (GPL v3 / CC BY 4.0) - -### Intent -Stitched the first veil of *Sinople*—resistance, mist, and memory embodied in a CSS-first foundation. diff --git a/journal-theme/content/EXPLAINME.adoc b/journal-theme/content/EXPLAINME.adoc new file mode 100644 index 0000000..22d7422 --- /dev/null +++ b/journal-theme/content/EXPLAINME.adoc @@ -0,0 +1,4 @@ +== 📁 Content Folder + +Workspace for drafts, JSON-LD experiments, and unfinished fragments. +Pairs with entries/ when ready to publish. diff --git a/journal-theme/content/EXPLAINME.md b/journal-theme/content/EXPLAINME.md deleted file mode 100644 index 3d1a3da..0000000 --- a/journal-theme/content/EXPLAINME.md +++ /dev/null @@ -1,8 +0,0 @@ - -# 📁 Content Folder - -Workspace for drafts, JSON-LD experiments, and unfinished fragments. -Pairs with entries/ when ready to publish. diff --git a/journal-theme/content/field-notes/fog-breathing.adoc b/journal-theme/content/field-notes/fog-breathing.adoc new file mode 100644 index 0000000..ecc00c5 --- /dev/null +++ b/journal-theme/content/field-notes/fog-breathing.adoc @@ -0,0 +1 @@ +Woke up to mist… (field note) diff --git a/journal-theme/content/field-notes/fog-breathing.md b/journal-theme/content/field-notes/fog-breathing.md deleted file mode 100644 index b2ce044..0000000 --- a/journal-theme/content/field-notes/fog-breathing.md +++ /dev/null @@ -1,5 +0,0 @@ - -Woke up to mist... (field note) diff --git a/journal-theme/docs/PHP-SECURITY-INTEGRATION.adoc b/journal-theme/docs/PHP-SECURITY-INTEGRATION.adoc new file mode 100644 index 0000000..d9899f9 --- /dev/null +++ b/journal-theme/docs/PHP-SECURITY-INTEGRATION.adoc @@ -0,0 +1,232 @@ +== PHP Security Integration with php-aegis and sanctify-php + +This document describes the integration of Hyperpolymath’s PHP security +tools with the Sinople WordPress theme. + +=== Overview + +Sinople integrates two complementary security tools: + +[arabic] +. *php-aegis*: Runtime PHP security library for input validation, output +sanitization, and Turtle/RDF escaping +. *sanctify-php*: Static analysis tool for PHP security hardening (CI/CD +integration) + +=== php-aegis Integration + +==== Added Files + +* `+inc/aegis-integration.php+` - WordPress-style function wrappers +* `+inc/turtle-output.php+` - RDF Turtle feed generation + +==== Features Used + +[cols=",,",options="header",] +|=== +|Feature |Sinople Use Case |Fallback +|`+Sanitizer::html()+` |Template output |`+esc_html()+` +|`+Sanitizer::attr()+` |Attribute escaping |`+esc_attr()+` +|`+Sanitizer::json()+` |JSON-LD output |`+wp_json_encode()+` +|`+Validator::url()+` |URL validation |`+filter_var()+` +|`+Validator::httpsUrl()+` |HTTPS enforcement (RSR) |Manual check +|`+TurtleEscaper+` |RDF/Turtle feed |Manual escaping +|=== + +==== TurtleEscaper - Unique Value + +The TurtleEscaper is particularly valuable for Sinople’s semantic web +focus. It provides: + +* W3C-compliant string escaping for Turtle literals +* IRI validation and escaping per RFC 3987 +* Language tag validation (BCP 47) +* Safe triple construction + +This enables the new `+/feed/turtle/+` endpoint for RDF consumers. + +==== WordPress Function Wrappers + +All php-aegis features are wrapped with WordPress-style functions that: +1. Check if php-aegis is available 2. Use php-aegis if loaded 3. Fall +back to WordPress/PHP equivalents otherwise + +Example: + +[source,php] +---- +// Uses php-aegis if available, otherwise esc_html() +echo sinople_aegis_html($user_input); +---- + +=== sanctify-php Integration + +==== CI Integration + +The `+.github/workflows/php-security.yml+` workflow now includes: + +[arabic] +. *Basic grep-based scanning* (original) +. *sanctify-php AST analysis* (new) +. *php-aegis verification* (new) + +==== What sanctify-php Checks + +* Missing `+declare(strict_types=1)+` +* Missing ABSPATH protection +* Unescaped output in echo statements +* Direct superglobal access without sanitization +* `+wp_redirect()+` without `+exit+` +* Missing text domains in i18n functions +* Direct database queries without `+prepare()+` + +==== Local Usage + +[source,bash] +---- +# If sanctify is installed +sanctify analyze ./inc/ +sanctify fix ./inc/ # Preview fixes +sanctify report ./ > security-report.json +---- + +=== Compatibility Notes + +==== PHP Version + +Both tools require *PHP 8.1+*, which matches Sinople’s requirement. + +==== License Compatibility + +[cols=",,",options="header",] +|=== +|Tool |License |Sinople (GPL-3.0) +|php-aegis |MIT |Compatible +|sanctify-php |AGPL-3.0 |Compatible (build tool only) +|=== + +==== WordPress Overlap + +php-aegis COMPATIBILITY.md correctly notes that WordPress has built-in +escaping. However, Sinople benefits from: + +[arabic] +. *TurtleEscaper* - Not available in WordPress +. *Stricter validation* - `+httpsUrl()+` for RSR compliance +. *Headers utilities* - Cleaner API with `+removeInsecureHeaders()+` + +''''' + +=== Issues to Report to Upstream Repositories + +==== php-aegis Issues + +===== 1. Missing php-aegis-compat Package + +*File*: `+COMPATIBILITY.md+` *Issue*: The document references +`+hyperpolymath/php-aegis-compat+` for PHP 7.4+ support, but this +package doesn’t exist. *Impact*: WordPress users on PHP 7.4/8.0 cannot +use the library. *Recommendation*: Either create the compat package or +update documentation to clarify it’s planned but not yet available. + +===== 2. No Packagist Publication + +*Issue*: php-aegis is not on Packagist, requiring VCS repository +configuration in composer.json. *Impact*: Harder installation, no +version resolution through Packagist. *Recommendation*: Publish to +Packagist for standard Composer installation. + +===== 3. WordPress Adapter Not Implemented + +*File*: `+COMPATIBILITY.md+` *Issue*: Describes WordPress mu-plugin +adapter but it doesn’t exist in the repo. *Recommendation*: Either +implement the adapter or mark as "`proposed`" in documentation. + +===== 4. Missing Security Headers + +*File*: `+src/Headers.php+` *Issue*: Missing `+Permissions-Policy+` in +`+secure()+` method despite having `+permissionsPolicy()+` helper. +*Recommendation*: Add default permissions policy to `+secure()+`. + +==== sanctify-php Issues + +===== 1. Parser PHP 8.1+ Syntax + +*Concern*: Verify parser handles all PHP 8.1+ features: - Constructor +property promotion - Named arguments - Match expressions - Nullsafe +operator (`+?->+`) *Recommendation*: Add test cases for these syntax +elements. + +===== 2. UnsafeRedirect False Positives + +*File*: `+src/Sanctify/WordPress/Constraints.hs+` *Issue*: +`+UnsafeRedirect+` check flags `+wp_redirect()+` without checking if +`+exit+` is on the next line. *Current*: Only checks same statement +*Expected*: Should check subsequent statement *Example* (should not +flag): + +[source,php] +---- +wp_redirect($url); +exit; +---- + +===== 3. MissingTextDomain False Positives + +*Issue*: May flag internal WordPress functions that don’t need text +domain. *Example*: `+__()+` used with WordPress core text domain. +*Recommendation*: Add allowlist for core WordPress text domains. + +===== 4. Guix Export Documentation + +*Issue*: `+sanctify export --guix+` referenced but Guix configuration +examples incomplete. *Recommendation*: Add complete Guix container +example in docs. + +''''' + +=== Testing the Integration + +==== Verify php-aegis is loaded + +[source,php] +---- +if (sinople_aegis_available()) { + echo "php-aegis loaded"; +} else { + echo "Using fallbacks"; +} +---- + +==== Test Turtle output + +Visit `+/feed/turtle/+` to see RDF output. + +==== Run sanctify locally + +[source,bash] +---- +# Install (requires Haskell toolchain) +cd /tmp && git clone https://github.com/hyperpolymath/sanctify-php +cd sanctify-php && cabal install + +# Analyze theme +sanctify analyze /path/to/sinople-theme +---- + +''''' + +=== Future Enhancements + +[arabic] +. *Structured RDFa Output*: Extend turtle-output.php to support RDFa +attributes in HTML +. *JSON-LD with php-aegis*: Use `+Sanitizer::json()+` for safer JSON-LD +output +. *Pre-commit Hook*: Add sanctify analysis to git pre-commit +. *Editor Integration*: LSP support for sanctify-php in VS Code/Neovim + +''''' + +_Document created during php-aegis and sanctify-php integration into +sinople-theme._ _Last updated: 2025-12-27_ diff --git a/journal-theme/docs/PHP-SECURITY-INTEGRATION.md b/journal-theme/docs/PHP-SECURITY-INTEGRATION.md deleted file mode 100644 index 5082e9e..0000000 --- a/journal-theme/docs/PHP-SECURITY-INTEGRATION.md +++ /dev/null @@ -1,206 +0,0 @@ - -# PHP Security Integration with php-aegis and sanctify-php - -This document describes the integration of Hyperpolymath's PHP security tools with the Sinople WordPress theme. - -## Overview - -Sinople integrates two complementary security tools: - -1. **php-aegis**: Runtime PHP security library for input validation, output sanitization, and Turtle/RDF escaping -2. **sanctify-php**: Static analysis tool for PHP security hardening (CI/CD integration) - -## php-aegis Integration - -### Added Files - -- `inc/aegis-integration.php` - WordPress-style function wrappers -- `inc/turtle-output.php` - RDF Turtle feed generation - -### Features Used - -| Feature | Sinople Use Case | Fallback | -|---------|------------------|----------| -| `Sanitizer::html()` | Template output | `esc_html()` | -| `Sanitizer::attr()` | Attribute escaping | `esc_attr()` | -| `Sanitizer::json()` | JSON-LD output | `wp_json_encode()` | -| `Validator::url()` | URL validation | `filter_var()` | -| `Validator::httpsUrl()` | HTTPS enforcement (RSR) | Manual check | -| `TurtleEscaper` | RDF/Turtle feed | Manual escaping | - -### TurtleEscaper - Unique Value - -The TurtleEscaper is particularly valuable for Sinople's semantic web focus. It provides: - -- W3C-compliant string escaping for Turtle literals -- IRI validation and escaping per RFC 3987 -- Language tag validation (BCP 47) -- Safe triple construction - -This enables the new `/feed/turtle/` endpoint for RDF consumers. - -### WordPress Function Wrappers - -All php-aegis features are wrapped with WordPress-style functions that: -1. Check if php-aegis is available -2. Use php-aegis if loaded -3. Fall back to WordPress/PHP equivalents otherwise - -Example: -```php -// Uses php-aegis if available, otherwise esc_html() -echo sinople_aegis_html($user_input); -``` - -## sanctify-php Integration - -### CI Integration - -The `.github/workflows/php-security.yml` workflow now includes: - -1. **Basic grep-based scanning** (original) -2. **sanctify-php AST analysis** (new) -3. **php-aegis verification** (new) - -### What sanctify-php Checks - -- Missing `declare(strict_types=1)` -- Missing ABSPATH protection -- Unescaped output in echo statements -- Direct superglobal access without sanitization -- `wp_redirect()` without `exit` -- Missing text domains in i18n functions -- Direct database queries without `prepare()` - -### Local Usage - -```bash -# If sanctify is installed -sanctify analyze ./inc/ -sanctify fix ./inc/ # Preview fixes -sanctify report ./ > security-report.json -``` - -## Compatibility Notes - -### PHP Version - -Both tools require **PHP 8.1+**, which matches Sinople's requirement. - -### License Compatibility - -| Tool | License | Sinople (GPL-3.0) | -|------|---------|-------------------| -| php-aegis | MIT | Compatible | -| sanctify-php | AGPL-3.0 | Compatible (build tool only) | - -### WordPress Overlap - -php-aegis COMPATIBILITY.md correctly notes that WordPress has built-in escaping. However, Sinople benefits from: - -1. **TurtleEscaper** - Not available in WordPress -2. **Stricter validation** - `httpsUrl()` for RSR compliance -3. **Headers utilities** - Cleaner API with `removeInsecureHeaders()` - ---- - -## Issues to Report to Upstream Repositories - -### php-aegis Issues - -#### 1. Missing php-aegis-compat Package -**File**: `COMPATIBILITY.md` -**Issue**: The document references `hyperpolymath/php-aegis-compat` for PHP 7.4+ support, but this package doesn't exist. -**Impact**: WordPress users on PHP 7.4/8.0 cannot use the library. -**Recommendation**: Either create the compat package or update documentation to clarify it's planned but not yet available. - -#### 2. No Packagist Publication -**Issue**: php-aegis is not on Packagist, requiring VCS repository configuration in composer.json. -**Impact**: Harder installation, no version resolution through Packagist. -**Recommendation**: Publish to Packagist for standard Composer installation. - -#### 3. WordPress Adapter Not Implemented -**File**: `COMPATIBILITY.md` -**Issue**: Describes WordPress mu-plugin adapter but it doesn't exist in the repo. -**Recommendation**: Either implement the adapter or mark as "proposed" in documentation. - -#### 4. Missing Security Headers -**File**: `src/Headers.php` -**Issue**: Missing `Permissions-Policy` in `secure()` method despite having `permissionsPolicy()` helper. -**Recommendation**: Add default permissions policy to `secure()`. - -### sanctify-php Issues - -#### 1. Parser PHP 8.1+ Syntax -**Concern**: Verify parser handles all PHP 8.1+ features: -- Constructor property promotion -- Named arguments -- Match expressions -- Nullsafe operator (`?->`) -**Recommendation**: Add test cases for these syntax elements. - -#### 2. UnsafeRedirect False Positives -**File**: `src/Sanctify/WordPress/Constraints.hs` -**Issue**: `UnsafeRedirect` check flags `wp_redirect()` without checking if `exit` is on the next line. -**Current**: Only checks same statement -**Expected**: Should check subsequent statement -**Example** (should not flag): -```php -wp_redirect($url); -exit; -``` - -#### 3. MissingTextDomain False Positives -**Issue**: May flag internal WordPress functions that don't need text domain. -**Example**: `__()` used with WordPress core text domain. -**Recommendation**: Add allowlist for core WordPress text domains. - -#### 4. Guix Export Documentation -**Issue**: `sanctify export --guix` referenced but Guix configuration examples incomplete. -**Recommendation**: Add complete Guix container example in docs. - ---- - -## Testing the Integration - -### Verify php-aegis is loaded - -```php -if (sinople_aegis_available()) { - echo "php-aegis loaded"; -} else { - echo "Using fallbacks"; -} -``` - -### Test Turtle output - -Visit `/feed/turtle/` to see RDF output. - -### Run sanctify locally - -```bash -# Install (requires Haskell toolchain) -cd /tmp && git clone https://github.com/hyperpolymath/sanctify-php -cd sanctify-php && cabal install - -# Analyze theme -sanctify analyze /path/to/sinople-theme -``` - ---- - -## Future Enhancements - -1. **Structured RDFa Output**: Extend turtle-output.php to support RDFa attributes in HTML -2. **JSON-LD with php-aegis**: Use `Sanitizer::json()` for safer JSON-LD output -3. **Pre-commit Hook**: Add sanctify analysis to git pre-commit -4. **Editor Integration**: LSP support for sanctify-php in VS Code/Neovim - ---- - -*Document created during php-aegis and sanctify-php integration into sinople-theme.* -*Last updated: 2025-12-27* diff --git a/journal-theme/docs/PORTALS.adoc b/journal-theme/docs/PORTALS.adoc new file mode 100644 index 0000000..0942507 --- /dev/null +++ b/journal-theme/docs/PORTALS.adoc @@ -0,0 +1,46 @@ +== 🌐 Portals: External Inspirations + +Sinople draws breath from misty edges, poetic archives, and +decentralized architectures. These portals are references, influences, +and threads beyond the journal. + +''''' + +=== 🪞 Semantic & IndieWeb + +* https://indieweb.org[IndieWeb.org] — A community for decentralized +publishing and human-scale web architecture. +* https://microformats.org[Microformats.org] — Semantic HTML patterns +for marking up people, entries, and relationships. +* http://xmlns.com/foaf/0.1/[FOAF Vocabulary] — Friend of a Friend +ontology for describing people and social graphs. +* https://www.w3.org/2004/02/skos/[SKOS] — Simple Knowledge Organization +System, perfect for gloss and thread vocabularies. + +''''' + +=== 🧵 Poetic Archives + +* https://archive.org[The Internet Archive] — A global memory machine of +forgotten pages and fog-bound texts. +* https://en.wikipedia.org/wiki/Haunani-Kay_Trask[Haunani-Kay Trask] — +Voice of indigenous resistance and stitched history. +* https://www.poetryfoundation.org/poets/maria-sabina[María Sabina’s +Mushroom Poetry] — The living syllables of veiled agency. + +''''' + +=== 🐚 Web Folk & Signal Flares + +* https://melanierichard.github.io/thread/[Melanie Richard’s `+thread+`] +— A minimal theme with emotional texture. +* https://zylstra.org/blog/[Ton Zijlstra] — IndieWeb praxis and semantic +curiosity. +* https://maggieappleton.com[Maggie Appleton] — Digital gardens and +conceptual cartography. + +''''' + +Want to add your own portal? Submit a glossed link with intent, +symbolism, or resonance. + +Portals are not backlinks—they are *threads into other worlds*. diff --git a/journal-theme/docs/PORTALS.md b/journal-theme/docs/PORTALS.md deleted file mode 100644 index b84b6e6..0000000 --- a/journal-theme/docs/PORTALS.md +++ /dev/null @@ -1,37 +0,0 @@ - -# 🌐 Portals: External Inspirations - -Sinople draws breath from misty edges, poetic archives, and decentralized architectures. These portals are references, influences, and threads beyond the journal. - ---- - -## 🪞 Semantic & IndieWeb - -- [IndieWeb.org](https://indieweb.org) — A community for decentralized publishing and human-scale web architecture. -- [Microformats.org](https://microformats.org) — Semantic HTML patterns for marking up people, entries, and relationships. -- [FOAF Vocabulary](http://xmlns.com/foaf/0.1/) — Friend of a Friend ontology for describing people and social graphs. -- [SKOS](https://www.w3.org/2004/02/skos/) — Simple Knowledge Organization System, perfect for gloss and thread vocabularies. - ---- - -## 🧵 Poetic Archives - -- [The Internet Archive](https://archive.org) — A global memory machine of forgotten pages and fog-bound texts. -- [Haunani-Kay Trask](https://en.wikipedia.org/wiki/Haunani-Kay_Trask) — Voice of indigenous resistance and stitched history. -- [María Sabina’s Mushroom Poetry](https://www.poetryfoundation.org/poets/maria-sabina) — The living syllables of veiled agency. - ---- - -## 🐚 Web Folk & Signal Flares - -- [Melanie Richard’s `thread`](https://melanierichard.github.io/thread/) — A minimal theme with emotional texture. -- [Ton Zijlstra](https://zylstra.org/blog/) — IndieWeb praxis and semantic curiosity. -- [Maggie Appleton](https://maggieappleton.com) — Digital gardens and conceptual cartography. - ---- - -Want to add your own portal? Submit a glossed link with intent, symbolism, or resonance. -Portals are not backlinks—they are **threads into other worlds**. diff --git a/journal-theme/docs/README.adoc b/journal-theme/docs/README.adoc new file mode 100644 index 0000000..2034ede --- /dev/null +++ b/journal-theme/docs/README.adoc @@ -0,0 +1,16 @@ +''''' + +== 📚 Further Reading + +* link:./docs/ethos.md[`+docs/ethos.md+`] — Sinople’s philosophical +grounding + +* link:./docs/spans.md[`+docs/spans.md+`] — Narrative content types and +structure + +* link:./docs/style-guide.md[`+docs/style-guide.md+`] — Semantic naming +and formatting guidance + +* link:./docs/taxonomy.md[`+docs/taxonomy.md+`] — Symbolic threads and +motif registry + +* link:./docs/contributing-philosophy.md[`+docs/contributing-philosophy.md+`] +— Narrative-oriented collaboration guide + +* link:./PORTALS.md[`+PORTALS.md+`] — External inspirations and cultural +references diff --git a/journal-theme/docs/README.md b/journal-theme/docs/README.md deleted file mode 100644 index 1709703..0000000 --- a/journal-theme/docs/README.md +++ /dev/null @@ -1,14 +0,0 @@ - ---- - -## 📚 Further Reading - -- [`docs/ethos.md`](./docs/ethos.md) — Sinople's philosophical grounding -- [`docs/spans.md`](./docs/spans.md) — Narrative content types and structure -- [`docs/style-guide.md`](./docs/style-guide.md) — Semantic naming and formatting guidance -- [`docs/taxonomy.md`](./docs/taxonomy.md) — Symbolic threads and motif registry -- [`docs/contributing-philosophy.md`](./docs/contributing-philosophy.md) — Narrative-oriented collaboration guide -- [`PORTALS.md`](./PORTALS.md) — External inspirations and cultural references diff --git a/journal-theme/docs/contributing-philosophy.adoc b/journal-theme/docs/contributing-philosophy.adoc new file mode 100644 index 0000000..4f5365b --- /dev/null +++ b/journal-theme/docs/contributing-philosophy.adoc @@ -0,0 +1 @@ +How to contribute with poetic clarity and semantic depth. diff --git a/journal-theme/docs/contributing-philosophy.md b/journal-theme/docs/contributing-philosophy.md deleted file mode 100644 index d636fd9..0000000 --- a/journal-theme/docs/contributing-philosophy.md +++ /dev/null @@ -1,5 +0,0 @@ - -How to contribute with poetic clarity and semantic depth. diff --git a/journal-theme/docs/ethos.adoc b/journal-theme/docs/ethos.adoc new file mode 100644 index 0000000..0e85256 --- /dev/null +++ b/journal-theme/docs/ethos.adoc @@ -0,0 +1 @@ +Sinople is stitched resistance… (ethos text) diff --git a/journal-theme/docs/ethos.md b/journal-theme/docs/ethos.md deleted file mode 100644 index 7a7858a..0000000 --- a/journal-theme/docs/ethos.md +++ /dev/null @@ -1,5 +0,0 @@ - -Sinople is stitched resistance... (ethos text) diff --git a/journal-theme/docs/spans.adoc b/journal-theme/docs/spans.adoc new file mode 100644 index 0000000..c461191 --- /dev/null +++ b/journal-theme/docs/spans.adoc @@ -0,0 +1 @@ +Field Notes, Constructs, Portals… (span descriptions) diff --git a/journal-theme/docs/spans.md b/journal-theme/docs/spans.md deleted file mode 100644 index f3fd48d..0000000 --- a/journal-theme/docs/spans.md +++ /dev/null @@ -1,5 +0,0 @@ - -Field Notes, Constructs, Portals... (span descriptions) diff --git a/journal-theme/docs/styles-guide.adoc b/journal-theme/docs/styles-guide.adoc new file mode 100644 index 0000000..322e122 --- /dev/null +++ b/journal-theme/docs/styles-guide.adoc @@ -0,0 +1,20 @@ +== 🎨 Style Guide for Semantic Naming + +=== 🧵 Constructs + +* Use lowercase, hyphenated filenames (`+eteri-mistveil.jsonld+`) +* ID URI: `+https://sinople.example.com/constructs/{name}+` +* Include `+alternateName+`, `+embodies+`, `+entanglesWith+` + +=== 🔖 Glosses + +* Use schema.org `+DefinedTerm+` +* Filename matches `+termCode+` (`+fog-threading.ttl+`) +* Include `+description+`, `+inDefinedTermSet+`, and `+appliesTo+` + +=== ✒️ Ontologies + +* Prefix custom vocabulary with `+sin:+` + +* Use `+Class+`, `+ObjectProperty+`, `+DatatypeProperty+` + +* Organize properties by domain (e.g. `+Construct+`, `+Gloss+`, +`+Thread+`) diff --git a/journal-theme/docs/styles-guide.md b/journal-theme/docs/styles-guide.md deleted file mode 100644 index 94ec750..0000000 --- a/journal-theme/docs/styles-guide.md +++ /dev/null @@ -1,20 +0,0 @@ - -# 🎨 Style Guide for Semantic Naming - -## 🧵 Constructs -- Use lowercase, hyphenated filenames (`eteri-mistveil.jsonld`) -- ID URI: `https://sinople.example.com/constructs/{name}` -- Include `alternateName`, `embodies`, `entanglesWith` - -## 🔖 Glosses -- Use schema.org `DefinedTerm` -- Filename matches `termCode` (`fog-threading.ttl`) -- Include `description`, `inDefinedTermSet`, and `appliesTo` - -## ✒️ Ontologies -- Prefix custom vocabulary with `sin:` -- Use `Class`, `ObjectProperty`, `DatatypeProperty` -- Organize properties by domain (e.g. `Construct`, `Gloss`, `Thread`) diff --git a/journal-theme/docs/taxonomy.adoc b/journal-theme/docs/taxonomy.adoc new file mode 100644 index 0000000..06e9ed5 --- /dev/null +++ b/journal-theme/docs/taxonomy.adoc @@ -0,0 +1 @@ +Registry of Threads, GlossTypes, and Motifs. diff --git a/journal-theme/docs/taxonomy.md b/journal-theme/docs/taxonomy.md deleted file mode 100644 index ae34176..0000000 --- a/journal-theme/docs/taxonomy.md +++ /dev/null @@ -1,5 +0,0 @@ - -Registry of Threads, GlossTypes, and Motifs. diff --git a/journal-theme/entries/EXPLAINME.adoc b/journal-theme/entries/EXPLAINME.adoc new file mode 100644 index 0000000..e2e040d --- /dev/null +++ b/journal-theme/entries/EXPLAINME.adoc @@ -0,0 +1,4 @@ +== 📚 Entries Folder + +Published journal content organized by span type. Includes field notes, +essays, glossed narratives, portals. diff --git a/journal-theme/entries/EXPLAINME.md b/journal-theme/entries/EXPLAINME.md deleted file mode 100644 index 0472325..0000000 --- a/journal-theme/entries/EXPLAINME.md +++ /dev/null @@ -1,8 +0,0 @@ - -# 📚 Entries Folder - -Published journal content organized by span type. -Includes field notes, essays, glossed narratives, portals. diff --git a/journal-theme/semantic/constructs/EXPLAINME.adoc b/journal-theme/semantic/constructs/EXPLAINME.adoc new file mode 100644 index 0000000..303e109 --- /dev/null +++ b/journal-theme/semantic/constructs/EXPLAINME.adoc @@ -0,0 +1,41 @@ +== 🧶 Semantic Constructs: Help & Guidance + +This folder contains semantic representations of narrative constructs in +various formats: + +* `+.jsonld+` — Lightweight JSON for structured data (used by search +engines, APIs) +* `+.ttl+` — RDF in Turtle format (ideal for Linked Data and SPARQL) +* `+.owl+` — Ontology fragments describing symbolic logic and +relationships + +=== ✅ Suggested Use Per Format + +[width="100%",cols="18%,43%,39%",options="header",] +|=== +|Format |Purpose |Best For +|`+.jsonld+` |Easy embedding & SEO |HTML templates, rich results + +|`+.ttl+` |RDF graph publication |Linked Data, ontology browsing + +|`+.owl+` |Formal ontology & reasoning |Semantic inference, vocab +modeling +|=== + +Each construct may be referenced across posts, glosses, or portals. +Semantic files help express agency, relationships, and narrative weight +in machine-readable form. + +''''' + +=== 📌 About "`Heavily Relational`" + +This means the construct: - Has *explicit semantic links* to other +entities (e.g. `+entanglesWith+`, `+knows+`, `+hasThread+`) - May be +used in *reasoning engines* to infer relationships or class memberships +- Operates within a *symbolic network*, rather than being a standalone +descriptor + +You can scale this up with properties like: - `+hasVeil+`, +`+appearsIn+`, `+resonatesWith+`, `+originatesFrom+` - Use cardinality +constraints or OWL restrictions if needed diff --git a/journal-theme/semantic/constructs/EXPLAINME.md b/journal-theme/semantic/constructs/EXPLAINME.md deleted file mode 100644 index 6f8160e..0000000 --- a/journal-theme/semantic/constructs/EXPLAINME.md +++ /dev/null @@ -1,35 +0,0 @@ - -# 🧶 Semantic Constructs: Help & Guidance - -This folder contains semantic representations of narrative constructs in various formats: - -- `.jsonld` — Lightweight JSON for structured data (used by search engines, APIs) -- `.ttl` — RDF in Turtle format (ideal for Linked Data and SPARQL) -- `.owl` — Ontology fragments describing symbolic logic and relationships - -### ✅ Suggested Use Per Format - -| Format | Purpose | Best For | -|---------------|--------------------------------------|-----------------------------------| -| `.jsonld` | Easy embedding & SEO | HTML templates, rich results | -| `.ttl` | RDF graph publication | Linked Data, ontology browsing | -| `.owl` | Formal ontology & reasoning | Semantic inference, vocab modeling| - -Each construct may be referenced across posts, glosses, or portals. Semantic files help express agency, relationships, and narrative weight in machine-readable form. - ---- - -### 📌 About “Heavily Relational” - -This means the construct: -- Has **explicit semantic links** to other entities (e.g. `entanglesWith`, `knows`, `hasThread`) -- May be used in **reasoning engines** to infer relationships or class memberships -- Operates within a **symbolic network**, rather than being a standalone descriptor - -You can scale this up with properties like: -- `hasVeil`, `appearsIn`, `resonatesWith`, `originatesFrom` -- Use cardinality constraints or OWL restrictions if needed - diff --git a/journal-theme/semantic/glosses/EXPLAINME.adoc b/journal-theme/semantic/glosses/EXPLAINME.adoc new file mode 100644 index 0000000..c3cfc61 --- /dev/null +++ b/journal-theme/semantic/glosses/EXPLAINME.adoc @@ -0,0 +1,53 @@ +== 🧵 Glosses: Semantic Footnotes and Conceptual Annotations + +This directory houses symbolic footnotes—_glosses_—expressed in +structured formats. Glosses are conceptual threads that annotate, +clarify, or emotionally inflect entries and constructs across Sinople. + +Each gloss provides: - *Semantic richness* (for search engines and +agents) - *Symbolic depth* (via named terms and emotional motifs) - +*Interoperability* (through shared vocabularies like schema.org, SKOS, +or OWL) + +''''' + +=== 📁 Included Formats + +[width="100%",cols="17%,42%,41%",options="header",] +|=== +|Format |Purpose |Best For +|`+.jsonld+` |Lightweight, SEO-friendly glossary |HTML embedding, +structured search + +|`+.ttl+` |RDF Turtle for Linked Data |SPARQL, dataset description + +|`+.owl+` |Ontology of gloss types |Semantic reasoning, vocab reuse +|=== + +Glosses often appear via `+aria-describedby+` or inline semantic markup, +connecting pages to their deeper meanings. + +''''' + +=== 🔖 Naming Convention + +* `+gloss-term.jsonld+` — individual gloss + +* `+gloss-term.ttl+` — RDF definition + +* `+glosses.owl+` — shared ontology defining gloss types +(e.g. ResistanceGloss, FogGloss) + +Keep file names slugified and meaningful: `+fog-threading.jsonld+`, +`+stitched-memory.ttl+` + +''''' + +=== 🧬 Guidance for Contributors + +[arabic] +. Keep glosses short, symbolic, and evocative. +. Include links to where gloss is used in the journal. +. Align vocabularies where possible (e.g. `+schema:DefinedTerm+`, +`+skos:Concept+`, custom `+sin:GlossType+`) +. Don’t duplicate across formats unless justified by context. + +Every gloss is a stitched voice—name it with care. diff --git a/journal-theme/semantic/glosses/EXPLAINME.md b/journal-theme/semantic/glosses/EXPLAINME.md deleted file mode 100644 index 3075b5a..0000000 --- a/journal-theme/semantic/glosses/EXPLAINME.md +++ /dev/null @@ -1,45 +0,0 @@ - -# 🧵 Glosses: Semantic Footnotes and Conceptual Annotations - -This directory houses symbolic footnotes—*glosses*—expressed in structured formats. Glosses are conceptual threads that annotate, clarify, or emotionally inflect entries and constructs across Sinople. - -Each gloss provides: -- **Semantic richness** (for search engines and agents) -- **Symbolic depth** (via named terms and emotional motifs) -- **Interoperability** (through shared vocabularies like schema.org, SKOS, or OWL) - ---- - -## 📁 Included Formats - -| Format | Purpose | Best For | -|--------------|------------------------------------|-----------------------------------| -| `.jsonld` | Lightweight, SEO-friendly glossary | HTML embedding, structured search | -| `.ttl` | RDF Turtle for Linked Data | SPARQL, dataset description | -| `.owl` | Ontology of gloss types | Semantic reasoning, vocab reuse | - -Glosses often appear via `aria-describedby` or inline semantic markup, connecting pages to their deeper meanings. - ---- - -## 🔖 Naming Convention - -- `gloss-term.jsonld` — individual gloss -- `gloss-term.ttl` — RDF definition -- `glosses.owl` — shared ontology defining gloss types (e.g. ResistanceGloss, FogGloss) - -Keep file names slugified and meaningful: `fog-threading.jsonld`, `stitched-memory.ttl` - ---- - -## 🧬 Guidance for Contributors - -1. Keep glosses short, symbolic, and evocative. -2. Include links to where gloss is used in the journal. -3. Align vocabularies where possible (e.g. `schema:DefinedTerm`, `skos:Concept`, custom `sin:GlossType`) -4. Don't duplicate across formats unless justified by context. - -Every gloss is a stitched voice—name it with care. diff --git a/journal-theme/tests/aria-checklist.adoc b/journal-theme/tests/aria-checklist.adoc new file mode 100644 index 0000000..99ce8dc --- /dev/null +++ b/journal-theme/tests/aria-checklist.adoc @@ -0,0 +1,25 @@ +== ♿ ARIA Checklist for Sinople + +=== 🔗 Navigation + +* [x] `+