Metadata-Version: 2.4
Name: PTSIP
Version: 0.3.8a2
Summary: Reference tooling for primary lifecycle ownership and responsibility isolation
Author: Kinirin
Maintainer: Kinirin
License-Expression: LicenseRef-PTSIP-Community-Reciprocity-1.0
Project-URL: Homepage, https://github.com/Kinirin/PTSIP
Project-URL: Specification, https://github.com/Kinirin/PTSIP
Project-URL: Issues, https://github.com/Kinirin/PTSIP/issues
Keywords: architecture,lifecycle,governance,validation,delivery,operations,ptsip
Classifier: Development Status :: 4 - Beta
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: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: License-Authority/license-authority.yaml
License-File: License-Authority/LICENSE.md
License-File: License-Authority/NOTICE.md
License-File: License-Authority/LICENSE-GUIDE.md
License-File: License-Authority/LICENSE-HISTORY.md
License-File: License-Authority/COMMERCIAL-USE.md
Requires-Dist: PyYAML<7,>=6.0
Requires-Dist: jsonschema<5,>=4.23
Provides-Extra: github-app
Requires-Dist: PyJWT[crypto]<3,>=2.10; extra == "github-app"
Provides-Extra: dev
Requires-Dist: build<2,>=1.2; extra == "dev"
Requires-Dist: pytest<9,>=8; extra == "dev"
Requires-Dist: setuptools>=77.0.3; extra == "dev"
Dynamic: license-file

<p align="right">
  English | <a href="README.ko.md">한국어</a>
</p>

# PTSIP — Primary Lifecycle Ownership and Responsibility Isolation Policy

**Status:** Tool `0.3.8a2` repository-namespace stabilization prerelease — publication pending<br>
**Tool/package version:** `0.3.8a2`<br>
**Project Profile contract:** `pp.1.02`<br>
**Specification family:** `0.3.7-draft`<br>
**Bound immutable Specification revision:** `3c47816770d194ae42f98faedc911d980db0e62a`<br>
**License authority:** [`License-Authority/`](License-Authority/) (closed authority boundary; references elsewhere are non-authoritative)<br>
**License effective time:** `2026-09-15T00:00:00Z` (UTC)<br>
**Localized documentation:** `README.md` is canonical. Localized README files are regenerated on `main` by the self-hosted Argos Translate workflow; if a translation conflicts with this file, this file governs.

PTSIP is a project-defined architecture policy for separating project responsibilities by **primary lifecycle ownership** while preserving explicit architecture intent, lifecycle isolation, reproducible conformance, verification-purpose separation, and multi-environment decision consistency.

> **Purpose precedes reuse.** Classify a coherent responsibility by why it exists and which lifecycle owns it before optimizing for code sharing.

Tool `0.3.8a2` is a repository-namespace stabilization prerelease built on the already-published `0.3.8a1` bridge and the same frozen Specification binding. It preserves the proposed-candidate bridge while establishing `.ptsip/` as the canonical repository-local ownership boundary for PTSIP-managed contracts, registries, configuration, task/operation metadata, and execution state. Canonical repository indexes use JSON. This release reserves Task and runtime namespaces but does not claim a completed generic Task Engine, Go runtime, or Tool `0.4.0` capability-recovery implementation.

## Primary lifecycle ownership

Canonical Tool `0.3.8a2` classifications remain exactly:

| Classification | Meaning |
| --- | --- |
| `PRODUCT` | Responsibility primarily owned by the Product lifecycle. |
| `DEVELOPMENT_TOOLING` | Development-lifecycle responsibility used to create, inspect, validate, transform, generate, migrate, analyze, test, or otherwise support development. |
| `DELIVERY` | Responsibility for release preparation, packaging, publication, promotion, distribution, or deployment to the delivery destination. |
| `OPERATIONS` | Ongoing post-delivery responsibility for health, recovery, reconciliation, maintenance, and operation. |
| `NEUTRAL_CONTRACT` | Deliberately non-executable, non-owning contract responsibility with lifecycle-independent governance. |

`UNKNOWN`, `CONFLICT`, `INCOMPLETE`, `PENDING`, confidence values, and migration states are workflow/evaluation states, not additional classifications.

### Tool 0.3.5 compatibility boundary

Tool `0.3.5` historically used:

```text
PRODUCT
TOOLCHAIN
NEUTRAL_CONTRACT
```

Tool `0.3.8a2` preserves the five-classification model established by Tool `0.3.6`. `TOOLCHAIN` is therefore **legacy Tool `0.3.5` input**, not a current canonical alias. A legacy Toolchain responsibility may become `DEVELOPMENT_TOOLING`, `DELIVERY`, `OPERATIONS`, or require a split depending on its actual lifecycle ownership. Blind `TOOLCHAIN -> DEVELOPMENT_TOOLING` rewriting is prohibited.

Tool `0.3.8a2` provides evidence-bound direct current-target migration for explicitly supported historical sources. Migration capability remains separate from repository adoption authority and never turns inference into project intent.

## Classification is not path or technology

Classification follows the governing lifecycle obligation, not filename, directory, language, framework, executable status, workflow provider, compilation behavior, runtime duration, test status, or confidence score.

Examples:

```text
Product-specific verification responsibility       -> PRODUCT
Reusable verification framework / test SDK         -> DEVELOPMENT_TOOLING
Product runtime implementation                      -> PRODUCT
Release-unit assembly / publication automation      -> DELIVERY
Post-deployment health or recovery automation       -> OPERATIONS
Independent non-executable shared contract          -> NEUTRAL_CONTRACT
```

Paths such as `tests/`, `tools/`, `deploy/`, `ops/`, or `.github/workflows/` are evidence context only. They do not become architecture authority.

## Responsibility Map v2

Tool `0.3.8a2` uses Responsibility Map v2 as the project-owned architecture declaration model. It keeps several axes independent:

```text
classification
    = primary lifecycle ownership

roles
    = coarse responsibility characteristics

relationships
    = project-owned typed directed semantics

source/derived provenance
    = where declaration/materialized architecture came from

VPMS Verification Purpose
    = why verification exists and what it protects
```

Canonical roles are:

```text
IMPLEMENTATION
VERIFICATION
AUTOMATION
CONFIGURATION
DOCUMENTATION
GOVERNANCE
```

Canonical typed relationships are:

```text
IMPORTS
LINKS
LOADS
INVOKES
READS
GENERATES
BUILDS
PACKAGES
PUBLISHES
DEPLOYS
VERIFIES
MANAGES
DOCUMENTS
SPECIFIES
GOVERNS
```

An associated artifact is a project-owned non-component support surface subordinate to one classified anchor component. It must not be used to hide independently governable executable or lifecycle responsibility.

## Explicit, template, and hybrid declarations

Canonical source modes are:

```text
explicit
    repository directly declares the complete map

template
    repository explicitly selects one immutable revision-bound template

hybrid
    repository explicitly selects a template and adds project-owned
    overrides, extensions, or removals
```

The initial template catalog contains:

```text
python-package-library
python-cli-application
mixed-product-development-delivery
```

Template selection is explicit. PTSIP does not automatically select a template from repository layout, language, framework detection, manifests, or confidence.

## Source declaration and Effective Responsibility Map

All source modes resolve through deterministic, non-authoritative materialization:

```text
Source Project Profile
        |
        v
explicit / template / hybrid
        |
        v
deterministic materialization
        |
        v
Canonical Effective Responsibility Map
        |
        +--> validation / conformance
        +--> clarification / adoption
        +--> narrow VPMS read-only projection
```

The Source Project Profile remains project-owned architecture authority. Materialization must not select templates, infer ownership, repair invalid architecture, or silently rewrite the source declaration.

The resolved view retains declaration provenance such as:

```text
PROJECT_EXPLICIT
TEMPLATE
PROJECT_OVERRIDE
PROJECT_EXTENSION
PROJECT_REMOVAL
```

and has deterministic digest identity for reproducibility. Neither provenance nor digest becomes a replacement architecture authority.

## Install and use

PTSIP requires Python 3.11 or newer.

Install the latest **published** release:

```powershell
python -m pip install PTSIP
```

Upgrade to the latest **published** release:

```powershell
python -m pip install --upgrade PTSIP
```

Tool `0.3.8a2` is a prerelease. A normal `pip install PTSIP` may continue to select the latest stable release unless prereleases are explicitly requested.

After publication, install this prerelease explicitly with:

```powershell
python -m pip install "PTSIP==0.3.8a2"
```

For source development on this release line:

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

Common commands:

```powershell
ptsip --version
ptsip spec
ptsip doctor .
ptsip inspect .
ptsip pilot .
ptsip adopt --help
ptsip validate .
ptsip clarify .
ptsip gate .
ptsip resolve --help
ptsip conform .
```

New project-owned profiles are selected through `.ptsip/profiles/index.json`; the catalog's `default_profile` resolves the active `*.ptsip.yaml` resource. Repository-root `ptsip.yaml` remains a compatibility/migration input, and an explicit `--profile` path still takes precedence.

## Adoption and decision authority

Repository evidence is not architecture authority. Candidate discovery, path names, templates, heuristics, and agent confidence can support review but cannot manufacture project intent.

Canonical Tool `0.3.8a2` explicit adoption facts center on `classification` as lifecycle ownership authority. New canonical decisions use facts such as:

```text
classification
purpose
shipped
runtime_required
executable
```

The historical `lifecycle_owner` field is legacy migration evidence, not a second Tool `0.3.8a2` ownership authority.

Example dry-run:

```powershell
ptsip adopt . `
  --component tools `
  --classification DEVELOPMENT_TOOLING `
  --purpose "Repository-local generation tooling" `
  --shipped no `
  --runtime-required no `
  --executable yes `
  --json
```

Apply only after reviewing the planned declaration change:

```powershell
ptsip adopt . `
  --component tools `
  --classification DEVELOPMENT_TOOLING `
  --purpose "Repository-local generation tooling" `
  --shipped no `
  --runtime-required no `
  --executable yes `
  --apply `
  --json
```

Prepared writes must reject stale repository/profile state.

PTSIP distinguishes four things that must not be collapsed:

```text
Specification
    -> normative rules

Decision Authority
    -> which explicit coordinated architecture answer won

Project Profile / Responsibility Map
    -> durable project-owned declaration

Observed evidence
    -> what the repository and artifacts actually do
```

A Decision Authority does not replace the Project Profile selected by `.ptsip/profiles/index.json` and does not prove conformance. Legacy root `ptsip.yaml` remains compatibility input only.

## Distributed decision coordination

The Reference Tool supports repository-distributed decision coordination through:

```text
refs/heads/ptsip-policy
```

GitHub is a Tool backend, not a universal Specification dependency. The coordination model preserves stable decision identity, first-valid-resolution-wins, stale-writer-safe conditional mutation, authority freshness, deterministic reconciliation, fail-closed behavior, and separation of global decision state from clone-local application state.

PTSIP uses action-time synchronization rather than continuous background polling.

## Product Artifact boundary

Artifact ownership is independent from producer ownership. A `DEVELOPMENT_TOOLING` or `DELIVERY` component may validly build a `PRODUCT` artifact, but the resulting artifact must still satisfy the Product package boundary.

Tool `0.3.8a2` supports snapshot-bound Product Artifact evidence. Release verification checks actual built distribution content rather than treating packaging configuration as proof. Product distribution verification rejects definite non-Product implementation leakage under `PTSIP-PKG-001`.

## VPMS — Verification Purpose Management System

PTSIP and VPMS answer different questions:

```text
PTSIP
    Who owns this responsibility across its lifecycle?

VPMS
    Why does this Verification Case exist, and what does it protect?
```

PTSIP classification and VPMS Verification Purpose remain separate axes. PTSIP core does not depend on VPMS. VPMS consumes only a narrow read-only projection of already-resolved PTSIP metadata.

The current VPMS compatibility vocabulary may still contain `PRODUCT | TOOLCHAIN`. VPMS `TOOLCHAIN` is not a canonical Tool `0.3.8a2` PTSIP classification.

VPMS verification PASS does not imply PTSIP `CONFORMANT`, and PTSIP `CONFORMANT` does not imply functional verification PASS.

## Conformance

`ptsip conform` evaluates declared architecture and observed evidence against applicable PTSIP rules after source declarations are resolved to the Effective Responsibility Map.

Completed outcomes are:

| Exit code | Outcome |
| --- | --- |
| `0` | `CONFORMANT` |
| `5` | `NON_CONFORMANT` |
| `6` | `INCOMPLETE` |

A valid profile does not prove conformance. Missing evidence that could hide an applicable mandatory rule remains fail-closed as `INCOMPLETE`; the Tool does not force an uncertain repository green.

## Dependency analysis and bounded review

The WU-13 development CLI reconciles dependency evidence before presenting items for review:

```powershell
ptsip dependency analyze .
ptsip dependency analyze . --component ptsip-core --json
ptsip dependency review-pack . --max-items 8 --max-context-bytes 12000
ptsip dependency validation-plan . --changed src/ptsip/dependency_analysis.py --json
```

`--component` requires a component ID declared in the selected Project Profile. All three commands accept `--profile`; omit `--component` to analyze the repository. The examples using `ptsip-core` and `src/ptsip/dependency_analysis.py` apply to this repository and must be replaced with consumer-owned component IDs and tracked paths elsewhere.

Analysis reports four advisory actionability buckets:

| Bucket | Next action |
| --- | --- |
| `AUTO_RESOLVED` | Reuse the recorded mechanical evidence. |
| `REPOSITORY_DEFECT` | Review the evidence-backed remediation candidate; application remains explicit. |
| `REVIEW_REQUIRED` | Review bounded source context and the unresolved support or ownership question. |
| `RESOLVER_LIMITATION` | Retain incomplete evidence and address the resolver or supply authoritative evidence. |

The default human output is concise. `--json` preserves the detailed machine report; keep large reports in an external working directory instead of placing the entire report in an AI prompt. A Review Pack includes only `REVIEW_REQUIRED` items, defaults to at most eight items and 12,000 UTF-8 bytes per item, and limits each item to four source files. Its summary distinguishes selected and deferred items. An item is deferred when its import snippet cannot fit the context budget. Generation does not perform AI review; record actual review counts separately from the generator's `ai_reviewed_items: 0`.

Review Packs and reusable Python source evidence are stored in external Tool-owned state by default. `review-pack --output <new-report.json>` chooses an explicit report path; it rejects overwriting tracked repository content. Source evidence is reused only when its cache identity matches, while repository snapshots are checked freshly. Corrupt or stale cache entries are recomputed.

`validation-plan` proposes focused and component commands from declared verification ownership and observed import reachability. Repeat `--changed` for multiple tracked paths. It does not execute the commands or replace the repository's full regression and exact-SHA verification requirements.

Dependency analysis and Review Packs do not evaluate conformance or establish architecture authority. Run `ptsip conform .` for the strict outcome. Unresolved verification dependencies remain blocking in a separate verification bucket; dynamic or ambiguous local imports remain unresolved when their targets cannot be established mechanically. A support-contract decision and any consumer change remain explicit.

## Tool and Specification lifecycle

The PTSIP Tool and PTSIP Specification are independently versioned.

- `pyproject.toml` owns Tool/package source version;
- `ptsip --version` reports installed Tool version;
- `ptsip spec` reports the exact Specification family and immutable revision bound to the Tool;
- `spec/`, `schemas/`, and `registry/` contain canonical Specification assets;
- `src/ptsip/specdata/` contains matching embedded machine-readable assets.

The current source tree exposes independent PP and Specification identities:

```text
Project Profile pp.1.02
Specification 0.3.7-draft
SPEC_REVISION 3c47816770d194ae42f98faedc911d980db0e62a
```

The already-published Tool `0.3.8a1` release retains its historical PP binding
in its Tool release note; advancing the PP contract does not rewrite that Tool history.

A new immutable revision is required only for a genuine normative change. Release workflow, test, planning, status, or documentation-only changes do not move `SPEC_REVISION` by themselves.

## Tool 0.3.8a2 release identity

Tool `0.3.8a2` is a repository-namespace stabilization prerelease with a deliberately narrow compatibility goal.

```text
Tool:             0.3.8a2
Project Profile:  pp.1.02
Specification:    0.3.7-draft
SPEC_REVISION:    3c47816770d194ae42f98faedc911d980db0e62a
Release scope:    canonical .ptsip repository namespace + JSON index routing
```

This Tool release does not introduce a new Specification family or Project Profile contract. It establishes `.ptsip/` as the canonical repository-local PTSIP ownership boundary and `.ptsip/index.json` as the root machine-routing entry point. `.ptsip/profiles/index.json` is the canonical local Project Profile catalog representation. The former `.ptsip/profiles/index.yaml` form is accepted only as compatibility input for migration.

`.ptsip/tasks/` and `.ptsip/runtime/` are reserved namespaces in this release. Reservation does not claim a complete generic Repository Task Engine or finalized runtime persistence semantics, and the absence of those capabilities does not authorize a coding agent to establish another PTSIP control-plane root under `tools/`, `scripts/`, or another repository path.

Release scope is recorded in [`releasenote/tool/0.3.8a2.md`](releasenote/tool/0.3.8a2.md).

## Tool 0.3.8a1 release identity

Tool `0.3.8a1` is an emergency bridge prerelease with an intentionally narrow scope.

```text
Tool:             0.3.8a1
Project Profile:  pp.1.01
Specification:    0.3.7-draft
SPEC_REVISION:    3c47816770d194ae42f98faedc911d980db0e62a
Release scope:    explicit proposed candidate bridge
```

This Tool release does not introduce a new Specification family or Project Profile contract.

It adds support for representing a not-yet-existing component as an explicit proposed candidate and resolving that proposal without silently materializing it as an active component. It does not claim completion of the broader Tool `0.4.0` capability-recovery architecture.

Release scope and verification history are recorded in [`releasenote/tool/0.3.8a1.md`](releasenote/tool/0.3.8a1.md). The release gate is defined by [`planning/0.3.8/0.3.8a1-emergency-release-gate.yaml`](planning/0.3.8/0.3.8a1-emergency-release-gate.yaml).

## License authority

PTSIP licensing authority is contained exclusively under [`License-Authority/`](License-Authority/). The machine-readable entry point is [`License-Authority/license-authority.yaml`](License-Authority/license-authority.yaml), and the controlling legal text is [`License-Authority/LICENSE.md`](License-Authority/LICENSE.md).

The canonical effective time currently declared by the License Authority is `2026-09-15T00:00:00Z` (UTC).

License-related wording elsewhere in this repository is informational or contextual only. It does not become part of the License, modify it, or become incorporated by reference.

Normal Tool releases, Specification validation, Tool version changes, documentation mentions, keyword matches, and AI semantic guesses do not authorize License Authority entry. Entry uses only the triggers declared by `License-Authority/license-authority.yaml`.
## Consumer Repository canonical namespace

Read-only inspection and Pilot operations remain read-only and do not create repository state merely by being invoked. When a Consumer Repository persists repository-local contracts, registries, configuration, task/operation metadata, or execution state whose semantic owner is PTSIP, `.ptsip/` is the canonical ownership boundary.

Repository tooling implementations may physically live under `tools/`, `scripts/`, `src/`, or another project-owned path. Their PTSIP-owned registration, policy bindings, task/operation contracts, indexes, and lifecycle state must not establish an alternative repository-local PTSIP control-plane root.

Canonical machine indexes under `.ptsip/` use JSON. Tool `0.3.8a2` uses `.ptsip/index.json` as the root router and `.ptsip/profiles/index.json` for local Project Profile selection. The Task and runtime namespaces are reserved; runtime persistence details remain future work. A reserved or unavailable Task capability must fail closed for the dependent operation rather than causing an agent to invent a new Task Engine elsewhere in the repository.

## Project status

PTSIP remains experimental. Tool `0.3.8a2` is the current namespace-stabilization prerelease candidate; its publication boundary is tracked in [`releasenote/tool/0.3.8a2.md`](releasenote/tool/0.3.8a2.md). Historical Tool releases, including `0.3.8a1`, and Specification notes are preserved under [`releasenote/`](releasenote/).
