PTSIP Tool 0.3.4

PTSIP Reference Tool 0.3.4 Release Notes

Status: RELEASE PREPARATION; repository identity migration complete; implementation completed; publication pending

Canonical repository: Kinirin/PTSIP

Previous Tool source: 0.3.3 (permanently source-only)
Distributed-authority implementation merge: 555c528593f700a348d8da84545a62ce61291cae
Pre-rebind verification completion: 8cd0ddf16dc9b56f27f694138a37caae1c49bb4f
Active bound Specification: 0.3.4-draft revision b5b17dd16667cc1afaf1d23054b6e5dd773e3f5e

Pre-identity-migration verification: GitHub Actions run 31558658990 — PASS

Final verification merge: PR #27, merge commit b092497c5eaab956ae5108a7ecd701cfa4e40515
Publication: no tool-v0.3.4 tag, GitHub Release, or PyPI publication has been created

Tool 0.3.4 completes GitHub-coordinated repository-global Decision Authority consistency and is now verified against the active 0.3.4-draft Specification binding.

The distributed-authority implementation was originally completed and verified while bound to the predecessor 0.2.0-draft revision. PR #26 activated the coherent normative migration and rebound the same Tool source version to the immutable 0.3.4-draft freeze revision above. PR #27 then aligned stale test fixtures and projection expectations with that active binding without changing runtime or Specification behavior.

The existing spec-v0.3.4-draft tag/GitHub Release remains the earlier public design checkpoint and is not moved. The active normative identity for Tool 0.3.4 is 0.3.4-draft @ b5b17dd16667cc1afaf1d23054b6e5dd773e3f5e.

Historical GitHub references may identify an earlier repository location; the canonical repository path is now Kinirin/PTSIP.

Authority freshness at gate time

For GitHub-coordinated repositories, ptsip gate checks the relevant authority scope even when the selected local Project Profile already contains a complete declaration.

A local declaration therefore cannot cause an early success result without accounting for an existing repository-global authority record for the same normalized component scope.

Authority lookup uses a read-only path. When the authority ref does not exist, absence observation does not create the ref or fabricate decision history merely to prove that no distributed decision exists.

Reconciliation matrix

Tool 0.3.4 distinguishes the important local/remote states explicitly:

• local declaration absent + no authority decision: create/reuse pending state only when the active operation actually requires one;
• local declaration absent + resolved authority winner: validate and safely project the winner into the selected local profile;
• local declaration present + no authority decision: retain the project declaration without fabricating authority history;
• local declaration equivalent + resolved authority winner: return resolved/consistent state without rewriting equivalent profile text;
• local declaration conflicting + resolved authority winner: return AUTHORITY_PROFILE_CONFLICT and do not silently overwrite/reclassify the Project Profile;
• repository/profile changes during reconciliation: refuse stale application rather than writing over changed local state.

Equivalent profile comparison is semantic rather than YAML-format-sensitive.

Global decision state versus local projection

Distributed authority owns global decision state such as PENDING / RESOLVED. Tool 0.3.4 does not use one global application flag to imply every clone has applied the decision.

Clone-local projection/application state is separate. A local receipt cannot change which architecture answer won and cannot claim other clones are synchronized.

Explicit adoption fact preservation

The 0.3.4-draft Project Profile migration closes the representation gap discovered during Tool 0.3.3 adoption work.

Structured adoption/resolution now preserves these supplied facts losslessly in component declarations:

• classification
• purpose
• shipped
• runtime_required
• lifecycle_owner
• executable

Canonical lifecycle owners are:

• PRODUCT
• DEVELOPMENT_TOOLING
• INDEPENDENT

release_owner and compatibility_owner remain separate project metadata. Tool 0.3.4 no longer uses release_owner as a lossy alias for lifecycle_owner, and it no longer drops runtime_required during profile projection.

Boundary-root shorthand remains structurally available, but a structured write-enabled adoption/resolution refuses mutation when the shorthand cannot preserve the complete supplied fact set.

Adoption and resolution

ptsip adopt --apply coordinates new GitHub architecture decisions before local mutation. A different already-resolved winner cannot be overwritten.

If a component is already declared locally and no distributed authority decision exists, adoption does not create remote pending history solely for bookkeeping.

ptsip resolve preserves first-valid-resolution-wins semantics and reconciles the accepted winner into the selected local Project Profile only after validation and freshness checks.

Fail-closed behavior

Selected distributed coordination fails closed when required authority freshness or safe mutation cannot be established and never silently falls back to a separate Local DecisionStore winner.

Machine-readable coordinated failures expose COORDINATION_UNAVAILABLE where required by the Tool authority contract.

Bound Specification migration

The coherent 0.3.4-draft migration adds stable normative rules:

• PTSIP-ADP-001
• PTSIP-AUT-001 through PTSIP-AUT-007

PTSIP-AUT-* rules govern implementations claiming distributed coordination capability. They are not a fourth Consumer Repository architecture plane.

The final immutable Specification freeze activated by PR #26 is:

Specification family: 0.3.4-draft
Specification revision: b5b17dd16667cc1afaf1d23054b6e5dd773e3f5e

Canonical and packaged embedded machine-readable assets are required by release-readiness tests to be byte-identical for:

• Project Profile schema;
• registry;
• artifact-evidence schema;
• agent-classification schema;
• diagnostic schema.

Pre-rebind verification

GitHub Actions run 31471025526 on Python 3.14.6 verified the distributed-authority Tool implementation before the Specification migration:

• complete pytest suite: 134 passed;
• PTSIP Tool 0.3.4 identity: PASS;
• predecessor bound Specification identity: PASS;
• ptsip conform --help: PASS;
• python -m build: PASS;
• wheel/sdist twine check: PASS;
• built-wheel force reinstall: PASS;
• installed-wheel Tool/spec/CLI smoke: PASS.

That run remains pre-rebind implementation evidence only; it does not serve as the final release verification for the active 0.3.4-draft @ afba3531... package binding.

Post-rebind verification

The first post-rebind merged-PR run, 31556564655, correctly detected stale test fixtures and expectations left from the predecessor Specification binding. It failed with 15 failed, 123 passed before package build and smoke stages and is retained as superseded diagnostic evidence.

PR #27 migrated only the stale verification fixtures and projection expectations to the active 0.3.4-draft contract. It introduced no runtime or Specification behavior change.

GitHub Actions run 31558658990 is pre-repository-identity-migration verification evidence for Tool 0.3.4. The run completed successfully and verified:

• complete pytest suite: 138 passed;
• Tool source/package identity remains 0.3.4: PASS;
• ptsip spec reports the active 0.3.4-draft @ b5b17dd16667cc1afaf1d23054b6e5dd773e3f5e binding: PASS;
• canonical/embedded machine-readable contract equality checks: PASS through the complete test suite;
• ptsip conform --help: PASS;
• python -m build: PASS;
• wheel and sdist twine check: PASS;
• built-wheel force reinstall: PASS;
• installed-wheel Tool/spec/CLI smoke: PASS.

Tool 0.3.4 requires fresh repository-identity-migration verification before publication.

Publication boundary

Tool 0.3.3 remains permanently without a tag, GitHub Release, or PyPI publication.

Tool 0.3.4 is verified and ready for the separate publication action, but remains unpublished at this release-note finalization point:

Tool source version: 0.3.4
Distributed implementation: COMPLETED
Specification rebind: ACTIVATED
Repository identity migration: COMPLETE
Implementation: COMPLETED
Publication: PENDING
Pre-identity-migration verification run: 31558658990
Final verification merge: b092497c5eaab956ae5108a7ecd701cfa4e40515
Tag: not created
GitHub Tool Release: not created
PyPI PTSIP==0.3.4: not published

The next publication action is to create/publish tool-v0.3.4 from canonical main. Publishing that GitHub Tool Release triggers the Tool release workflow, which builds the distributions and publishes PTSIP==0.3.4 to PyPI through trusted publishing after the release checks succeed.

PTSIP Specification 0.3.4-draft

PTSIP Specification 0.3.4-draft Release Notes

Status: Proposed experimental Specification family
Design predecessor: 0.3.3-draft
Active normative baseline: 0.2.0-draft revision a877b2f66a7f94c1b844c979e1b08fb08a9a8e45
Implementation evidence: PTSIP Reference Tool 0.3.4
Tool implementation merge: 555c528593f700a348d8da84545a62ce61291cae
Tool verification completion: 8cd0ddf16dc9b56f27f694138a37caae1c49bb4f
Candidate normative snapshot: To be assigned only by a coherent normative migration commit
Identity model: draft family label + immutable Git revision

The 0.3.4-draft label is a proposed PTSIP Specification family that incorporates the Explicit Project Adoption design work recorded in 0.3.3-draft and adds the completed Distributed Authority Consistency contract demonstrated by Reference Tool 0.3.4.

This document is a release-note-level Specification design record. It does not by itself activate 0.3.4-draft, rebind a Tool, publish a Tool release, or make every current Reference Tool implementation detail normative.

Reference Tool 0.3.4 was implemented and verified while still bound to the active immutable Specification baseline:

Specification family: 0.2.0-draft
Specification revision: a877b2f66a7f94c1b844c979e1b08fb08a9a8e45

Therefore the completed Tool behavior is implementation evidence for this draft, not a retroactive Specification binding.

0.3.3-draft is the design predecessor, but it has not become an active normative snapshot. A future coherent 0.3.4-draft migration MAY incorporate the accepted 0.3.3-draft adoption/schema proposals directly from the active 0.2.0-draft baseline. Activating 0.3.3-draft first is not a prerequisite.

1. Compatibility baseline

Unless explicitly changed by the final coherent normative migration, 0.3.4-draft preserves the established 0.2.0-draft architecture and conformance model.

The following invariants remain unchanged:

• PTSIP has exactly three architecture classifications: PRODUCT, TOOLCHAIN, and NEUTRAL_CONTRACT;
• UNKNOWN, CONFLICT, and INCOMPLETE remain decision/evaluation states rather than additional architecture planes;
• a Project Profile is project-owned architecture declaration state and is not itself observed conformance truth;
• declaration and observation remain distinct;
• Product Artifact owner and artifact producer remain distinct concepts;
• project-specific dependency policy may strengthen but may not weaken universal PTSIP rules;
• mandatory-rule violations are not waived by project governance metadata;
• External PTSIP Tooling remains non-intrusive toward Consumer Repository structure;
• a coding agent must not invent missing architecture intent;
• Specification and Reference Tool release identities remain independently versioned;
• immutable Git revision remains the exact identity of a normative draft snapshot.

This family does not create a fourth plane and does not redefine evidence, artifact, dependency, conformance, or diagnostic semantics merely because distributed decision coordination is added.

2. Design lineage from 0.3.3-draft

0.3.3-draft narrowed its scope to Explicit Project Adoption and durable architecture declaration semantics after the early GitHub authority implementation was correctly recognized as incomplete.

That design record established or proposed the following concepts that 0.3.4-draft carries forward unless a later normative migration explicitly changes them:

• discovered repository scope is not architecture authority;
• project-owner architectural intent must be explicit;
• adoption must validate before mutation;
• stale or conflicting Project Profile mutation must be refused;
• Project Profile identity/path must remain consistent across one workflow;
• local Tool-owned operational state must not replace durable project architecture declaration;
• runtime_required requires a durable, lossless representation if it remains a required classification fact;
• lifecycle ownership used by decision validation requires a durable, lossless Project Profile representation;
• Tool implementation behavior does not become normative solely because it exists in source.

The principal addition in 0.3.4-draft is that distributed coordination is now sufficiently complete to define a backend-neutral consistency contract.

3. Why Distributed Authority Consistency belongs in the Specification

A Consumer Repository may be acted on concurrently by:

• local IDE agents;
• local command-line agents;
• cloud coding agents;
• CI agents;
• multiple clones or worktrees;
• hosted decision-control services.

Separate local operational databases cannot establish one shared answer for the same unresolved architecture scope across those environments.

Git propagation of ptsip.yaml is also insufficient as the only coordination mechanism because a valid architecture decision may be accepted before the resulting Project Profile change is committed, pushed, fetched, merged, or observed by another environment.

PTSIP therefore distinguishes:

PTSIP Specification
    -> normative architecture and conformance contract

Consumer Repository Project Profile
    -> project-owned, revision-bound architecture declaration

Decision Authority
    -> coordination state for unresolved/resolved architecture decisions

The roles MUST remain distinct.

Distributed Authority Consistency means that participating environments within one coordination domain observe one authoritative decision winner at architecture-sensitive operation boundaries without requiring immediate Project Profile propagation between clones.

4. Decision Authority

A Decision Authority is the authority used to coordinate unresolved and resolved architecture decisions for a defined coordination domain.

A Decision Authority does not replace the Project Profile.

Decision Authority
    -> which explicit architecture answer won for a coordinated decision

Project Profile
    -> which architecture declaration is represented by a repository revision/worktree

An implementation MAY provide local, repository-distributed, or hosted authority backends.

A backend claiming distributed coordination MUST satisfy the consistency requirements in this draft regardless of its storage technology.

Local SQLite, a Git ref, a transactional service, or another persistence mechanism is an implementation choice unless separately standardized by an interoperability schema.

5. Coordination domain

A coordination domain is the scope within which one architecture decision identity has one authoritative winner.

A conforming distributed implementation MUST identify its coordination domain unambiguously for an architecture-decision operation.

For repository-scoped coordination, repository identity is normally part of the domain identity.

An implementation MUST NOT silently switch from a selected distributed coordination domain to an isolated local domain when the distributed backend becomes unavailable.

Such a switch could create two independently valid winners for what participants believe is the same architecture decision.

6. Stable distributed decision identity

The same architectural component scope MUST map to the same distributed decision identity across participating clones and environments.

Distributed decision identity MUST NOT depend solely on clone-local or temporary values such as:

• local clarification IDs;
• branch-local missing-field lists;
• temporary local Project Profile completeness;
• Local DecisionStore record IDs;
• one process's operation identifier;
• incidental candidate display names when the normalized architecture scope is otherwise the same.

The identity MUST be derived from stable coordination-domain identity plus a deterministic normalized architecture/component scope.

The exact hash or string encoding is an interoperability concern rather than universal architecture semantics unless separately standardized.

7. Authority revision and ordered state

A distributed Decision Authority MUST expose state strongly enough for participants to distinguish the authority state they read from a later authority state.

The implementation MAY represent this as:

• an immutable Git commit/ref revision;
• a database transaction/version;
• an ETag or generation number;
• a consensus log index;
• another ordered conditional-write token.

Wall-clock time alone SHOULD NOT determine the winning decision when a stronger ordered authority revision is available.

The purpose of the authority revision is to prevent a stale participant from replacing a newer accepted decision merely because it completed later.

8. First-valid-resolution-wins

For one distributed decision identity, the first valid accepted resolution wins.

A later contradictory resolution MUST NOT silently replace an already accepted authoritative winner.

A distributed authority mutation MUST use atomic conditional-write, compare-and-swap, transaction, consensus, or equivalent semantics that prevent a stale writer from overwriting a newer state.

Conceptually:

read authority revision A
        |
        v
prepare valid mutation based on A
        |
        v
conditionally publish A -> B

if authority no longer equals A
        |
        v
reject stale write
        |
        v
reread current authority
        |
        +-- same-scope winner already resolved
        |       -> accept winner; do not retry contradictory answer
        |
        +-- unrelated authority mutation only
                -> retry/rebase only when safe

Concurrent independent decisions for different component scopes MAY both eventually succeed after safe retry against the latest autho...

PTSIP Tool 0.3.2

What's Changed

• tooling: add Tool 0.3.2 topology migration by @kwaksinwoo01 in #20

Full Changelog: tool-v0.3.1...tool-v0.3.2

PTSIP Tool 0.3.1

What's Changed

• Tool 0.3.1: add on-demand coding-agent decision gate by @kwaksinwoo01 in #19

Full Changelog: tool-v0.3.0...tool-v0.3.1

PTSIP Tool 0.3.0

What's Changed

• docs: simplify README and automate Korean localization by @kwaksinwoo01 in #8
• chore: move README translation helper under .github by @kwaksinwoo01 in #9
• docs: sync Korean README script path by @kwaksinwoo01 in #10
• docs: plan next pilot-driven PTSIP normative snapshot by @kwaksinwoo01 in #11
• spec: forward-port pilot-driven normative snapshot onto Tool 0.2.2 main by @kwaksinwoo01 in #13
• tooling: migrate Tool 0.2.3 evidence correctness by @kwaksinwoo01 in #14
• docs: finalize Tool 0.2.3 main status by @kwaksinwoo01 in #15
• docs: mark Tool 0.2.3 as source-only migration by @kwaksinwoo01 in #16
• spec: remove stale waiver inputs from conformance by @kwaksinwoo01 in #18
• tooling: implement Tool 0.3.0 conformance engine by @kwaksinwoo01 in #17

Full Changelog: tool-v0.2.0...tool-v0.3.0

PTSIP Tool 0.2.0

PTSIP Tool 0.2.0 evidence-v2 release.

PTSIP Tool 0.1.0a1

Initial alpha release of the PTSIP Reference Tool.