PTSIP 0.3.2__tar.gz → 0.3.5__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (96) hide show
  1. ptsip-0.3.5/PKG-INFO +336 -0
  2. ptsip-0.3.5/README.md +303 -0
  3. {ptsip-0.3.2 → ptsip-0.3.5}/pyproject.toml +10 -5
  4. ptsip-0.3.5/src/PTSIP.egg-info/PKG-INFO +336 -0
  5. {ptsip-0.3.2 → ptsip-0.3.5}/src/PTSIP.egg-info/SOURCES.txt +16 -1
  6. {ptsip-0.3.2 → ptsip-0.3.5}/src/PTSIP.egg-info/requires.txt +1 -0
  7. {ptsip-0.3.2 → ptsip-0.3.5}/src/PTSIP.egg-info/top_level.txt +1 -0
  8. ptsip-0.3.5/src/ptsip/__init__.py +5 -0
  9. ptsip-0.3.5/src/ptsip/adoption.py +225 -0
  10. {ptsip-0.3.2 → ptsip-0.3.5}/src/ptsip/app/client.py +3 -3
  11. ptsip-0.3.5/src/ptsip/app/github_authority.py +629 -0
  12. ptsip-0.3.5/src/ptsip/app/github_reconciliation.py +328 -0
  13. ptsip-0.3.5/src/ptsip/app/local_client.py +111 -0
  14. {ptsip-0.3.2 → ptsip-0.3.5}/src/ptsip/clarification/generator.py +10 -5
  15. {ptsip-0.3.2 → ptsip-0.3.5}/src/ptsip/clarification/generator_core.py +2 -2
  16. {ptsip-0.3.2 → ptsip-0.3.5}/src/ptsip/clarification/resolution/profile_projection.py +12 -33
  17. ptsip-0.3.5/src/ptsip/cli.py +754 -0
  18. ptsip-0.3.5/src/ptsip/constants.py +9 -0
  19. {ptsip-0.3.2 → ptsip-0.3.5}/src/ptsip/specdata/ptsip-agent-classification.schema.json +28 -6
  20. {ptsip-0.3.2 → ptsip-0.3.5}/src/ptsip/specdata/ptsip-artifact-evidence.schema.json +1 -1
  21. ptsip-0.3.5/src/ptsip/specdata/ptsip-diagnostic.schema.json +58 -0
  22. ptsip-0.3.5/src/ptsip/specdata/ptsip-profile.schema.json +188 -0
  23. {ptsip-0.3.2 → ptsip-0.3.5}/src/ptsip/specdata/ptsip-registry.yaml +103 -3
  24. {ptsip-0.3.2 → ptsip-0.3.5}/src/ptsip/storage/local_state.py +8 -0
  25. ptsip-0.3.5/src/vpms/__init__.py +64 -0
  26. ptsip-0.3.5/src/vpms/domain/__init__.py +1 -0
  27. ptsip-0.3.5/src/vpms/domain/model.py +88 -0
  28. ptsip-0.3.5/src/vpms/domain/registry.py +350 -0
  29. ptsip-0.3.5/src/vpms/domain/selector.py +41 -0
  30. ptsip-0.3.5/src/vpms/execution/__init__.py +1 -0
  31. ptsip-0.3.5/src/vpms/execution/adapters/__init__.py +1 -0
  32. ptsip-0.3.5/src/vpms/execution/adapters/command.py +67 -0
  33. ptsip-0.3.5/src/vpms/execution/runner.py +102 -0
  34. ptsip-0.3.5/src/vpms/integration/__init__.py +1 -0
  35. ptsip-0.3.5/src/vpms/integration/ptsip_bridge.py +102 -0
  36. ptsip-0.3.2/PKG-INFO +0 -338
  37. ptsip-0.3.2/README.md +0 -307
  38. ptsip-0.3.2/src/PTSIP.egg-info/PKG-INFO +0 -338
  39. ptsip-0.3.2/src/ptsip/__init__.py +0 -3
  40. ptsip-0.3.2/src/ptsip/cli.py +0 -434
  41. ptsip-0.3.2/src/ptsip/constants.py +0 -9
  42. ptsip-0.3.2/src/ptsip/specdata/ptsip-diagnostic.schema.json +0 -29
  43. ptsip-0.3.2/src/ptsip/specdata/ptsip-profile.schema.json +0 -310
  44. {ptsip-0.3.2 → ptsip-0.3.5}/LICENSE +0 -0
  45. {ptsip-0.3.2 → ptsip-0.3.5}/MANIFEST.in +0 -0
  46. {ptsip-0.3.2 → ptsip-0.3.5}/setup.cfg +0 -0
  47. {ptsip-0.3.2 → ptsip-0.3.5}/src/PTSIP.egg-info/dependency_links.txt +0 -0
  48. {ptsip-0.3.2 → ptsip-0.3.5}/src/PTSIP.egg-info/entry_points.txt +0 -0
  49. {ptsip-0.3.2 → ptsip-0.3.5}/src/ptsip/__main__.py +0 -0
  50. {ptsip-0.3.2 → ptsip-0.3.5}/src/ptsip/app/__init__.py +0 -0
  51. {ptsip-0.3.2 → ptsip-0.3.5}/src/ptsip/app/github_client.py +0 -0
  52. {ptsip-0.3.2 → ptsip-0.3.5}/src/ptsip/app/server.py +0 -0
  53. {ptsip-0.3.2 → ptsip-0.3.5}/src/ptsip/app/service.py +0 -0
  54. {ptsip-0.3.2 → ptsip-0.3.5}/src/ptsip/app/store.py +0 -0
  55. {ptsip-0.3.2 → ptsip-0.3.5}/src/ptsip/artifact_evidence.py +0 -0
  56. {ptsip-0.3.2 → ptsip-0.3.5}/src/ptsip/build_resolution.py +0 -0
  57. {ptsip-0.3.2 → ptsip-0.3.5}/src/ptsip/clarification/__init__.py +0 -0
  58. {ptsip-0.3.2 → ptsip-0.3.5}/src/ptsip/clarification/i18n.py +0 -0
  59. {ptsip-0.3.2 → ptsip-0.3.5}/src/ptsip/clarification/model.py +0 -0
  60. {ptsip-0.3.2 → ptsip-0.3.5}/src/ptsip/clarification/render.py +0 -0
  61. {ptsip-0.3.2 → ptsip-0.3.5}/src/ptsip/clarification/resolution/__init__.py +0 -0
  62. {ptsip-0.3.2 → ptsip-0.3.5}/src/ptsip/clarification/resolution/model.py +0 -0
  63. {ptsip-0.3.2 → ptsip-0.3.5}/src/ptsip/clarification/resolution/parser.py +0 -0
  64. {ptsip-0.3.2 → ptsip-0.3.5}/src/ptsip/clarification/resolution/resolver.py +0 -0
  65. {ptsip-0.3.2 → ptsip-0.3.5}/src/ptsip/clarification/transports/__init__.py +0 -0
  66. {ptsip-0.3.2 → ptsip-0.3.5}/src/ptsip/clarification/transports/github_issue.py +0 -0
  67. {ptsip-0.3.2 → ptsip-0.3.5}/src/ptsip/conformance.py +0 -0
  68. {ptsip-0.3.2 → ptsip-0.3.5}/src/ptsip/conformance_audit.py +0 -0
  69. {ptsip-0.3.2 → ptsip-0.3.5}/src/ptsip/conformance_engine.py +0 -0
  70. {ptsip-0.3.2 → ptsip-0.3.5}/src/ptsip/doctor.py +0 -0
  71. {ptsip-0.3.2 → ptsip-0.3.5}/src/ptsip/inspection/__init__.py +0 -0
  72. {ptsip-0.3.2 → ptsip-0.3.5}/src/ptsip/inspection/components.py +0 -0
  73. {ptsip-0.3.2 → ptsip-0.3.5}/src/ptsip/inspection/dependencies.py +0 -0
  74. {ptsip-0.3.2 → ptsip-0.3.5}/src/ptsip/inspection/dependencies_030.py +0 -0
  75. {ptsip-0.3.2 → ptsip-0.3.5}/src/ptsip/inspection/dotnet.py +0 -0
  76. {ptsip-0.3.2 → ptsip-0.3.5}/src/ptsip/inspection/go.py +0 -0
  77. {ptsip-0.3.2 → ptsip-0.3.5}/src/ptsip/inspection/inventory.py +0 -0
  78. {ptsip-0.3.2 → ptsip-0.3.5}/src/ptsip/inspection/javascript.py +0 -0
  79. {ptsip-0.3.2 → ptsip-0.3.5}/src/ptsip/inspection/lexing.py +0 -0
  80. {ptsip-0.3.2 → ptsip-0.3.5}/src/ptsip/inspection/source_adapters.py +0 -0
  81. {ptsip-0.3.2 → ptsip-0.3.5}/src/ptsip/lifecycle_evidence.py +0 -0
  82. {ptsip-0.3.2 → ptsip-0.3.5}/src/ptsip/model.py +0 -0
  83. {ptsip-0.3.2 → ptsip-0.3.5}/src/ptsip/pilot/__init__.py +0 -0
  84. {ptsip-0.3.2 → ptsip-0.3.5}/src/ptsip/pilot/runner.py +0 -0
  85. {ptsip-0.3.2 → ptsip-0.3.5}/src/ptsip/repository/__init__.py +0 -0
  86. {ptsip-0.3.2 → ptsip-0.3.5}/src/ptsip/repository/discover.py +0 -0
  87. {ptsip-0.3.2 → ptsip-0.3.5}/src/ptsip/repository/remote.py +0 -0
  88. {ptsip-0.3.2 → ptsip-0.3.5}/src/ptsip/repository/snapshot.py +0 -0
  89. {ptsip-0.3.2 → ptsip-0.3.5}/src/ptsip/review_evidence.py +0 -0
  90. {ptsip-0.3.2 → ptsip-0.3.5}/src/ptsip/spec_identity.py +0 -0
  91. {ptsip-0.3.2 → ptsip-0.3.5}/src/ptsip/storage/__init__.py +0 -0
  92. {ptsip-0.3.2 → ptsip-0.3.5}/src/ptsip/topology.py +0 -0
  93. {ptsip-0.3.2 → ptsip-0.3.5}/src/ptsip/validation/__init__.py +0 -0
  94. {ptsip-0.3.2 → ptsip-0.3.5}/src/ptsip/validation/components.py +0 -0
  95. {ptsip-0.3.2 → ptsip-0.3.5}/src/ptsip/validation/profile.py +0 -0
  96. {ptsip-0.3.2 → ptsip-0.3.5}/src/ptsip/validation/rules.py +0 -0
ptsip-0.3.5/PKG-INFO ADDED
@@ -0,0 +1,336 @@
1
+ Metadata-Version: 2.4
2
+ Name: PTSIP
3
+ Version: 0.3.5
4
+ Summary: Reference development tooling for the Product-Toolchain SDK Isolation Policy
5
+ Author: Kinirin
6
+ Maintainer: Kinirin
7
+ License-Expression: Apache-2.0
8
+ Project-URL: Homepage, https://github.com/Kinirin/PTSIP
9
+ Project-URL: Specification, https://github.com/Kinirin/PTSIP
10
+ Project-URL: Issues, https://github.com/Kinirin/PTSIP/issues
11
+ Keywords: architecture,sdk,toolchain,governance,validation,ptsip
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Environment :: Console
14
+ Classifier: Operating System :: OS Independent
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.11
17
+ Classifier: Programming Language :: Python :: 3.12
18
+ Classifier: Programming Language :: Python :: 3.13
19
+ Classifier: Programming Language :: Python :: 3.14
20
+ Classifier: Topic :: Software Development :: Quality Assurance
21
+ Requires-Python: >=3.11
22
+ Description-Content-Type: text/markdown
23
+ License-File: LICENSE
24
+ Requires-Dist: PyYAML<7,>=6.0
25
+ Requires-Dist: jsonschema<5,>=4.23
26
+ Provides-Extra: github-app
27
+ Requires-Dist: PyJWT[crypto]<3,>=2.10; extra == "github-app"
28
+ Provides-Extra: dev
29
+ Requires-Dist: build<2,>=1.2; extra == "dev"
30
+ Requires-Dist: pytest<9,>=8; extra == "dev"
31
+ Requires-Dist: setuptools>=77; extra == "dev"
32
+ Dynamic: license-file
33
+
34
+ <p align="right">
35
+ English | <a href="README.ko.md">한국어</a>
36
+ </p>
37
+
38
+ # PTSIP — Product–Toolchain SDK Isolation Policy
39
+
40
+ **Status:** Draft project-defined specification
41
+ **Specification family:** `0.3.4-draft`
42
+ **Active normative snapshot:** `b5b17dd16667cc1afaf1d23054b6e5dd773e3f5e`<br>
43
+ **License:** Apache License 2.0
44
+
45
+ PTSIP is an architecture policy for keeping Product SDK responsibility separate from development Toolchain SDK responsibility while preserving explicit contracts, reproducible conformance, and multi-environment architecture-decision consistency.
46
+
47
+ > **Purpose precedes reuse.** Classify a component by why it exists and which lifecycle owns it before considering code sharing.
48
+
49
+ ## Architecture model
50
+
51
+ PTSIP has exactly three architectural classifications:
52
+
53
+ | Classification | Meaning |
54
+ | --- | --- |
55
+ | `PRODUCT` | Product-owned runtime/library/SDK/component responsibility. |
56
+ | `TOOLCHAIN` | Development-tooling-owned SDK/component responsibility. |
57
+ | `NEUTRAL_CONTRACT` | Deliberately non-executable, independently governed contract responsibility. |
58
+
59
+ `UNKNOWN`, `CONFLICT`, `INCOMPLETE`, `PENDING`, and similar states are workflow/evaluation states, not additional architecture planes.
60
+
61
+ The core boundary is:
62
+
63
+ ```text
64
+ Toolchain SDK ---> Product source / artifacts
65
+ inspect / validate / generate / migrate / package
66
+
67
+ Product SDK -X-> Toolchain implementation
68
+ runtime / shipped dependency prohibited
69
+ ```
70
+
71
+ Shared semantics should prefer a Neutral Contract over one project-local executable package owned by both planes.
72
+
73
+ ## Install and use
74
+
75
+ PTSIP requires Python 3.11 or newer.
76
+
77
+ For a new installation:
78
+
79
+ ```powershell
80
+ python -m pip install PTSIP
81
+ ```
82
+
83
+ To upgrade an existing installation to the latest available release:
84
+
85
+ ```powershell
86
+ python -m pip install --upgrade PTSIP
87
+ ```
88
+
89
+ Common commands:
90
+
91
+ ```powershell
92
+ ptsip --version
93
+ ptsip spec
94
+ ptsip doctor .
95
+ ptsip inspect .
96
+ ptsip pilot .
97
+ ptsip adopt --help
98
+ ptsip validate .
99
+ ptsip clarify .
100
+ ptsip gate .
101
+ ptsip resolve --help
102
+ ptsip conform .
103
+ ```
104
+
105
+ For source development:
106
+
107
+ ```powershell
108
+ pip install -e ".[dev]"
109
+ ```
110
+
111
+ ## Specification and Tool lifecycle
112
+
113
+ The **PTSIP Specification** and **PTSIP Reference Tool** are independently versioned.
114
+
115
+ - `pyproject.toml` owns Tool/package source version;
116
+ - `ptsip --version` reports installed Tool version;
117
+ - `ptsip spec` reports the exact Specification family + immutable revision bound to that Tool;
118
+ - `spec/`, `schemas/`, and `registry/` contain canonical Specification assets;
119
+ - `src/ptsip/specdata/` contains matching embedded resources used by the Tool;
120
+ - GitHub Releases publish Tool and Specification release/design records.
121
+
122
+ The existing `spec-v0.3.4-draft` GitHub Release records the earlier design proposal. It remains an immutable historical checkpoint and is not moved. The active repository-identity-migration snapshot is `0.3.4-draft @ b5b17dd16667cc1afaf1d23054b6e5dd773e3f5e`.
123
+
124
+ A Tool version number matching a Specification family number does not imply identity by itself.
125
+
126
+ ## Consumer Repository non-intrusion
127
+
128
+ PTSIP does not require adopting repositories to create PTSIP-specific `docs/`, `tools/`, `.ptsip/`, cache, report, or hidden directories.
129
+
130
+ External inspection/Pilot tooling is read-only by default. Tool-owned operational state belongs outside the Consumer Repository unless the user explicitly chooses a repository path.
131
+
132
+ The default project-owned architecture declaration is repository-root `ptsip.yaml`; projects may consistently select another path with `--profile`.
133
+
134
+ Local state such as `control-plane.sqlite3` is not portable architecture authority and must not be Git-shared as repository-global coordination state.
135
+
136
+ ## Explicit project adoption
137
+
138
+ Candidate discovery is evidence, not architecture authority. The project owner supplies architecture intent.
139
+
140
+ `0.3.4-draft` defines this structured adoption fact set:
141
+
142
+ ```text
143
+ classification
144
+ purpose
145
+ shipped
146
+ runtime_required
147
+ lifecycle_owner
148
+ executable
149
+ ```
150
+
151
+ Canonical lifecycle owners are:
152
+
153
+ ```text
154
+ PRODUCT
155
+ DEVELOPMENT_TOOLING
156
+ INDEPENDENT
157
+ ```
158
+
159
+ Example dry-run:
160
+
161
+ ```powershell
162
+ ptsip adopt . `
163
+ --component tools `
164
+ --classification TOOLCHAIN `
165
+ --purpose "Repository-local generation tooling" `
166
+ --shipped no `
167
+ --runtime-required no `
168
+ --lifecycle-owner DEVELOPMENT_TOOLING `
169
+ --executable yes `
170
+ --json
171
+ ```
172
+
173
+ Apply only after reviewing the plan:
174
+
175
+ ```powershell
176
+ ptsip adopt . `
177
+ --component tools `
178
+ --classification TOOLCHAIN `
179
+ --purpose "Repository-local generation tooling" `
180
+ --shipped no `
181
+ --runtime-required no `
182
+ --lifecycle-owner DEVELOPMENT_TOOLING `
183
+ --executable yes `
184
+ --apply `
185
+ --json
186
+ ```
187
+
188
+ Structured adoption preserves those facts losslessly in component declarations. `runtime_required` is not discarded, and canonical `lifecycle_owner` is not aliased to `release_owner`.
189
+
190
+ Boundary-root shorthand remains available for simple declarations, but a write-enabled structured adoption/resolution must refuse mutation when shorthand cannot preserve the full fact set.
191
+
192
+ ## Decision Authority
193
+
194
+ PTSIP distinguishes:
195
+
196
+ ```text
197
+ Specification
198
+ -> normative architecture / conformance / coordination rules
199
+
200
+ Decision Authority
201
+ -> which explicit architecture answer won
202
+
203
+ Project Profile
204
+ -> durable project-owned architecture declaration
205
+
206
+ Observed evidence
207
+ -> what repository/artifacts actually do
208
+ ```
209
+
210
+ A Decision Authority is not a conformance oracle and does not replace `ptsip.yaml`.
211
+
212
+ ## GitHub-coordinated Reference Tool profile
213
+
214
+ Reference Tool `0.3.4` demonstrates distributed coordination through a dedicated Git ref:
215
+
216
+ ```text
217
+ refs/heads/ptsip-policy
218
+ ```
219
+
220
+ GitHub storage details are implementation-specific. The Specification requires the semantics, not GitHub itself:
221
+
222
+ - stable coordination-domain + component-scope decision identity;
223
+ - first-valid-resolution-wins;
224
+ - ordered conditional mutation / stale-writer protection;
225
+ - authority freshness at architecture-sensitive boundaries;
226
+ - non-mutating absence lookup;
227
+ - deterministic reconciliation;
228
+ - fail-closed distributed behavior; and
229
+ - separation of global decision state from clone-local application state.
230
+
231
+ ## Coding-agent decision gate
232
+
233
+ ```powershell
234
+ ptsip gate . --component tools --json
235
+ ```
236
+
237
+ In distributed mode, a complete local profile does **not** automatically bypass the authority check. The relevant local declaration is compared with current authority state.
238
+
239
+ | Local Project Profile | Distributed Authority | Required result |
240
+ | --- | --- | --- |
241
+ | declaration absent | no decision | pending only when the active operation actually needs a decision |
242
+ | declaration absent | resolved winner | validate and safely project winner locally |
243
+ | declaration present | no authority decision | use project declaration; do not fabricate authority history |
244
+ | declaration present + equivalent | resolved equivalent winner | resolved/consistent; no formatting rewrite required |
245
+ | declaration present + conflicting | resolved different winner | explicit authority/profile conflict; no silent overwrite |
246
+ | repository/profile changed during reconciliation | any authority state | stale; refuse application and re-analyze |
247
+
248
+ Semantic equivalence means architecture meaning, not YAML key order or whitespace.
249
+
250
+ If distributed coordination is selected but required freshness/safe mutation cannot be established, PTSIP fails the affected operation instead of silently creating a separate Local winner.
251
+
252
+ ## Global decision state versus local projection
253
+
254
+ ```text
255
+ GLOBAL
256
+ PENDING / RESOLVED
257
+
258
+ LOCAL CLONE / WORKTREE
259
+ missing / consistent / locally applied / stale / failed
260
+ ```
261
+
262
+ A global winner does not mean every clone is already synchronized. A clone-local application receipt cannot change the winner.
263
+
264
+ PTSIP uses **action-time synchronization** rather than continuous polling.
265
+
266
+ ## Enforced conformance
267
+
268
+ `ptsip conform` evaluates declaration + observed evidence + Product Artifact/build/lifecycle evidence + snapshot/coverage against Consumer Repository PTSIP rules.
269
+
270
+ Completed outcomes are only:
271
+
272
+ | Exit code | Outcome |
273
+ | --- | --- |
274
+ | `0` | `CONFORMANT` |
275
+ | `5` | `NON_CONFORMANT` |
276
+ | `6` | `INCOMPLETE` |
277
+
278
+ A valid Project Profile does not prove conformance. A resolved Decision Authority winner does not prove conformance. A zero-finding scan does not prove conformance when blocking evidence gaps remain.
279
+
280
+ For Enforced Conformance against a mutable draft, bind the exact immutable Specification revision.
281
+
282
+ ## Reference Tool focus
283
+
284
+ The Reference Tool provides:
285
+
286
+ - read-only repository inspection and Pilot evidence;
287
+ - multi-language dependency/artifact evidence;
288
+ - deterministic clarification for missing intent;
289
+ - explicit project-owner adoption;
290
+ - on-demand decision gating and explicit resolution;
291
+ - GitHub-coordinated first-winner authority for multi-environment agents;
292
+ - gate-time authority freshness and reconciliation;
293
+ - fail-closed distributed coordination;
294
+ - local-only DecisionStore mode when intentionally selected;
295
+ - project-profile validation;
296
+ - Product Artifact evidence ingestion;
297
+ - evidence-relative Enforced Conformance and stable diagnostics.
298
+
299
+ ## Repository map
300
+
301
+ | Area | Location | Purpose |
302
+ | --- | --- | --- |
303
+ | Normative Specification | [`spec/`](spec/) | Architecture, terminology, and conformance rules. |
304
+ | Machine-readable registry | [`registry/`](registry/) | Canonical terms/rule IDs/metadata. |
305
+ | Schemas | [`schemas/`](schemas/) | Project Profile and interoperability schemas. |
306
+ | Agent contract | [`agents/AGENT-CONTRACT.md`](agents/AGENT-CONTRACT.md) | Coding-agent operational contract. |
307
+ | Adoption guide | [`adoption/ADOPTION-GUIDE.md`](adoption/ADOPTION-GUIDE.md) | Controlled adoption sequence. |
308
+ | Reference architecture | [`reference/REFERENCE-ARCHITECTURE.md`](reference/REFERENCE-ARCHITECTURE.md) | Informative architecture guidance. |
309
+ | ADRs | [`decisions/`](decisions/) | Normative architecture decisions. |
310
+ | Embedded spec data | [`src/ptsip/specdata/`](src/ptsip/specdata/) | Tool-packaged schema/registry copies. |
311
+ | Reference Tool | [`src/ptsip/`](src/ptsip/) | Installable Python implementation. |
312
+ | Tests | [`tests/`](tests/) | Tool and contract verification. |
313
+ | Release notes | [`releasenote/`](releasenote/) | Tool/Specification release history. |
314
+
315
+ ## Key Specification documents
316
+
317
+ - [`spec/PTSIP-SPEC.md`](spec/PTSIP-SPEC.md)
318
+ - [`spec/PTSIP-CONFORMANCE.md`](spec/PTSIP-CONFORMANCE.md)
319
+ - [`spec/PTSIP-TERMINOLOGY.md`](spec/PTSIP-TERMINOLOGY.md)
320
+ - [`schemas/ptsip-profile.schema.json`](schemas/ptsip-profile.schema.json)
321
+ - [`registry/ptsip-registry.yaml`](registry/ptsip-registry.yaml)
322
+ - [`decisions/ADR-0005-activate-spec-0.3.4-draft.md`](decisions/ADR-0005-activate-spec-0.3.4-draft.md)
323
+
324
+ ## Release namespaces
325
+
326
+ Tool releases use `tool-v*` tags. Specification releases/design records use the separate `spec-v*` namespace.
327
+
328
+ The exact normative identity of a mutable draft remains the immutable revision, not the tag string alone.
329
+
330
+ ## Maturity
331
+
332
+ PTSIP is a draft project-defined specification, not an ISO, IEEE, IETF, CNCF, or other external industry standard.
333
+
334
+ ## License
335
+
336
+ 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).
ptsip-0.3.5/README.md ADDED
@@ -0,0 +1,303 @@
1
+ <p align="right">
2
+ English | <a href="README.ko.md">한국어</a>
3
+ </p>
4
+
5
+ # PTSIP — Product–Toolchain SDK Isolation Policy
6
+
7
+ **Status:** Draft project-defined specification
8
+ **Specification family:** `0.3.4-draft`
9
+ **Active normative snapshot:** `b5b17dd16667cc1afaf1d23054b6e5dd773e3f5e`<br>
10
+ **License:** Apache License 2.0
11
+
12
+ PTSIP is an architecture policy for keeping Product SDK responsibility separate from development Toolchain SDK responsibility while preserving explicit contracts, reproducible conformance, and multi-environment architecture-decision consistency.
13
+
14
+ > **Purpose precedes reuse.** Classify a component by why it exists and which lifecycle owns it before considering code sharing.
15
+
16
+ ## Architecture model
17
+
18
+ PTSIP has exactly three architectural classifications:
19
+
20
+ | Classification | Meaning |
21
+ | --- | --- |
22
+ | `PRODUCT` | Product-owned runtime/library/SDK/component responsibility. |
23
+ | `TOOLCHAIN` | Development-tooling-owned SDK/component responsibility. |
24
+ | `NEUTRAL_CONTRACT` | Deliberately non-executable, independently governed contract responsibility. |
25
+
26
+ `UNKNOWN`, `CONFLICT`, `INCOMPLETE`, `PENDING`, and similar states are workflow/evaluation states, not additional architecture planes.
27
+
28
+ The core boundary is:
29
+
30
+ ```text
31
+ Toolchain SDK ---> Product source / artifacts
32
+ inspect / validate / generate / migrate / package
33
+
34
+ Product SDK -X-> Toolchain implementation
35
+ runtime / shipped dependency prohibited
36
+ ```
37
+
38
+ Shared semantics should prefer a Neutral Contract over one project-local executable package owned by both planes.
39
+
40
+ ## Install and use
41
+
42
+ PTSIP requires Python 3.11 or newer.
43
+
44
+ For a new installation:
45
+
46
+ ```powershell
47
+ python -m pip install PTSIP
48
+ ```
49
+
50
+ To upgrade an existing installation to the latest available release:
51
+
52
+ ```powershell
53
+ python -m pip install --upgrade PTSIP
54
+ ```
55
+
56
+ Common commands:
57
+
58
+ ```powershell
59
+ ptsip --version
60
+ ptsip spec
61
+ ptsip doctor .
62
+ ptsip inspect .
63
+ ptsip pilot .
64
+ ptsip adopt --help
65
+ ptsip validate .
66
+ ptsip clarify .
67
+ ptsip gate .
68
+ ptsip resolve --help
69
+ ptsip conform .
70
+ ```
71
+
72
+ For source development:
73
+
74
+ ```powershell
75
+ pip install -e ".[dev]"
76
+ ```
77
+
78
+ ## Specification and Tool lifecycle
79
+
80
+ The **PTSIP Specification** and **PTSIP Reference Tool** are independently versioned.
81
+
82
+ - `pyproject.toml` owns Tool/package source version;
83
+ - `ptsip --version` reports installed Tool version;
84
+ - `ptsip spec` reports the exact Specification family + immutable revision bound to that Tool;
85
+ - `spec/`, `schemas/`, and `registry/` contain canonical Specification assets;
86
+ - `src/ptsip/specdata/` contains matching embedded resources used by the Tool;
87
+ - GitHub Releases publish Tool and Specification release/design records.
88
+
89
+ The existing `spec-v0.3.4-draft` GitHub Release records the earlier design proposal. It remains an immutable historical checkpoint and is not moved. The active repository-identity-migration snapshot is `0.3.4-draft @ b5b17dd16667cc1afaf1d23054b6e5dd773e3f5e`.
90
+
91
+ A Tool version number matching a Specification family number does not imply identity by itself.
92
+
93
+ ## Consumer Repository non-intrusion
94
+
95
+ PTSIP does not require adopting repositories to create PTSIP-specific `docs/`, `tools/`, `.ptsip/`, cache, report, or hidden directories.
96
+
97
+ External inspection/Pilot tooling is read-only by default. Tool-owned operational state belongs outside the Consumer Repository unless the user explicitly chooses a repository path.
98
+
99
+ The default project-owned architecture declaration is repository-root `ptsip.yaml`; projects may consistently select another path with `--profile`.
100
+
101
+ Local state such as `control-plane.sqlite3` is not portable architecture authority and must not be Git-shared as repository-global coordination state.
102
+
103
+ ## Explicit project adoption
104
+
105
+ Candidate discovery is evidence, not architecture authority. The project owner supplies architecture intent.
106
+
107
+ `0.3.4-draft` defines this structured adoption fact set:
108
+
109
+ ```text
110
+ classification
111
+ purpose
112
+ shipped
113
+ runtime_required
114
+ lifecycle_owner
115
+ executable
116
+ ```
117
+
118
+ Canonical lifecycle owners are:
119
+
120
+ ```text
121
+ PRODUCT
122
+ DEVELOPMENT_TOOLING
123
+ INDEPENDENT
124
+ ```
125
+
126
+ Example dry-run:
127
+
128
+ ```powershell
129
+ ptsip adopt . `
130
+ --component tools `
131
+ --classification TOOLCHAIN `
132
+ --purpose "Repository-local generation tooling" `
133
+ --shipped no `
134
+ --runtime-required no `
135
+ --lifecycle-owner DEVELOPMENT_TOOLING `
136
+ --executable yes `
137
+ --json
138
+ ```
139
+
140
+ Apply only after reviewing the plan:
141
+
142
+ ```powershell
143
+ ptsip adopt . `
144
+ --component tools `
145
+ --classification TOOLCHAIN `
146
+ --purpose "Repository-local generation tooling" `
147
+ --shipped no `
148
+ --runtime-required no `
149
+ --lifecycle-owner DEVELOPMENT_TOOLING `
150
+ --executable yes `
151
+ --apply `
152
+ --json
153
+ ```
154
+
155
+ Structured adoption preserves those facts losslessly in component declarations. `runtime_required` is not discarded, and canonical `lifecycle_owner` is not aliased to `release_owner`.
156
+
157
+ Boundary-root shorthand remains available for simple declarations, but a write-enabled structured adoption/resolution must refuse mutation when shorthand cannot preserve the full fact set.
158
+
159
+ ## Decision Authority
160
+
161
+ PTSIP distinguishes:
162
+
163
+ ```text
164
+ Specification
165
+ -> normative architecture / conformance / coordination rules
166
+
167
+ Decision Authority
168
+ -> which explicit architecture answer won
169
+
170
+ Project Profile
171
+ -> durable project-owned architecture declaration
172
+
173
+ Observed evidence
174
+ -> what repository/artifacts actually do
175
+ ```
176
+
177
+ A Decision Authority is not a conformance oracle and does not replace `ptsip.yaml`.
178
+
179
+ ## GitHub-coordinated Reference Tool profile
180
+
181
+ Reference Tool `0.3.4` demonstrates distributed coordination through a dedicated Git ref:
182
+
183
+ ```text
184
+ refs/heads/ptsip-policy
185
+ ```
186
+
187
+ GitHub storage details are implementation-specific. The Specification requires the semantics, not GitHub itself:
188
+
189
+ - stable coordination-domain + component-scope decision identity;
190
+ - first-valid-resolution-wins;
191
+ - ordered conditional mutation / stale-writer protection;
192
+ - authority freshness at architecture-sensitive boundaries;
193
+ - non-mutating absence lookup;
194
+ - deterministic reconciliation;
195
+ - fail-closed distributed behavior; and
196
+ - separation of global decision state from clone-local application state.
197
+
198
+ ## Coding-agent decision gate
199
+
200
+ ```powershell
201
+ ptsip gate . --component tools --json
202
+ ```
203
+
204
+ In distributed mode, a complete local profile does **not** automatically bypass the authority check. The relevant local declaration is compared with current authority state.
205
+
206
+ | Local Project Profile | Distributed Authority | Required result |
207
+ | --- | --- | --- |
208
+ | declaration absent | no decision | pending only when the active operation actually needs a decision |
209
+ | declaration absent | resolved winner | validate and safely project winner locally |
210
+ | declaration present | no authority decision | use project declaration; do not fabricate authority history |
211
+ | declaration present + equivalent | resolved equivalent winner | resolved/consistent; no formatting rewrite required |
212
+ | declaration present + conflicting | resolved different winner | explicit authority/profile conflict; no silent overwrite |
213
+ | repository/profile changed during reconciliation | any authority state | stale; refuse application and re-analyze |
214
+
215
+ Semantic equivalence means architecture meaning, not YAML key order or whitespace.
216
+
217
+ If distributed coordination is selected but required freshness/safe mutation cannot be established, PTSIP fails the affected operation instead of silently creating a separate Local winner.
218
+
219
+ ## Global decision state versus local projection
220
+
221
+ ```text
222
+ GLOBAL
223
+ PENDING / RESOLVED
224
+
225
+ LOCAL CLONE / WORKTREE
226
+ missing / consistent / locally applied / stale / failed
227
+ ```
228
+
229
+ A global winner does not mean every clone is already synchronized. A clone-local application receipt cannot change the winner.
230
+
231
+ PTSIP uses **action-time synchronization** rather than continuous polling.
232
+
233
+ ## Enforced conformance
234
+
235
+ `ptsip conform` evaluates declaration + observed evidence + Product Artifact/build/lifecycle evidence + snapshot/coverage against Consumer Repository PTSIP rules.
236
+
237
+ Completed outcomes are only:
238
+
239
+ | Exit code | Outcome |
240
+ | --- | --- |
241
+ | `0` | `CONFORMANT` |
242
+ | `5` | `NON_CONFORMANT` |
243
+ | `6` | `INCOMPLETE` |
244
+
245
+ A valid Project Profile does not prove conformance. A resolved Decision Authority winner does not prove conformance. A zero-finding scan does not prove conformance when blocking evidence gaps remain.
246
+
247
+ For Enforced Conformance against a mutable draft, bind the exact immutable Specification revision.
248
+
249
+ ## Reference Tool focus
250
+
251
+ The Reference Tool provides:
252
+
253
+ - read-only repository inspection and Pilot evidence;
254
+ - multi-language dependency/artifact evidence;
255
+ - deterministic clarification for missing intent;
256
+ - explicit project-owner adoption;
257
+ - on-demand decision gating and explicit resolution;
258
+ - GitHub-coordinated first-winner authority for multi-environment agents;
259
+ - gate-time authority freshness and reconciliation;
260
+ - fail-closed distributed coordination;
261
+ - local-only DecisionStore mode when intentionally selected;
262
+ - project-profile validation;
263
+ - Product Artifact evidence ingestion;
264
+ - evidence-relative Enforced Conformance and stable diagnostics.
265
+
266
+ ## Repository map
267
+
268
+ | Area | Location | Purpose |
269
+ | --- | --- | --- |
270
+ | Normative Specification | [`spec/`](spec/) | Architecture, terminology, and conformance rules. |
271
+ | Machine-readable registry | [`registry/`](registry/) | Canonical terms/rule IDs/metadata. |
272
+ | Schemas | [`schemas/`](schemas/) | Project Profile and interoperability schemas. |
273
+ | Agent contract | [`agents/AGENT-CONTRACT.md`](agents/AGENT-CONTRACT.md) | Coding-agent operational contract. |
274
+ | Adoption guide | [`adoption/ADOPTION-GUIDE.md`](adoption/ADOPTION-GUIDE.md) | Controlled adoption sequence. |
275
+ | Reference architecture | [`reference/REFERENCE-ARCHITECTURE.md`](reference/REFERENCE-ARCHITECTURE.md) | Informative architecture guidance. |
276
+ | ADRs | [`decisions/`](decisions/) | Normative architecture decisions. |
277
+ | Embedded spec data | [`src/ptsip/specdata/`](src/ptsip/specdata/) | Tool-packaged schema/registry copies. |
278
+ | Reference Tool | [`src/ptsip/`](src/ptsip/) | Installable Python implementation. |
279
+ | Tests | [`tests/`](tests/) | Tool and contract verification. |
280
+ | Release notes | [`releasenote/`](releasenote/) | Tool/Specification release history. |
281
+
282
+ ## Key Specification documents
283
+
284
+ - [`spec/PTSIP-SPEC.md`](spec/PTSIP-SPEC.md)
285
+ - [`spec/PTSIP-CONFORMANCE.md`](spec/PTSIP-CONFORMANCE.md)
286
+ - [`spec/PTSIP-TERMINOLOGY.md`](spec/PTSIP-TERMINOLOGY.md)
287
+ - [`schemas/ptsip-profile.schema.json`](schemas/ptsip-profile.schema.json)
288
+ - [`registry/ptsip-registry.yaml`](registry/ptsip-registry.yaml)
289
+ - [`decisions/ADR-0005-activate-spec-0.3.4-draft.md`](decisions/ADR-0005-activate-spec-0.3.4-draft.md)
290
+
291
+ ## Release namespaces
292
+
293
+ Tool releases use `tool-v*` tags. Specification releases/design records use the separate `spec-v*` namespace.
294
+
295
+ The exact normative identity of a mutable draft remains the immutable revision, not the tag string alone.
296
+
297
+ ## Maturity
298
+
299
+ PTSIP is a draft project-defined specification, not an ISO, IEEE, IETF, CNCF, or other external industry standard.
300
+
301
+ ## License
302
+
303
+ 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).
@@ -4,14 +4,17 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "PTSIP"
7
- version = "0.3.2"
7
+ version = "0.3.5"
8
8
  description = "Reference development tooling for the Product-Toolchain SDK Isolation Policy"
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.11"
11
11
  license = "Apache-2.0"
12
12
  license-files = ["LICENSE"]
13
13
  authors = [
14
- { name = "kwaksinwoo01" }
14
+ { name = "Kinirin" }
15
+ ]
16
+ maintainers = [
17
+ { name = "Kinirin" }
15
18
  ]
16
19
  keywords = ["architecture", "sdk", "toolchain", "governance", "validation", "ptsip"]
17
20
  classifiers = [
@@ -31,9 +34,9 @@ dependencies = [
31
34
  ]
32
35
 
33
36
  [project.urls]
34
- Homepage = "https://github.com/kwaksinwoo01/ptsip"
35
- Specification = "https://github.com/kwaksinwoo01/ptsip"
36
- Issues = "https://github.com/kwaksinwoo01/ptsip/issues"
37
+ Homepage = "https://github.com/Kinirin/PTSIP"
38
+ Specification = "https://github.com/Kinirin/PTSIP"
39
+ Issues = "https://github.com/Kinirin/PTSIP/issues"
37
40
 
38
41
  [project.scripts]
39
42
  ptsip = "ptsip.cli:main"
@@ -41,6 +44,7 @@ ptsip-app = "ptsip.app.server:main"
41
44
 
42
45
  [tool.setuptools.packages.find]
43
46
  where = ["src"]
47
+ include = ["ptsip*", "vpms*"]
44
48
 
45
49
  [tool.setuptools.package-data]
46
50
  ptsip = ["specdata/*.json", "specdata/*.yaml"]
@@ -52,4 +56,5 @@ github-app = [
52
56
  dev = [
53
57
  "build>=1.2,<2",
54
58
  "pytest>=8,<9",
59
+ "setuptools>=77",
55
60
  ]