Metadata-Version: 2.4
Name: ptsip
Version: 0.1.0a1
Summary: Reference development tooling for the Product–Toolchain SDK Isolation Policy
Author: kwaksinwoo01
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/kwaksinwoo01/ptsip
Project-URL: Specification, https://github.com/kwaksinwoo01/ptsip
Project-URL: Issues, https://github.com/kwaksinwoo01/ptsip/issues
Keywords: architecture,sdk,toolchain,governance,validation,ptsip
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyYAML<7,>=6.0
Requires-Dist: jsonschema<5,>=4.23
Provides-Extra: dev
Requires-Dist: build<2,>=1.2; extra == "dev"
Requires-Dist: pytest<9,>=8; extra == "dev"
Dynamic: license-file

# PTSIP — Product–Toolchain SDK Isolation Policy

**Status:** Draft Specification 0.2.0  
**Canonical repository:** `https://github.com/kwaksinwoo01/ptsip`  
**Specification family:** Software architecture / SDK governance / development toolchain isolation  
**Reference Tool:** `0.1.0a1`  
**License:** Apache License 2.0

PTSIP (Product–Toolchain SDK Isolation Policy) is a project-defined architecture policy for managing Software Development Kits (SDKs) according to their **purpose, packaging responsibility, dependency boundary, build environment, and lifecycle**.

PTSIP distinguishes two primary SDK planes:

- **Product SDK Plane** — SDKs and libraries that are part of, support, or are distributed with the product.
- **Toolchain SDK Plane** — SDKs and development tools used to build, validate, migrate, test, generate, inspect, release, or otherwise develop the product.

The central rule is:

> **Purpose precedes reuse.** A component is classified by why it exists and which lifecycle owns it before code-sharing opportunities are considered.

PTSIP does not claim that host/target separation, build-time/runtime separation, toolchain isolation, or independent lifecycle management are new ideas. PTSIP is a named policy that combines these established ideas into a stronger SDK-governance boundary with explicit conformance and machine-readable project rules.

## Consumer Repository non-intrusion

PTSIP does not require adopting repositories to create PTSIP-specific `docs/`, `tools/`, `.ptsip/`, cache, or report directories. External PTSIP inspection and Pilot tooling is read-only against the Consumer Repository by default, and tool-owned state should remain outside that repository unless the user explicitly chooses otherwise.

A project may voluntarily provide a machine-readable profile for enforced conformance, but the profile location remains a project/configuration concern rather than a required repository topology.

## Reference Tool

This canonical repository also contains the independently versioned **PTSIP Reference Tool** under `src/ptsip/`. The repository is shared; the Specification and Tool release lifecycles are not.

The Python distribution name and CLI command are both `ptsip`:

```powershell
pip install ptsip
ptsip --version
ptsip spec
ptsip doctor .
ptsip inspect .
ptsip pilot .
ptsip validate .
```

PyPI publication is not yet complete for `0.1.0a1`; source development can use:

```powershell
pip install -e ".[dev]"
```

`inspect` and `pilot` do not modify the Consumer Repository. Pilot state is stored outside the repository by default (`%LOCALAPPDATA%\PTSIP` on Windows and the platform-equivalent user state directory elsewhere). `PTSIP_HOME` can override that location.

Tool releases use the `tool-v*` tag/release namespace. Specification releases may use a separate `spec-v*` namespace, so both lifecycles can remain independently governed inside one Git repository.

## Why PTSIP exists

In large or long-lived codebases, a validator, schema helper, generator, migration module, or common utility can gradually become shared by both product runtime code and development tooling. That often creates hidden coupling:

- development-only dependencies leak into product packaging;
- toolchain changes force product releases;
- product compatibility concerns block toolchain evolution;
- generic `common` packages erase architectural ownership;
- code reuse becomes more important than lifecycle independence.

PTSIP makes the opposite trade-off: **lifecycle and responsibility boundaries are primary; reuse is conditional.**

## Repository map

### Specification ownership

- [`spec/PTSIP-SPEC.md`](spec/PTSIP-SPEC.md) — normative architecture specification.
- [`spec/PTSIP-TERMINOLOGY.md`](spec/PTSIP-TERMINOLOGY.md) — canonical terms and meanings.
- [`spec/PTSIP-GOVERNANCE.md`](spec/PTSIP-GOVERNANCE.md) — specification change and exception governance.
- [`spec/PTSIP-CONFORMANCE.md`](spec/PTSIP-CONFORMANCE.md) — requirements for claiming PTSIP conformance.
- [`registry/ptsip-registry.yaml`](registry/ptsip-registry.yaml) — machine-readable terminology and rule registry.
- [`schemas/ptsip-profile.schema.json`](schemas/ptsip-profile.schema.json) — project-profile schema.
- [`reference/REFERENCE-ARCHITECTURE.md`](reference/REFERENCE-ARCHITECTURE.md) — informative reference architecture.
- [`adoption/ADOPTION-GUIDE.md`](adoption/ADOPTION-GUIDE.md) — migration/adoption sequence.
- [`agents/AGENT-CONTRACT.md`](agents/AGENT-CONTRACT.md) — concise rules for coding agents.
- [`profiles/example.ptsip.yaml`](profiles/example.ptsip.yaml) — example project profile.
- [`decisions/`](decisions/) — specification architecture decision records.
- [`CHANGELOG.md`](CHANGELOG.md) — Specification change history.

### Reference Tool ownership

- [`src/ptsip/`](src/ptsip/) — installable Python Reference Tool implementation.
- [`tests/`](tests/) — Reference Tool tests.
- [`pyproject.toml`](pyproject.toml) — PyPI distribution/build metadata for `ptsip`.
- [`.github/workflows/tooling-test.yml`](.github/workflows/tooling-test.yml) — Python 3.11–3.13 Tool CI.
- [`.github/workflows/tooling-release.yml`](.github/workflows/tooling-release.yml) — `tool-v*` PyPI Trusted Publishing workflow.
- [`TOOLING-CHANGELOG.md`](TOOLING-CHANGELOG.md) — independently versioned Tool change history.

### Shared repository assets

- [`LICENSE`](LICENSE) — Apache License 2.0 terms for this repository.
- [`README.md`](README.md) — project overview and ownership map.

## Normative language

The words **MUST**, **MUST NOT**, **SHOULD**, **SHOULD NOT**, and **MAY** are used as normative requirement keywords in the sense of BCP 14 (RFC 2119 as updated by RFC 8174) when, and only when, they appear in uppercase.

References:

- RFC 2119: https://www.rfc-editor.org/info/rfc2119/
- RFC 8174: https://www.rfc-editor.org/info/rfc8174/

## Relationship to existing concepts

PTSIP is related to, but not identical with:

- host / execution / target separation;
- build-time / runtime dependency separation;
- toolchain isolation;
- dependency graph isolation;
- independent release lifecycle management;
- hermetic or reproducible build practices.

## Maturity

PTSIP 0.2.0-draft is a **draft project-defined specification**, not an ISO, IEEE, IETF, CNCF, or other external industry standard. The public specification is intended to make the term reproducible: a person, coding agent, or external validator should be able to identify the governing specification and independently evaluate a repository against it.

The Reference Tool `0.1.0a1` is an alpha implementation intended for read-only inspection, Pilot evidence collection, and project-profile validation. It does not yet claim complete automated PTSIP conformance enforcement.

## License

This repository, including the PTSIP specification and Reference Tool unless explicitly stated otherwise, is licensed under the **Apache License, Version 2.0**. See [`LICENSE`](LICENSE).
