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