# Contributing to praxis-stack

Thank you for helping evolve a self-auditing session-bootstrap system.
This project is intentionally small at the core: two skills (**megapraxis**,
**metamegapraxis**), a portable package, and a public Cloudflare Pages surface
that explains the system and shows live scrubbed audit state.

Live site: https://praxis-stack.pages.dev  
Technical white paper: https://praxis-stack.pages.dev/whitepaper  
Code of conduct: https://praxis-stack.pages.dev/CODE_OF_CONDUCT.md  
Security: https://praxis-stack.pages.dev/SECURITY.md  
License: https://praxis-stack.pages.dev/LICENSE (MIT)

## What you can contribute

| Kind | Examples | Notes |
|---|---|---|
| Skill fixes | trap probes, boot modes, render contracts | Prefer content-anchors, not line pins |
| Adapters | new harness drop-ins under `adapters/` | Keep install one-shot; no silent network calls |
| Docs | install paths, white paper errata, llms.txt | Tarski-honest: name residuals, never invent counts |
| Site / package | Pages UI, exporter scrub rules, package build | Production deploy branch is **master** |
| Trap catalog | new silent-failure classes with probe + fix | Must be disk/runtime verifiable |
| Bridges | short-circuits, templates, delta-scopes | Manifest integrity required |

## What not to contribute (without discussion)

- Silent default of unknowns into “CLOSED” or “complete”
- Fabricated skill/agent counts from truncated listings
- MCP / credentials / hooks in the core plugin (by design: instruction skills only)
- Machine-identifying data in published snapshots
- Recursive metamegapraxis self-invocation patterns

## Development loop (MetaMethodology)

1. **Orient** — run `/megapraxis` (or filesystem-fallback) in your harness.
2. **Audit** — `/metamegapraxis` for trap roll-call + residuals.
3. **Propose** — write `_proposed_*.diff` artifacts (or PR-equivalent patches).
4. **Apply** — only with explicit operator go-ahead (`apply` / merge).
5. **Verify** — `validate.py`, package rebuild, live checks on Proven Cycle.
6. **Converge** — name decidable / semi-decidable / undecidable leftovers.

When multi-lens review is needed, compose a SwarmInvocation; do not auto-dispatch
expensive swarms on first install.

## Get the source

```text
# Zip package (skills + installer + adapters)
curl -sL https://praxis-stack.pages.dev/pkg/praxis-stack-skills.zip -o praxis-stack-skills.zip

# Dumb-HTTP git (also Codex / Claude marketplace)
git clone https://praxis-stack.pages.dev/git/praxis-stack.git
```

There may not be a single public GitHub “upstream” for every fork. The site-served
git tree and zip are the **canonical distribution surfaces** for the portable skills
package. Forks should keep provenance (package version + SwarmInvocation notes).

## Coding norms

1. **Truth-on-disk** — every user-visible claim maps to a probeable fact, or is omitted.
2. **Content anchors** — cite symbols / grep-stable phrases, never fragile line numbers.
3. **Tarski honesty** — residuals named with class; never silently absorbed.
4. **Windows-safe paths** — avoid `/tmp/` for durable artifacts (trap #16).
5. **Real Python** — never bare `python` on Windows for validation (trap #6); use venv or `py`.
6. **Production branch** — `wrangler pages deploy … --branch=master` (not `main`).

## Pull request / patch checklist

- [ ] Change description states the trap, residual, or feature addressed
- [ ] Evidence is content-anchored
- [ ] No secrets, absolute home paths, or usernames in committed docs/snapshots
- [ ] Skills package rebuilt if skill text changed (`build_package.py`)
- [ ] `validate.py` (or equivalent) passes when available
- [ ] Undecidable leftovers listed if “complete” is claimed

## Communication

Prefer artifacts over vibes:

- Trap status with probe evidence  
- SwarmInvocation name-encoding for cycle provenance  
- Short-circuit certificates under `/demo/*.json` for install paths  

## License of contributions

By contributing, you agree your contributions are licensed under the MIT License
(same as the project).