Contributing to PALO Framework

August 16, 2026 · View on GitHub

Semantic contract changes

PALO v3 semantic sources are versioned public contracts. Change the semantic source through the documented generator workflow, then run npm run semantic:generate, npm run semantic:validate and npm run semantic:release. Do not hand-edit the generated Explorer graph or lifecycle projection. Breaking identifier, meaning, cardinality, authority-boundary or mapping changes require a major semantic version, a change-impact record, migration gates and updated valid/invalid fixtures.

First off, thank you for considering contributing to PALO!

Fast path: contribute a case

During the 30-day activation freeze, the most valuable contribution is one synthetic or safely publishable Evidence Pack case. Generate the Case File and pull request body with:

npm run case:contribute -- \
  --slug retail-returns-assistant \
  --title "Retail returns assistant" \
  --sector retail \
  --scenario "An assistant drafts a recommendation while a named employee approves refunds." \
  --community builders \
  --author "@your-github-handle"

Complete the generated TODO fields, then run:

npm run case:contribute -- --validate-all
npm run evidence:test
npm run validate

The command does not push, open a pull request or transmit case content. Cases must state allowed and prohibited actions, an observable expected effect, an independent verification method and their non-production boundary.

Code of Conduct
How Can I Contribute?
Development Setup
Style Guidelines
Pull Request Process

Use a clear and descriptive title
Describe the exact steps to reproduce the problem
Provide specific examples
Describe the behavior you observed and expected
Include screenshots if applicable
Note your browser and version

Suggesting Enhancements

Enhancement suggestions are tracked as GitHub issues. When creating an enhancement suggestion:

Use a clear and descriptive title
Provide a detailed description of the suggested enhancement
Explain why this enhancement would be useful
List any similar features in other projects if applicable

Documentation

Fix typos or clarify language
Add missing documentation
Improve code comments
Write tutorials or guides

Translations

We welcome translations! Currently available:

English (default)
Italian (partial)

To add a new language:

Copy the English version of the file
Add language suffix (e.g., _DE.html for German)
Translate all content
Submit a pull request

Development Setup

Prerequisites

Modern web browser (Chrome, Firefox, Safari, Edge)
Text editor (VS Code recommended)
Git

Local Development

# Clone your fork
git clone https://github.com/YOUR-USERNAME/PALOframework.git
cd PALOframework

# Create a branch for your feature
git checkout -b feature/your-feature-name

# Start a local server (optional, but recommended for testing)
python3 -m http.server 8000

# Open in browser
open http://localhost:8000

Style Guidelines

Text and Git metadata

Use plain ASCII punctuation in source text, generated pages, commit messages, tag messages and ref names.
Use the normal hyphen (-), straight quotes (' and "), three periods (...) and ASCII arrows (->) when needed.
Do not use typographic dashes, typographic quotes, Unicode ellipses, decorative separators, emoji or invisible spacing characters.
Letters with language-specific accents and necessary currency symbols remain valid.
Run npm run validate:text-style before committing. The P0 gate applies the same rule to source files, generated dist files and current Git metadata.