Developer tooling

These tools are for framework maintainers. Kiyo users never run them. There is no Kiyo CLI, generator, or scaffolding for consumer projects.

Requirements

Requirement	Detail
Python	Standard library only. The framework exercised Python 3.11.9 and notes that this “is not a declared minimum version”. The code uses `sys.orig_argv` and `sys.stdlib_module_names`, so Python 3.10 or later is required
Third-party packages	None; `release_candidate.py` fails with “Unreviewed developer imports” if a non-stdlib import appears
Git	Required; the tools record `git rev-parse HEAD`
Working directory	Repository root
OS	Recorded runs were on Windows (`Windows-10-10.0.26200-SP0`)

Run every command with python -B so no __pycache__ is written into the tree.

Write behavior common to all tools

The tools never overwrite. Outputs are opened in exclusive-create mode. Existing output that differs is refused (“Existing output differs; refusing overwrite”), and identical output is a no-op. Always pass fresh output and report paths, and keep historical inventories and results.

Commands

Tool	Command	Output
Distribution builder	`python -B tools/package_distributions.py --output <fresh-archive-directory> --inventory <fresh-inventory.json>`	Three deterministic ZIPs and a `kiyo-distribution-inventory-1` inventory
Claude packager	`python -B tools/package_claude.py --output <dir> --inventory <file>`	Claude package (default `dist/claude`)
Codex packager	`python -B tools/package_codex.py --output <dir> --inventory <file>`	Codex package; the output folder name must be `kiyo-axiom-framework`
Copilot packager	`python -B tools/package_copilot.py --output <dir> --inventory <file>`	Copilot package; the output folder name must be `kiyo-axiom-framework`
Payload verifier	`python -B tools/verify_payload.py <payload> <claude\|codex\|copilot> --deny-probe <path-outside-payload>`	JSON result with files, skills, `shared_per_skill`, `local_links`, `payload_digest`
Release rehearsal	`python -B tools/release_candidate.py --output dist/releases/<fresh-run-name>`	Six-stage local rehearsal; publication always `BLOCKED`
Acceptance audit	`python -B tools/acceptance_handoff.py --output docs/evidence/acceptance/<fresh-dir>`	Final acceptance checks FA-01 to FA-05

Arguments

Script	Arguments
`package_claude.py`	`--output` (default `dist/claude`; not under `src/` or `platforms/`), `--inventory` (default `docs/evidence/claude/package-inventory.json`; not inside output)
`package_codex.py`	`--output` (default `dist/codex/kiyo-axiom-framework`), `--inventory` (default `docs/evidence/codex/package-inventory.json`)
`package_copilot.py`	`--output` (default `dist/copilot/kiyo-axiom-framework`), `--inventory` (default `docs/evidence/copilot/package-inventory.json`)
`package_distributions.py`	`--output` (default `dist/archives`; not inside src, platforms, tools, or tests), `--inventory` (default `docs/evidence/packaging/artifact-inventory.json`)
`verify_payload.py`	positional `payload`; positional `target` (`claude`, `codex`, `copilot`); `--deny-probe` (required, outside the payload)
`release_candidate.py`	`--output` (required; a fresh direct child of `dist/releases` matching `[A-Za-z0-9][A-Za-z0-9._-]*`)
`acceptance_handoff.py`	`--output` (required; a fresh direct child of `docs/evidence/acceptance`)

Typical maintainer workflow

flowchart LR
accTitle: Maintainer workflow
accDescr: Edit canonical source or overlays, update the allowlist if files changed, build into fresh paths twice and compare, run static, packaging and behavioral helper tests with fresh report paths, review evidence, and keep publication blocked until owner decisions.
E[Edit src/kiyo or platforms/*] --> A{New or removed<br/>product files?}
A -- yes --> AL[Update tools/packaging-inputs.json]
A -- no --> B
AL --> B[Build into fresh paths<br/>package_distributions.py]
B --> C[Rebuild and compare<br/>inventories + archives]
C --> T[Run tests with fresh --report paths]
T --> R[Review evidence;<br/>update docs and counts]
R --> G[Publication stays BLOCKED<br/>until owner decisions]