feat(skill): refresh TS companion guidance and bounded metadata compatibility #118

Priority and scope

P2, planning-only TS companion skill/compatibility refresh. Coordinate with session-peer-skill; do not modify/install/release that repository or any skill/runtime as part of this issue registration. Target0.3.3 planning candidate; no0.4.0 feature promotion.

Verified distinction

The companion repository currently has tag v0.3.2 at dc2032c9627ae3e40d567f044095b8bddbe7a991. Its Python session-peer/SKILL.md metadata version is0.3.2, while the separate TypeScript session-peer-ts/SKILL.md metadata version remains0.1.0, with min/full runtime0.1.0 and probe-help policy. The TS file is byte-identical to the existing pinned 081cc3c1d16a394bd92824333f4bc61c36951799 source (SHA256 b0c323a54274be525c9862629b3ed3c4c3c6903821999e1b4b0f23585bc05634).

• Current TS skill
• Current Python skill
• TS doctor exact metadata checks
• Four-language pinned skill guidance

Thus this is not simply a wrong repository-tag pin or proof that current installed TS metadata is rejected. The present TS file passes that exact old metadata contract and can help-probe optional features. But its feature table still treats TS0.2/0.3 published capabilities as development-only, its fixed-source guidance calls merged PR14 a candidate, and inspectSkills hardcodes skill/min/full exactly0.1.0. A future legitimate TS skill metadata update would be rejected irrespective of a separately validated compatibility contract.

Acceptance criteria

• Keep repository tag, Python skill version, TS skill version and runtime minimum/full-feature baselines distinct; do not force all version numbers to match or replace the TS skill with Python guidance.
• Coordinate a reviewed TS-specific content baseline covering published unified/multi-home/inactive queue, readonly doctor/return route, multi-host/Tailscale/SSH, npm manager-owned updates/opt-in notices, optional sp and current safety/JSON limits. Keep0.1.0 history clearly bounded.
• Preserve exact TypeScript implementation/path selection, actual version/help capability probing, queued/posted not ACK, unknown no-resend, no wake/Antigravity/Relay/MCP support import, no Draft0.4 handoff/observer as shipped.
• Define a bounded supported metadata/schema/compatibility policy before relaxing inspectSkills exact equalities; validate implementation, min/full meaning and supported runtime/capabilities. Missing, malformed, conflicting or unsupported metadata remains unknown/incompatible. Inspection stays metadata_only: no network, instructions execution, install/update or send authorization.
• Test the existing0.1.0 contract, a separately reviewed compatible successor, wrong Python implementation, unsupported runtime minimum/full contract, duplicates/malformed metadata, and unknown versions. Do not claim a generic future-version compatibility guarantee.
• After companion review/publication boundaries are decided, update four-language guidance/PARITY and the reviewed source pin together; explain merged PR14 and separately managed skill install/update/uninstall. No implicit postinstall, global PATH replacement or automatic skill deployment.
• Do not silently repin Python1.0.2/runtime parity, change the published0.3.2 artifact, or claim installation/live verification from this source audit.

Related migration-doc follow-up: #117. This issue is the compatibility/content coordination work; #117 is documentation correction and should not silently include a runtime compatibility-code change.

Python-side planning consultation — 2026-10-07

Planning feedback received under STS-PY-MUTUAL-IMPROVEMENT-ISSUES-20261007. This is not approval of candidate metadata values, runtime implementation, PR/merge, experiments or publication.

• Define and test the bounded TS runtime metadata support contract and fixtures for the existing and explicitly reviewed successor skill first. Publish the runtime containing that guard before publishing new skill metadata. Content/metadata candidates may be prepared as Draft beforehand, but compatibility must not be claimed before the guard is shipped.
• Document unsupported/incompatible behavior and upgrade guidance for older runtimes. Never declare arbitrary future skill versions compatible.
• Define runtime-full-version meaning separately from the minimum runtime requirement. Compatible remains a limited metadata-only verdict, not complete CLI support, send authorization or ACK support; optional capabilities continue to require resolved-executable version/help checks.
• Keep Python skill canonical metadata/snapshot, Python published runtime and existing parity/reference pins unchanged. TS skill/repository tag/npm runtime/Python skill version trains stay independent.
• Preserve distinctions between malformed/unknown and mismatched implementation/unsupported contracts with bounded scope/evidence output. Preserve published0.2/0.3 versus Draft0.4 feature boundaries, manager ownership, exact-version provisioning, no postinstall and submission-not-ACK semantics.

The skill maintainer receives these planning boundaries for rollout coordination; no new metadata value or release is authorized here.