How to Read and Use the PALO Repository#

The PALO repository is both a public framework publication and a reproducible evidence workspace. It contains human-readable guidance, machine-readable governance contracts, local-first worked cases, developer-preview agentic components, tests and the generated website artifact. These layers have different authority and maturity. They should not be treated as interchangeable.

Repository: sev7enITA/PALOframework

Start with the version boundary#

Use three Git signals before interpreting a file:

1. Release metadata: this source baseline is v3.1.0, PALO Governance Control Plane, dated 23 August 2026. A Git tag is authoritative only after the maintainer publishes it.
2. Main branch: main is the reviewed public baseline after merged pull requests. It can move beyond a tag without creating a new release.
3. Open pull request or feature branch: this is proposed or unreleased work even when its files carry a candidate version. PALO-AI v2.7 is a released component baseline only when the maintainer publishes the corresponding platform release or tag.

The PALO Web platform and PALO-AI runtime have independent version lines. A website release number must not be used to imply that a developer-preview runtime is production-ready.

Choose the path that matches your role#

Non-technical reviewer#

1. Read README.md for scope, version and maturity.
2. Open the PALO Guide to translate a plain-language use case into phases, questions, controls and accountable outputs.
3. Run the preloaded Evidence Pack case to see how a case becomes a local Case File and Evidence Bundle.
4. Read CHANGELOG.md to distinguish released work from Unreleased work.
5. Use the Documentation Library for source-backed references and implementation boundaries.

No command line is required for this path.

Governance practitioner or assurance reviewer#

Start with the same Guide and Evidence Pack route, then inspect:

• data/ for the lifecycle, control, KPI/KRI, decision-gate, source and semantic registries;
• schemas/ for the validation contracts used by Case Files, evidence, decisions and agentic records;
• examples/worked-cases/ and evidence-pack/cases/ for synthetic, safely publishable examples;
• docs/ for methodology, source boundaries, integration guidance and production-readiness limits;
• release-manifest.json for component versions, publication scope and authority boundaries.

Treat source-backed context as an input to accountable review, not as an automatic decision, legal conclusion, certification or proof of operating effectiveness.

Developer evaluating PALO-AI#

PALO-AI is a reference implementation for isolated evaluation. Do not connect it to production agents, privileged tools, sensitive data or consequential workflows.

The main technical entry points are:

• packages/palo-mcp-server/ for the MCP and REST reference runtime;
• packages/n8n-nodes-palo-ai/ for the installable n8n evaluation package;
• examples/agentic-interface/ for Dify, n8n and MCP examples;
• examples/policy-as-code/ for the fail-closed OPA/Rego policy pattern;
• schemas/palo-agentic-*.schema.json for the Action Claim, decision, capability, receipt, outcome and incident contracts;
• PALO_AgenticCapabilityMatrix.html and PALO_AIProductionReadiness.html for evidence and remaining production gates.

Install and validate with the pinned Node.js toolchain:

git clone https://github.com/sev7enITA/PALOframework.git
cd PALOframework
npm ci
npm run validate:agentic
npm run validate
npm run build
npm run validate:dist
npm run build:check
npm run smoke

The validation sequence checks contracts, runtime tests, semantic projections, schemas, publication coverage, generated artifact exactness and browser flows. A passing test suite demonstrates conformance to the repository assertions; it is not independent certification or production authorization.

Understand authoring files and dist#

Root files and source directories are the authoring layer. The dist/ directory is the deterministic publication artifact generated by:

npm run build

Do not hand-edit dist/. Change the source, rebuild, run npm run build:check, and review the source and generated diff together. The same rule applies to generated semantic projections: change the canonical semantic source and use the documented generator workflow.

Read the evidence path, not only the feature list#

PALO should be evaluated as a chain:

question -> Guide route -> Case File -> Evidence Bundle -> control or policy decision
         -> execution evidence -> outcome verification -> review or reopen

Not every repository layer implements every step. PALO Web provides released local-first orientation and evidence handling. PALO-AM defines authority and oversight. PALO-AI demonstrates selected executable assurance contracts in developer preview. External security, identity, data, platform and enterprise controls remain necessary.

Contribute without widening authority#

During the activation focus, the preferred contribution is a synthetic or safely publishable Evidence Pack case:

npm run case:contribute -- --help

A contribution should:

• use a focused branch and small pull request;
• preserve version and authority boundaries;
• include or update tests and documentation;
• use only synthetic or safely publishable evidence;
• avoid secrets, personal data and private assessment workpapers;
• state allowed and prohibited actions, expected effect, verification method and limitations;
• pass the relevant validation commands before review.

Semantic contract changes require the generator, validation, change-impact and migration process documented in CONTRIBUTING.md. Security findings must follow SECURITY.md and must not be opened as public issues.

A practical reading rule#

For every artifact, ask four questions:

1. Version: is it released, on main, or only in an open pull request?
2. Maturity: is it implemented, developer preview, prototype, specified or roadmap?
3. Authority: is it a canonical definition, source-backed context, illustrative preview or pending human review?
4. Evidence: which test, schema, owner and reopen trigger support the claim?

If one of these answers is missing, the artifact is not ready to be used as an authoritative governance decision.