Contributing

Independent criticism and falsification attempts are especially valuable here. Good contributions include minimized counterexamples, stronger independent oracles, missing limitations, portability failures, clearer explanations, and reproductions on a different architecture or container runtime.

Report a result

Run:

./poc.sh test
./poc.sh run --run-id review-01

When opening an issue, include:

• Docker Engine and Compose versions;
• host OS and architecture;
• .runs/review-01/results/output.json;
• .runs/review-01/work/input-inventory.json;
• .runs/review-01/work/runtime-manifest.json;
• the exact command and exit status; and
• the smallest relevant stderr log for a failure.

Do not upload the complete .runs/ directory unless requested; raw files are checksummed and often unnecessary for triage.

Propose a change

1. State which clause in poc/contract.md changes or which existing obligation the change preserves.
2. Add a behavioral test through a public CLI or stable function boundary.
3. Run ./poc.sh test and a complete ./poc.sh run.
4. Keep generated runs, caches, logs, and build output out of Git.
5. Separate semantic claims from descriptive performance observations.

Refactoring must preserve the supported claim. If reproducible evidence shows that the claim itself is wrong, stop and request an explicit design decision before changing the contract, definition, oracles, or purpose. Do not mask a failed obligation with a workaround or fallback path.

Keep commits atomic and write their messages in English. Avoid speculative abstractions, premature optimization, and production infrastructure that does not strengthen the bounded claim.

Improve the documentation

The documentation site publishes the repository's canonical Markdown directly. Do not copy contract, compatibility, artifact, or architecture prose into a second site-only source. Treat Markdown containing HTML and every Vue theme component as executable review surface because VitePress evaluates them during the build.

For a documentation change, run:

npm ci --ignore-scripts
npm run docs:check

Also run the POC gates when a documentation change touches a supported command, machine-owned fact, contract interpretation, artifact schema, runtime boundary, or diagram of executable behavior. Static presentation changes that cannot affect those subjects require the documentation gates but do not substitute for the complete POC gate before a release or final handoff.

Keep diagrams focused on one question, retain their PlantUML sources, render them with the repository's pinned local profile, and commit the validated SVG output. Do not add remote rendering, remote includes, embedded active SVG content, analytics, or hosted search.

Language

All project content must be written in US English, including source names, comments, documentation, tests, configuration labels, user-facing messages, and commit messages. An established term from another language may be used only when that specific term is required.

Contribution licensing

Unless explicitly stated otherwise, contributions intentionally submitted for inclusion in this repository are provided under the Apache License 2.0. By submitting a contribution, you represent that you have the right to provide it under those terms.