diff --git a/ROADMAP.md b/ROADMAP.md index 1a31d2efc..d5321929b 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -48,6 +48,7 @@ - Keep public imported plugin surfaces and root marketplace wiring aligned in the same pass. - Keep user-facing plugin install and update docs on the official Git-backed marketplace path. - Keep the base `main` checkout clean for coordination and release verification; do implementation work in branch-backed worktrees unless Gale explicitly approves direct-main work. +- Keep this roadmap for active commitments and concise completion history. Shipped behavior belongs in its owning skill or plugin, and live cross-repository policy belongs in its owning maintainer reference; do not retain completed implementation plans as active sources of truth. ## Milestone Progress @@ -63,7 +64,7 @@ - Milestone 14: Core AI and Foundation Models workflow ownership - Completed - Milestone 15: Android Dev Skills plugin - Completed - Milestone 16: Server-Side JVM skills plugin - In Progress -- Milestone 17: Cross-agent skill and plugin portability - Planned +- Milestone 17: Cross-agent skill and plugin portability - In Progress - Milestone 18: Swift Lang shared language plugin - Completed - Milestone 19: Project audit skills plugin - Planned - Milestone 20: Game Dev Skills plugin - Completed @@ -73,9 +74,9 @@ - Milestone 24: Apple system integration, runtime evidence, and distribution workflows - Completed - Milestone 25: Apple Creator Studio operator workflows - Planned - Milestone 26: Messaging collaboration skills plugin - Completed -- Milestone 27: Cybersecurity skills plugin - Planned +- Milestone 27: Cybersecurity skills plugin - Completed - Milestone 28: Swift language tooling expansion - In Progress -- Milestone 29: Model Lab skills plugin - Planned +- Milestone 29: Model Lab skills plugin - Completed - Milestone 30: macOS virtualization and container skills expansion - Completed - Milestone 31: macOS platform security skills expansion - Completed - Milestone 32: tvOS app experience and media playback workflows - Completed @@ -84,7 +85,7 @@ ### Status -In progress +Completed ### Scope @@ -959,7 +960,7 @@ In Progress ### Status -Implemented; release pending +Completed ### Scope @@ -1087,7 +1088,7 @@ Completed ### Scope -- [x] Use [`docs/maintainers/tvos-skills-plan.md`](./docs/maintainers/tvos-skills-plan.md) as the source of truth for the focused Apple Dev Skills expansion. +- [x] Ship `tvos-app-experience-workflow` and `tvos-media-playback-workflow` as the source of truth for the focused Apple Dev Skills expansion. - [x] Add `tvos-app-experience-workflow` for remote-first SwiftUI/UIKit design, focus-system decisions, Large Text, platform gates, and TVMLKit migration routing. - [x] Add `tvos-media-playback-workflow` for AVKit system-player preference, custom-player escalation, remote commands, Now Playing state, and tvOS media validation. - [x] Preserve SwiftUI architecture, general accessibility, general AVFoundation, Core Media timing, AVFAudio, Xcode execution/testing, Model Lab runtime selection, and Apple-owned Core AI implementation ownership through clear handoffs. @@ -1208,14 +1209,15 @@ Completed - [x] Grow Swift Steward from read-heavy guidance-sync and repo-maintenance scans into reviewable patch artifacts that can be saved, edited, or applied by the main thread, then decide whether any apply-mode behavior belongs in the main thread, a guarded report workflow, or a future repo-local sidecar. - [x] Turn the placeholder `android-dev-skills` child plugin into an installable Android guidance plugin. It covers Kotlin-first Android project work, Java interoperability or Java-only maintenance when a repo requires it, Gradle and Android Gradle Plugin alignment, emulator-aware validation, release readiness, and clear handoffs to existing mobile testing plugins instead of duplicating emulator tooling. - [x] Replace the separate `mlx-skills` and `coreml-skills` plugin candidates with the coordinated `model-lab-skills:choose-apple-model-runtime` plan. Keep app integration in Apple Dev Skills and revisit a narrower plugin only if repeated work proves the combined boundary insufficient. -- [x] Expand Apple Dev Skills with dedicated SwiftUI animation, Core Animation, SF Symbols, and Apple typography workflows. Shipped `sf-symbols-workflow`, `swiftui-animation-workflow`, `core-animation-layer-workflow`, and `apple-typography-workflow` from [`docs/maintainers/apple-design-animation-skills-plan.md`](./docs/maintainers/apple-design-animation-skills-plan.md), keeping the skills under `plugins/apple-dev-skills`, using Xcode-local docs, Dash, official Apple docs, and local Apple developer apps as evidence, and avoiding absorption into the existing SwiftUI architecture skill. -- [x] Add an `apple-dev-skills:appkit-app-architecture-workflow` skill so AppKit has a first-party architecture decision surface parallel to SwiftUI. It covers menu bar apps, status items, responder-chain menus, window and view-controller ownership, app and window restoration, AppKit MVC, object archiving and persistence choices, Observation with AppKit, and mixed AppKit/SwiftUI composition without steering agents inordinately toward either framework. Started from [`docs/agents/appkit-skills-coverage-plan.md`](./docs/agents/appkit-skills-coverage-plan.md). +- [x] Expand Apple Dev Skills with dedicated SwiftUI animation, Core Animation, SF Symbols, and Apple typography workflows: `sf-symbols-workflow`, `swiftui-animation-workflow`, `core-animation-layer-workflow`, and `apple-typography-workflow`. Keep the skills under `plugins/apple-dev-skills`, use Xcode-local docs, Dash, official Apple docs, and local Apple developer apps as evidence, and avoid absorbing them into SwiftUI architecture guidance. +- [x] Add `apple-dev-skills:appkit-app-architecture-workflow` as AppKit's first-party architecture decision surface, covering menu bar apps, responder-chain menus, window and view-controller ownership, restoration, MVC, archiving, Observation, and mixed AppKit/SwiftUI composition. - [x] Complete Phase 2 of the Apple Dev Skills Socket migration. Treat `plugins/apple-dev-skills` as monorepo-owned source, remove Apple Dev Skills from subtree release gates, update Socket docs and duplicate-install guidance, add the compatibility marketplace smoke test, run full Socket validation, and publish the Socket release that makes the ownership change durable. - [x] Track the remaining Speak Swiftly duplicate-enable repair behavior in the standalone `SpeakSwiftlyServer` plugin workflow rather than keeping the completed Socket catalog split open: [gaelic-ghost/SpeakSwiftlyServer#98](https://github.com/gaelic-ghost/SpeakSwiftlyServer/issues/98). - [x] Restore Socket and the Apple Dev Skills compatibility surface to Apache License 2.0 after the source-available licensing experiment proved less useful than the adoption and goodwill of a standard permissive license. ## History +- Retired completed implementation plans for deferred wakeups, DeviceCheck/App Attest, tvOS, Apple design and animation, and AppKit coverage after their shipped skills and live policy became the authoritative owners; retained only active plans and compatibility/evidence records. - Re-contained SwiftData persistence guidance in a dedicated Apple Dev skill and SwiftUI composition in its architecture skill, while introducing the explicit three-letter Swift prefix and Xcode-friendly concatenated filename grammar. - Made Socket worktree-first for implementation work while keeping the base `main` checkout as the clean coordination and release-verification surface. - Aligned Socket documentation-source routing away from generic documentation aggregators by making Xcode MCP `DocumentationSearch` the Apple SDK default, Dash MCP/HTTP the preferred local-docs path for installed docsets across supported stacks, and canonical upstream docs/source the fallback when Dash/local coverage is missing or stale. diff --git a/docs/agents/appkit-skills-coverage-plan.md b/docs/agents/appkit-skills-coverage-plan.md deleted file mode 100644 index 8fca5c249..000000000 --- a/docs/agents/appkit-skills-coverage-plan.md +++ /dev/null @@ -1,163 +0,0 @@ -# AppKit Skills Coverage Plan - -## Purpose - -Audit the current Socket skill coverage for AppKit compared with SwiftUI, then -propose a durable Apple Dev Skills expansion that keeps agents neutral between -SwiftUI, AppKit, and mixed AppKit/SwiftUI app shapes. - -This report is a planning artifact. Durable decisions should move into -`ROADMAP.md`, `plugins/apple-dev-skills/AGENTS.md`, and the shipped skill files -when implementation starts. - -## Current Coverage - -### Strong SwiftUI Coverage - -`plugins/apple-dev-skills/skills/swiftui-app-architecture-workflow/` provides a -dedicated SwiftUI app-architecture workflow. It covers `App`, `Scene`, -`WindowGroup`, `Window`, `Settings`, `DocumentGroup`, commands, focus, focused -values, environment, preference keys, ownership boundaries, and common -anti-patterns. - -That means SwiftUI currently has a first-party Apple Dev Skills decision surface -for app structure and desktop-oriented SwiftUI concerns. - -### General Apple Docs Coverage - -`plugins/apple-dev-skills/skills/explore-apple-swift-docs/` is the canonical -docs-routing surface for Apple APIs, including AppKit, SwiftUI, Observation, and -Foundation-on-Apple. - -This gives AppKit work a required Apple-docs gate, but it does not itself teach -AppKit app ownership, menu-bar app structure, restoration, controller lifetimes, -or mixed AppKit/SwiftUI decisions. - -### SwiftASB-Specific AppKit Coverage - -`plugins/swiftasb-skills/skills/build-appkit-app/` provides useful AppKit -guidance, but only for SwiftASB integrations. It names `NSApplication`, -`NSApplicationDelegate`, `NSWindowController`, `NSViewController`, `NSWindow`, -menu and toolbar actions, panels, document windows, and main-actor UI updates. - -This is valuable evidence for the desired AppKit shape, but it should not be the -general AppKit architecture owner because it is intentionally scoped to -SwiftASB-backed features. - -## Gap - -Socket currently lacks the AppKit equivalent of -`swiftui-app-architecture-workflow`. - -The practical effect is that an agent working on a macOS app can be steered -toward SwiftUI app-architecture guidance even when the real problem belongs to -AppKit's app delegate, responder chain, menu validation, status item, window -controller, document controller, restoration, or archiving model. - -That does not mean the repository is anti-AppKit. It means AppKit has a docs gate -and one product-specific integration skill, while SwiftUI has a broad -architecture decision skill with supporting references. - -## Recommended Skill Shape - -Add `plugins/apple-dev-skills/skills/appkit-app-architecture-workflow/` as a -general Apple Dev Skills workflow. - -This should be a durable building-block change. Its job should be to help agents -choose and explain AppKit ownership shapes before implementation, not to replace -the Xcode build/test skills or the Apple docs router. - -### Core Scope - -- App lifecycle and app delegate ownership. -- Menu bar apps, `NSStatusItem`, status-item menus, popovers, panels, activation - policy, and quit behavior. -- Main menu, contextual menu, toolbar, responder-chain action routing, and menu - validation. -- Window ownership through `NSWindow`, `NSWindowController`, `NSViewController`, - panels, inspectors, and tabbed or multiwindow app shapes. -- Old-school restoration through `NSWindowRestoration`, restoration identifiers, - `NSApplicationDelegate`, `NSWindowController`, and document or workspace - reopening. -- Document-style and workspace-style ownership without forcing SwiftUI - `DocumentGroup`. -- AppKit MVC: model ownership, controller lifetimes, delegate responsibilities, - target/action, bindings where appropriate, and view-controller boundaries. -- Object persistence and archiving choices, including `NSSecureCoding`, - `NSKeyedArchiver`, `Codable`, user defaults, files, Core Data, SwiftData, and - explicit migration boundaries. -- Observation and AppKit interop: `@Observable` model ownership, main-actor UI - updates, bridging model changes into controls, and avoiding unnecessary - SwiftUI-only state assumptions. -- Mixed AppKit/SwiftUI composition through `NSHostingView`, - `NSHostingController`, SwiftUI views embedded in AppKit, AppKit views exposed - to SwiftUI, and clear ownership handoffs. - -### Explicit Non-Scope - -- Do not make this the raw Apple-docs lookup skill; hand off to - `explore-apple-swift-docs`. -- Do not make it the Xcode build, run, signing, file-membership, or testing - owner; hand off to `xcode-build-run-workflow` or `xcode-testing-workflow`. -- Do not absorb SwiftASB-specific runtime guidance; keep those details in - `swiftasb-skills`. -- Do not present AppKit as legacy-only or SwiftUI as automatically preferred. - The recommendation should choose the framework based on the app shape and the - API surface that actually owns the behavior. - -## Suggested Reference Files - -The new skill should mirror the SwiftUI architecture skill's reference-heavy -shape, but with AppKit-specific topics: - -- `references/app-delegate-and-lifecycle.md` -- `references/menu-bar-status-item-and-activation.md` -- `references/menus-responder-chain-and-validation.md` -- `references/windows-controllers-panels-and-inspectors.md` -- `references/restoration-documents-and-workspaces.md` -- `references/appkit-mvc-target-action-and-bindings.md` -- `references/archiving-persistence-and-migration.md` -- `references/observation-and-appkit.md` -- `references/mixed-appkit-swiftui-composition.md` -- `references/architecture-decision-rules.md` -- `references/anti-patterns-and-corrections.md` - -## Apple Documentation Gate - -Implementation should start from official Apple documentation for the exact API -families involved. Initial source targets include: - -- [AppKit](https://developer.apple.com/documentation/AppKit) -- [NSApplication](https://developer.apple.com/documentation/appkit/nsapplication) -- [NSApplicationDelegate](https://developer.apple.com/documentation/appkit/nsapplicationdelegate) -- [NSWindow](https://developer.apple.com/documentation/appkit/nswindow) -- [NSWindowController](https://developer.apple.com/documentation/appkit/nswindowcontroller) -- [NSViewController](https://developer.apple.com/documentation/appkit/nsviewcontroller) -- [NSStatusItem](https://developer.apple.com/documentation/appkit/nsstatusitem) -- [NSMenu](https://developer.apple.com/documentation/appkit/nsmenu) -- [NSResponder](https://developer.apple.com/documentation/appkit/nsresponder) -- [NSWindowRestoration](https://developer.apple.com/documentation/appkit/nswindowrestoration) -- [NSSecureCoding](https://developer.apple.com/documentation/foundation/nssecurecoding) -- [NSKeyedArchiver](https://developer.apple.com/documentation/foundation/nskeyedarchiver) -- [Observation](https://developer.apple.com/documentation/Observation) -- [NSHostingView](https://developer.apple.com/documentation/swiftui/nshostingview) -- [NSHostingController](https://developer.apple.com/documentation/swiftui/nshostingcontroller) - -## Acceptance Criteria - -- Apple Dev Skills exposes an AppKit architecture workflow that is parallel in - weight to the SwiftUI architecture workflow. -- Menu bar apps and status-item apps are first-class AppKit shapes, not edge - cases hidden under generic Xcode guidance. -- Restoration, archiving, MVC, target/action, responder chain, and controller - lifetimes are documented as modern AppKit concerns instead of treated as stale - trivia. -- Mixed AppKit/SwiftUI guidance names which framework owns each responsibility - and how state crosses the boundary. -- Observation guidance explains practical AppKit use without assuming SwiftUI - property-wrapper semantics. -- Handoffs stay clear among AppKit architecture, SwiftUI architecture, - Apple-docs lookup, Xcode execution, accessibility, and SwiftASB integration. -- Socket metadata validation and Apple Dev Skills child validation pass after - implementation. - diff --git a/docs/maintainers/apple-design-animation-skills-plan.md b/docs/maintainers/apple-design-animation-skills-plan.md deleted file mode 100644 index e0837a8b3..000000000 --- a/docs/maintainers/apple-design-animation-skills-plan.md +++ /dev/null @@ -1,100 +0,0 @@ -# Apple Design, Animation, Typography, and Symbols Skills Plan - -This plan captures a candidate Apple Dev Skills expansion for SwiftUI animation, Core Animation, Apple's San Francisco typography family, and SF Symbols. - -## Status - -Implemented. The first implementation slice shipped `sf-symbols-workflow` and `swiftui-animation-workflow`; the second slice shipped `core-animation-layer-workflow` and `apple-typography-workflow`. - -## Ownership - -These skills belong in `plugins/apple-dev-skills` because they depend on Apple framework behavior, Xcode integration, local Apple developer tools, and Apple documentation. They should not move into `swift-lang`, which owns shared Swift language guidance rather than Apple UI frameworks or design-tool workflows. - -The existing `swiftui-app-architecture-workflow` should stay focused on app structure, scenes, commands, focus, environment, preferences, and view composition. Animation, typography, and symbol production need separate workflow surfaces so architecture guidance does not become a generic SwiftUI grab bag. - -## Proposed Skill Set - -### `swiftui-animation-workflow` - -Use for SwiftUI animation design and repair across animation modifiers, transactions, matched geometry, timeline-driven rendering, phase and keyframe animation APIs, symbol effects, transitions, accessibility reduce-motion behavior, previews, and performance-oriented validation. - -This skill should help an agent: - -- classify whether the work is interaction feedback, state transition, timeline animation, hero transition, loading/progress motion, decorative motion, or accessibility-sensitive motion -- choose SwiftUI-native animation before dropping into Core Animation or lower-level rendering -- preserve data flow clarity by keeping motion derived from explicit state instead of hidden side effects -- route structural SwiftUI questions back to `swiftui-app-architecture-workflow` -- route build, preview, simulator, and Xcode project validation to `xcode-build-run-workflow` - -### `core-animation-layer-workflow` - -Use for lower-level layer-backed animation and rendering with Core Animation, including `CALayer`, layer trees, implicit and explicit animations, `CAAnimation`, transactions, timing, shape layers, gradient layers, replicator layers, text layers, view/layer bridging, and performance diagnosis. - -This skill should help an agent: - -- decide when Core Animation is justified instead of SwiftUI animation, AppKit/UIKit animation helpers, Canvas, SpriteKit, SceneKit, Metal, or video rendering -- keep layer ownership explicit when bridging SwiftUI, AppKit, or UIKit surfaces -- reason about model layer versus presentation layer behavior before proposing fixes -- avoid custom timers or manual invalidation when framework timing primitives fit -- hand off Xcode, Instruments, simulator, or device validation to the existing execution skills - -### `apple-typography-workflow` - -Use for Apple platform typography decisions involving the San Francisco family and system typography APIs. - -This skill should help an agent: - -- choose system typography APIs before bundling font files -- distinguish design guidance, font family selection, variable behavior, Dynamic Type, accessibility, platform conventions, and implementation APIs -- route SwiftUI, AppKit, UIKit, and asset/font integration to the right Apple docs and project validation paths -- call out licensing and redistribution boundaries once when a task asks to bundle, extract, modify, or redistribute Apple font assets -- avoid hard-coding local font file paths, private font copies, or nonportable assumptions into public project docs - -### `sf-symbols-workflow` - -Use for SF Symbols library, SF Symbols app, symbol availability, symbol effects, rendering modes, variable color, palette and hierarchical color, multicolor behavior, custom symbols, animated symbols, localization or directionality concerns, asset-catalog integration, and SwiftUI/AppKit/UIKit use. - -This skill should help an agent: - -- inspect current Apple documentation and the local SF Symbols app before making current-version claims -- choose between built-in symbols, customized symbol variants, custom symbol templates, ordinary vector artwork, and app icons -- validate custom symbol templates and exported assets through the SF Symbols app or documented tooling when available -- keep app-icon work routed to `icon-composer-app-icon-workflow` -- keep accessibility labels, semantic meaning, color modes, and platform availability visible in implementation guidance -- hand off build, preview, and asset-catalog integration to `xcode-build-run-workflow` - -## Local Tool Research Needed - -Before implementing these skills, run a short local evidence pass: - -- verify the SF Symbols app path and version on Gale's Mac -- check whether the app exposes useful scripting, command-line, Shortcuts, AppleScript, or Accessibility automation surfaces -- inspect current SF Symbols app menus and export/validation workflows with Computer Use only when the task needs GUI evidence -- prefer Xcode-local documentation and Dash when available, then official Apple documentation -- record current authoritative source links in the skill bodies only where they guide workflow decisions - -## Implementation Slices - -The first slice shipped two skills: - -1. `sf-symbols-workflow`, because it has the richest local-tool surface and the clearest boundary with existing Icon Composer guidance. -2. `swiftui-animation-workflow`, because it fills the most common app-implementation gap without forcing lower-level Core Animation guidance into the same skill. - -The second slice added `core-animation-layer-workflow` and the broader `apple-typography-workflow` name so the typography surface can cover San Francisco, New York, SF Mono, Dynamic Type, and custom app-font boundaries without a later rename. - -## Metadata And Validation Tasks - -- Add each skill under `plugins/apple-dev-skills/skills/`. -- Add `agents/openai.yaml` metadata for each skill. -- Update `plugins/apple-dev-skills/.codex-plugin/plugin.json` keywords, description, long description, and default prompts. -- Update `plugins/apple-dev-skills/AGENTS.md` only if local Apple design-tool rules need a narrower owner rule than the existing Apple Rules section. -- Add targeted tests that verify skill frontmatter, routing boundaries, docs-gate language, and important handoffs. -- Run `bash .github/scripts/validate_repo_docs.sh` from `plugins/apple-dev-skills`. -- Run `uv run pytest` from `plugins/apple-dev-skills` when tests change. -- Run `uv run scripts/validate_socket_metadata.py` from the Socket root after metadata changes. - -## Open Questions - -- Should `sf-symbols-workflow` include guided Computer Use walkthrough prompts for the SF Symbols app in the first release, or should the first release stay docs-and-routing only? -- Should San Francisco typography live as its own skill, or should it start as a broader `apple-typography-workflow` that treats SF as the default system font family while leaving room for New York and custom app fonts? -- Should animated SF Symbols stay inside `sf-symbols-workflow`, or should `swiftui-animation-workflow` own symbol effects once the symbol choice is already made? diff --git a/docs/maintainers/deferred-work-wakeup-policy-plan.md b/docs/maintainers/deferred-work-wakeup-policy-plan.md deleted file mode 100644 index f0e661b84..000000000 --- a/docs/maintainers/deferred-work-wakeup-policy-plan.md +++ /dev/null @@ -1,313 +0,0 @@ -# Deferred Work Wakeup Policy: Audit and Implementation Plan - -## Status - -Superseded by the live [Deferred Work Wakeup Policy](./deferred-work-wakeup-policy.md). -This document preserves the audit, design, and acceptance record for the -implementation released in Socket v9.30.0. - -## Decision - -When an agent has started a remote or externally-owned operation that will not -produce a useful result promptly, it must stop actively waiting and schedule a -future continuation using the current host's approved scheduler. It must not -keep a terminal, polling loop, or status-watch command open merely to wait for -CI, a review bot, a hosted build, a release publication, deployment readiness, -or a remote worker. - -This is a durable cross-host policy, not a new generic runtime abstraction. -It removes the current split where a release script can describe a Codex -heartbeat while the surrounding portable skills still imply that an agent may -watch the remote state directly. The simpler extension considered first was to -clarify the existing Codex-only wording in `maintain-project-repo`; that would -leave deployment, CI, and Hermes users with incompatible behavior. - -### Boundary - -The rule applies to an *agent waiting for an external process or service*. -It does not replace: - -- a program's own synchronization primitive, protocol polling, event loop, or - test assertion; -- a short, bounded, immediate API-consistency probe needed to finish the - command that caused the mutation; or -- a tool-owned foreground operation whose live output is necessary to diagnose - the operation and cannot safely be inspected concurrently. - -The implementation must define "short and bounded" concretely: at most one -immediate re-read or a documented sub-minute command-local timeout. Repeated -or multi-minute checks become deferred work. A wakeup must capture the target, -the observed state, the next check time, the continuation command or query, -and the gate that remains closed. - -### Minimum Continuation Interval - -Every agent-created heartbeat, continuation, or scheduled re-check must be at -least **five minutes** after its observation time. This is a minimum, not a -recommended cadence: agents must never schedule a one-, two-, or four-minute -heartbeat/cron job to emulate polling. They may choose a longer delay when the -provider, CI queue, approval window, or prior state makes that more honest. - -The only shorter operation is the command-local, one-time bounded re-read -defined above. It completes the current mutation attempt; it is not scheduled, -is not repeated, and must not grow into a polling loop. - -### Continuation Reuse - -Before scheduling a remote-gate continuation, inspect for a live scheduler item -for the same repository/target, gate, and identity. If that gate is still -pending and has not failed or changed, reuse the existing heartbeat or cron job -unchanged; do not delete and recreate it merely because the fresh snapshot is -also pending. Pause or delete the item when the gate clears, fails, is -cancelled, or the identity drifts. A new or updated item is appropriate only -after the prior continuation has fired or its recorded state is no longer the -current gate. - -## Host Contract - -| Host | Required continuation surface | Required setup/check | Continuation rule | -| --- | --- | --- | --- | -| Codex desktop / ChatGPT app | A current-thread `heartbeat` created through the host automation surface. | Confirm that the active host exposes the heartbeat automation tool and look for a live matching heartbeat first. | Reuse the matching heartbeat while its named PR, run, release, deployment, or process gate is pending and healthy. Pause/delete it only on resolution, failure, cancellation, or identity drift. | -| Hermes Agent | `cronjob(action="create" or update, ...)` with a relative schedule of five minutes or longer, `deliver="origin"`, and `attach_to_session=true`. | Confirm the `cronjob` tool is enabled and `hermes cron status` reports an active gateway, then look for a matching cron job first. | Reuse/update the matching cron job rather than churning jobs on an unchanged pending state. The cron execution is a fresh agent run, so its prompt must be self-contained. `attach_to_session=true` makes the delivered result continuable in the origin conversation; it does not revive a suspended shell or silently authorize the remaining release steps. | -| Other hosts | That host's documented future-wakeup or scheduled-task tool. | Verify its availability and inspect for a matching live item before use. | Reuse it while healthy and pending; only create/replace it after it fires or becomes resolved, failed, cancelled, or stale. If the host has no approved continuation mechanism, report that limitation and return control rather than emulating a long wait with `sleep`, a background loop, or an idle shell. | - -Hermes evidence: its official [Scheduled Tasks (Cron)](https://hermes-agent.nousresearch.com/docs/user-guide/features/cron) -documentation identifies `cronjob` as the agent-facing scheduler, describes -one-shot schedules, and documents continuable jobs through -`attach_to_session`. The same documentation also makes the important boundary -explicit: cron runs in a fresh agent session, so continuation prompts must not -depend on unstated prior context. - -## Audit Method and Results - -The audit searched the tracked Socket source for agent-facing `wait`, `sleep`, -`poll`, `watch`, `monitor`, `heartbeat`, `wakeup`, `release`, `GitHub Actions`, -and deployment guidance. It found 169 files with a generic wait-related token -and 202 files with a release/deployment-related token. Most are intentionally -outside this policy: application runtime semantics, test synchronization, -watch-directory configuration, historical plans, or generic release mentions. - -The following are the complete actionable set. Derived Hermes exports are -listed separately and must be regenerated, never hand-edited. - -| Surface | Current state | Planned change | -| --- | --- | --- | -| Root `AGENTS.md` | Says a pushed branch does not imply waiting on CI, but has no universal agent-wait rule. | Add the host-neutral mandatory policy and the short bounded-probe exception; route detailed release behavior to `maintain-project-repo`. | -| `plugins/agent-engineering-skills/skills/schedule-agent-work/SKILL.md` | Selects a native scheduled task but does not map the current hosts or ban idle remote waits. | Add the host matrix above and a required deferred-work envelope. Keep it about scheduling; do not duplicate release choreography. | -| `plugins/repository-skills/skills/maintain-project-repo/SKILL.md` | Recommends a Codex heartbeat only "when available" and describes the full remote-CI mode as a normal default. | Make deferred scheduling mandatory for agent-run remote gates; name Codex heartbeat and Hermes `cronjob` precisely; require a state snapshot and explicit resume gate. | -| `plugins/repository-skills/skills/maintain-project-repo/references/automation-prompts.md` | Mentions only a Codex heartbeat. | Replace it with host-neutral prompts covering Codex and Hermes, and forbid a long-lived polling shell. | -| `plugins/repository-skills/skills/maintain-project-repo/references/release-modes.md` | Permits `gh pr checks --watch` by default and says a same-thread Codex heartbeat for defer. | Specify that agent-run standard releases enter deferred mode after the initial state snapshot; describe continuation packets and both host implementations. | -| `plugins/repository-skills/skills/maintain-project-repo/assets/repo-maintenance/config/release.env` | Defaults `REPO_MAINTENANCE_REMOTE_CI_MODE=full`; comments name a vague Timer/Wakeup or heartbeat. | Default agent-oriented configuration to `defer`, name the host-level scheduler requirement, and retain any blocking mode only as an explicit human-operated shell opt-in if it remains supported. | -| `plugins/repository-skills/skills/maintain-project-repo/assets/repo-maintenance/release.sh` | `full` uses `gh pr checks --watch`; `defer` still has Codex-only wording. | Make defer emit one structured, parseable continuation packet after the initial snapshot. Do not let agent guidance select `full`. Preserve short remote-visibility retries only within the policy boundary; otherwise return the packet for scheduling. | -| `plugins/repository-skills/skills/maintain-project-repo/assets/repo-maintenance/lib/common.sh` | Uses five-second polling loops for branch, tag, release, and initial-check visibility. | Separate bounded read-after-write convergence from remote job monitoring; cap/document the former and return actionable state instead of extending it into a remote wait. | -| `plugins/repository-skills/skills/maintain-project-repo/tests/test_maintain_project_repo_workflow.py` | Locks in Codex-only heartbeat wording and the blocking watcher. | Replace those assertions with portable policy assertions, structured-packet coverage, and a test that agent defaults never invoke `gh ... --watch`. | -| Apple guidance templates: `bootstrap-swift-package/assets/AGENTS.md`, `bootstrap-xcode-app-project/assets/AGENTS.md`, `sync-swift-package-guidance/assets/AGENTS.md`, `sync-swift-package-guidance/assets/append-section.md`, `sync-xcode-project-guidance/assets/AGENTS.md`, and `sync-xcode-project-guidance/assets/append-section.md` | Each tells generated repositories to "watch CI". | Replace with the shared deferred remote-gate rule so downstream repositories do not reinstall the old behavior. Update their focused tests. | -| `plugins/cloud-deployment-skills/skills/dockerized-service-release-deployment-workflow/SKILL.md` | Correctly forbids blind Docker polling, but says to wait on an active build without a host continuation instruction. | Add an explicit ownership-preserving deferred-wakeup rule for hosted build, release-published deployment, environment approval, health, and rollback gates. A wakeup must inspect the original log/session without starting a concurrent Docker operation. | -| `skills/dockerized-service-release-deployment-workflow/` | Generated Hermes export of the Cloud Deployment skill. | Regenerate with `uv run scripts/export_hermes_skills.py`; do not edit this mirror. | -| `plugins/server-side-swift/skills/fly-io-deployment-workflow/SKILL.md` | Covers `fly deploy`, logs, status, and health checks but does not say how an agent waits when the rollout takes time. | Add a deployment-specific continuation checkpoint after an accepted deploy: snapshot app/region/release state, schedule a host wakeup, then inspect status/checks/logs at the wakeup. | -| `plugins/cloud-inference-skills/skills/flash/SKILL.md` | An upstream Runpod mirror uses an unbounded `sleep 2` readiness loop for a long-running local server. | Do not hand-edit this mirror. First confirm the upstream refresh path; then update upstream or carry an approved Socket wrapper/reference that replaces unbounded agent waiting with a short readiness probe followed by a host wakeup. | - -### Explicitly audited but not changed - -- GitHub Actions design skills for Android, .NET, Python, and Rust teach CI - construction rather than an agent waiting for a remote run. They will receive - a short cross-reference only if a concrete release/deployment wait is added; - duplicating the entire host matrix there would be drift. -- Application polling, SwiftNIO nonblocking-I/O rules, XCUITest waits, test - confirmations, callback-server waits, media-job monitoring, and shell cleanup - `wait` calls are program behavior, not an agent's idle wait. They remain - unchanged. -- Historical roadmap entries retain their historical wording. A new current - ticket records this plan instead of rewriting release history. - -## Proposed Release Automation Shape - -### What Changes for Maintainers - -The release tooling stays highly automated, but it stops pretending that one -shell process should remain alive for the whole lifecycle. A maintainer starts -the release once. The script advances through every immediately provable step, -then returns a precise continuation packet when GitHub or a deployment platform -owns the next result. The host schedules the next inspection and the same -release command safely advances again. - -This is a durable building-block change. It unlocks unattended-but-gated -protected-main releases, review-bot handling, release-published deployments, -and reliable restart/retry behavior without leaving an agent or terminal idle. -It removes duplicated release choreography in host prompts and eliminates the -current confused ownership between `release.sh` and a host scheduler. - -The simpler extension path was retaining one large release script and replacing -only `gh pr checks --watch`. That would still combine local mutation, remote -observation, sleep loops, and resume instructions in one opaque process; a -failed or restarted session would remain difficult to reason about. - -### Responsibilities - -| Surface | Owns | Must not own | -| --- | --- | --- | -| `release.sh` | Deterministic preflight, validation, version bump, Git mutations, PR/release inspection, safe state transitions, and emitting continuation packets. | Sleeping, `gh --watch`, indefinite polling, or scheduling host work. | -| Codex heartbeat / Hermes cron job | Waiting until the chosen next check, then invoking an explicit re-inspection or advance prompt in the correct repository context. | Inventing release state, bypassing approval gates, or assuming a prior shell remains alive. | -| Git and GitHub | Authoritative branch, commit, PR, check, review, merge, tag, and release state. | Storing machine-local secret values or inferred local-validation results. | -| Deployment workflow / provider adapter | Deploying an exact approved artifact and reporting provider-specific rollout/health state. | Rebuilding source, mutating Git release state, or making a production approval decision. | - -No database, daemon, or generic queue is proposed. The continuation packet is -transport, not a second source of truth. On every invocation, the script reads -Git and GitHub again and treats a changed branch tip, PR, tag, or release as a -new fact that must be validated or surfaced. - -### Commands and State Transitions - -Replace the current monolithic `standard` path with three idempotent modes: - -| Command | Performs | Stops and emits a packet when | -| --- | --- | --- | -| `release.sh prepare --mode standard --version vX.Y.Z` | Validates locally, creates or recognizes the version-bump commit, pushes the branch, creates/finds the PR, and reads one initial PR/check snapshot. | The PR/check/review gate is not conclusively clear. | -| `release.sh inspect --mode standard --version vX.Y.Z` | Reads only: branch tip, PR, check, review/comment, merge, tag, and GitHub Release state. | It always returns a normalized state and never waits or mutates. This is the default scheduled-wakeup action. | -| `release.sh advance --mode standard --version vX.Y.Z` | Re-reads state, verifies the expected branch/PR/tag identity, then performs every safe immediately-ready next step: merge, fast-forward, tag, push tag, create/verify Release, and branch accounting. | A remote gate is pending, a read-after-write result is not immediately visible, state differs from the packet, or an approval/review condition is not satisfied. | - -`advance` is intentionally resumable, not blindly transactional. Re-running it -after an interruption must recognize an existing version-bump commit, PR, -merge, tag, or release only when it points at the expected commit. A branch tip -that changed after `prepare` invalidates that prepare result and sends the -release back to the local-validation gate rather than merging new code on the -strength of stale checks. - -An explicit human-only `--remote-ci-mode full` may remain as a convenience for -a terminal user who deliberately wants live `gh` output. It is not the default -agent path and is never selected by guidance. The agent default becomes this -prepare/inspect/advance path; it does not call a blocking watcher. - -### Continuation Packet - -When a command reaches an external gate, it writes one human-readable summary -and one machine-readable JSON object. The packet contains no credentials and -is sufficient for a fresh Hermes cron session or a later Codex heartbeat: - -```json -{ - "schema": "repo-maintenance-continuation/v1", - "operation": "standard-release", - "repository": "owner/repository", - "release_tag": "vX.Y.Z", - "branch": "release/vX.Y.Z", - "head_commit": "full-commit-sha", - "pr_number": "123", - "phase": "awaiting-pr-checks", - "minimum_delay_minutes": 5, - "resume_command": "scripts/repo-maintenance/release.sh --mode standard --version vX.Y.Z --operation inspect", - "advance_command": "scripts/repo-maintenance/release.sh --mode standard --version vX.Y.Z --operation advance" -} -``` - -`minimum_delay_minutes` is the script's sole delay field; it must be at least -five. The host adapter schedules no sooner than that floor. Its prompt must -include the packet, tell the agent to run `inspect` first (or `prepare` for a -pre-PR `not-started` or `awaiting-branch-visibility` packet), and permit -`advance` only if the packet's repository, tag, branch, commit, and gate still -match current source-of-truth state. If still pending and the same continuation -is live, it retains that scheduler item rather than replacing it. It creates or -updates a continuation only after the previous one fires or is stale. If failed -or changed, it reports the discrepancy and does not continue automatically. - -### Lifecycle - -1. `prepare` validates the release candidate and publishes the release branch - and PR. It emits `awaiting-pr-checks` instead of watching CI. -2. The host creates one continuation, or reuses the live matching item. The - wakeup runs `inspect` and either reports a failed/changed gate, retains the - healthy pending item (or updates it after it fires), or calls `advance`. -3. `advance` verifies CI, review comments, and review-bot contexts before - merging. It never treats a pending bot as approval. -4. After merge, `advance` fast-forwards the local base, creates/pushes the tag, - and creates/verifies the GitHub Release. A remote object that is not yet - visible produces another packet, not a sleep loop. -5. Release completion remains distinct from deployment completion. A - release-published deployment workflow receives the immutable artifact and - creates its own provider/health continuation packet. It does not make the - Git release script wait for a server rollout. -6. Final branch accounting and cleanup occur only after the GitHub Release - state is confirmed. A pending deployment is reported separately, never - misrepresented as a failed or completed release. - -### Failure and Recovery Rules - -- A failed check, requested changes, new review comment, or changed branch tip - stops advancement and names the exact next human or agent action. -- A scheduler failure never authorizes a fallback polling loop. The current - state and continuation packet are reported for a user-directed retry. -- A duplicate wakeup is harmless: `inspect` is read-only and `advance` verifies - identities before every mutation. -- A restart on a different host does not reuse machine-local shell state. It - can only continue after resolving the repository and proving the packet still - matches Git/GitHub state. -- Deployment adapters retain their own approval and rollback rules. The release - executor only proves the release artifact is published and hands off its - exact immutable reference. - -## Implementation Sequence - -1. Add the universal root rule and the `schedule-agent-work` host matrix. Define - the continuation packet fields, five-minute minimum interval, scheduler - adapter contract, and bounded-probe exception once. -2. Refactor `maintain-project-repo` from its monolithic release path into - idempotent `prepare`, `inspect`, and `advance` commands. Keep Git/GitHub as - the source of truth; do not add a database or background daemon. -3. Change `maintain-project-repo` documentation, prompts, release-mode - reference, defaults, script output, and focused tests together. Preserve - `full` only as an explicit human-only choice if maintainers still want it; - agents must not select it. -4. Update all six Apple generated-guidance sources and their tests so a newly - bootstrapped or synchronized repository inherits the same release policy. -5. Add deployment-specific checkpoints in the Dockerized-service and Fly.io - workflows. Preserve their existing production approval, exact-digest, - ownership, health-check, rollback, and separate deployment-completion gates. -6. Resolve the Runpod Flash upstream-mirror boundary: inspect its upstream - source and refresh policy, then make the smallest maintainable change rather - than editing the checked-in mirror directly. -7. Regenerate Hermes exports, run root and child validation, and use a focused - fixture to verify the Codex heartbeat and Hermes cron continuation prompts - contain the same target, state, resume command, and closed gate. - -## Acceptance Criteria - -- No agent-facing release, CI, or server-deployment guidance tells an agent to - keep `gh ... --watch`, `sleep` polling, or an idle terminal open for a - long-running remote gate. -- Codex instructions always use a same-thread heartbeat automation. -- Hermes instructions always use one-shot `cronjob` plus `deliver="origin"`, - `attach_to_session=true`, a self-contained prompt, and gateway/tool - availability verification. -- Every continuation packet emits `minimum_delay_minutes >= 5`, and every - agent-created heartbeat or scheduled re-check honors that floor; focused - tests reject shorter values and repeated short-delay reschedules. -- The release script returns a machine-readable continuation packet in deferred - mode, supports idempotent `prepare`, read-only `inspect`, and guarded - `advance` actions, and cannot accidentally merge, tag, or release while the - named remote gate is pending. -- A changed branch tip invalidates its prior local-validation result; a duplicate - continuation cannot produce duplicate merges, tags, or releases. -- Release publication and provider deployment remain separate state machines - with separate completion claims. -- Script-level read-after-write visibility checks are clearly bounded and do - not masquerade as a long-running CI or deployment monitor. -- Docker and Fly deployment instructions preserve existing ownership and safety - constraints while making the future wakeup mandatory. -- Generated Hermes skill exports are current and no generated file was edited - by hand. - -## Validation Plan - -Run, serially: - -```bash -uv run scripts/validate_socket_metadata.py -uv run scripts/validate_hermes_compatibility.py -uv run scripts/export_hermes_skills.py --check -uv run pytest plugins/repository-skills/skills/maintain-project-repo/tests/test_maintain_project_repo_workflow.py -``` - -Then run the affected child-plugin tests identified by the template and skill -changes. Use non-mutating fixtures for the release-script continuation packet; -do not open a real PR, schedule a real persistent Hermes job, deploy a service, -or alter a cloud account merely to validate this guidance. diff --git a/docs/maintainers/deferred-work-wakeup-policy.md b/docs/maintainers/deferred-work-wakeup-policy.md index f419ae652..9fb8779c3 100644 --- a/docs/maintainers/deferred-work-wakeup-policy.md +++ b/docs/maintainers/deferred-work-wakeup-policy.md @@ -1,9 +1,7 @@ # Deferred Work Wakeup Policy Use this live reference when an agent needs to resume work after external CI, -review, release, deployment, provider, or remote-worker state changes. The -historical audit and design record is retained in -[deferred-work-wakeup-policy-plan.md](./deferred-work-wakeup-policy-plan.md). +review, release, deployment, provider, or remote-worker state changes. ## Required Behavior diff --git a/docs/maintainers/devicecheck-app-attest-skill-plan.md b/docs/maintainers/devicecheck-app-attest-skill-plan.md deleted file mode 100644 index d6a837968..000000000 --- a/docs/maintainers/devicecheck-app-attest-skill-plan.md +++ /dev/null @@ -1,92 +0,0 @@ -# DeviceCheck and App Attest Skill Record - -This record captures the shipped Apple Dev Skills expansion for the DeviceCheck framework, including per-device DeviceCheck state and App Attest app-instance validation. - -## Status - -Implemented. The first implementation shipped one focused workflow skill, `devicecheck-app-attest-workflow`, rather than separate `device-identification` and `app-attest` skills. - -## Ownership - -This skill belongs in `plugins/apple-dev-skills` because it depends on Apple framework behavior, app IDs, entitlements, Xcode signing state, Apple Developer account setup, local Apple documentation, and Apple server APIs. - -The skill should stay separate from the broader client auth and sync milestone. DeviceCheck and App Attest are risk and integrity signals for a server-backed app, not a general credential-storage or session-management workflow. - -The server verification side should be explicit but bounded. Apple Dev Skills can guide the client/server contract, challenge shape, App Attest object flow, and validation checklist, but server implementation should hand off to server-side Swift, OpenAPI, or RPC workflows when the backend code or API contract is the primary change. - -## Documented Apple Behavior To Rely On - -Apple documentation describes DeviceCheck as a framework plus Apple server APIs for reducing fraudulent use by managing device state and asserting app integrity. - -Device identification uses `DCDevice` in the app to generate an ephemeral token. The server uses that token with a JWT-backed Apple server request to query, update, or validate two per-device bits stored by Apple. The app must check `DCDevice.current.isSupported`, and the app must have an Apple Developer registered App ID. - -App Attest uses `DCAppAttestService` to generate a Secure Enclave-backed key, ask Apple to attest that key, and later generate assertions for sensitive server requests. The app must check `DCAppAttestService.shared.isSupported`, the app must have a registered App ID, and server-side challenge handling is required to prevent replay attacks. - -App Attest has important rollout and environment constraints: - -- Sandbox and production keys and receipts are separate. -- Distributed apps operate in production mode. -- Large existing user bases should ramp attestation gradually because attestation contacts Apple servers and can be rate limited. -- Attestation failures with `serverUnavailable` should retry later using the same key and `clientDataHash`. -- App Attest does not prove that a device operating system is uncompromised; it supplies one signal for a broader fraud-risk decision. -- On macOS, App Attest verification has macOS-specific signing identifier and key access-policy checks. - -## Implemented Skill - -### `devicecheck-app-attest-workflow` - -Use for DeviceCheck and App Attest decisions in Apple-platform apps, including `DCDevice`, per-device two-bit state, `DCAppAttestService`, App Attest key lifecycle, server challenge design, attestation and assertion request shapes, app IDs, entitlements, sandbox versus production environments, rollout/rate-limit planning, and client/server handoffs. - -This skill helps an agent: - -- classify whether the request is DeviceCheck two-bit device state, App Attest app-instance integrity, or a broader auth/session/sync concern -- apply the Apple docs gate before making current framework, entitlement, platform, or server-endpoint claims -- preserve the client/server boundary instead of pretending the app can validate itself -- keep key identifiers persistent but avoid storing secrets or treating attestation objects as app-side proof -- distinguish development, sandbox, TestFlight, App Store, Enterprise, Developer ID, and macOS signing behavior where Apple docs require it -- plan server challenges, replay protection, assertion counters, public-key storage, receipt storage, and risk metrics without making Apple Dev Skills own a backend implementation -- route Xcode signing, entitlements, App ID capability, build, run, simulator, device, and test follow-through to `xcode-build-run-workflow` or `xcode-testing-workflow` -- route generated client APIs to `swift-openapi-client-workflow` -- route backend validation implementation to the relevant server-side Swift or API-contract workflow when available - -## Shipped Skill Shape - -The shipped first version is guidance and routing, not a deterministic validator. App Attest server verification includes CBOR, COSE, ASN.1, certificate-chain, receipt, environment, signing-category, and counter checks, which are too stack-specific for a tiny first slice. - -Shipped first payload: - -- `SKILL.md` with the core workflow, docs gate, classification, handoffs, and guardrails. -- `agents/openai.yaml` metadata generated from the skill body. -- `references/devicecheck-device-state.md` for `DCDevice`, two-bit state, JWT, query/update/validate endpoints, privacy, and reset semantics. -- `references/app-attest-client-flow.md` for `DCAppAttestService`, key ID persistence, challenge hashing, attestation, assertions, `DCError`, and retry behavior. -- `references/app-attest-server-validation.md` for server-side validation checklist, receipt/risk metric handling, sandbox versus production, replay protection, counters, and macOS-specific validation notes. -- `references/entitlements-app-id-and-validation.md` for App ID, DeviceCheck capability, App Attest environment entitlement, provisioning, Xcode handoffs, simulator/device expectations, and rollout gates. - -Avoid scripts in the first slice unless a concrete backend stack needs one. If a later project repeatedly needs App Attest verification in Swift, add a separate deterministic reference implementation or test helper after the server-side owner is clear. - -## Implementation Slices - -1. Planning and docs evidence: - - [x] Add this plan and roadmap milestone. - - [x] Keep the plan grounded in Xcode and Dash documentation lookups. - - [x] Decide the one-skill shape unless implementation evidence shows the workflow becomes too large. -2. Skill scaffold: - - [x] Initialize `devicecheck-app-attest-workflow` under `plugins/apple-dev-skills/skills/`. - - [x] Add references and generated `agents/openai.yaml`. - - [x] Keep `SKILL.md` concise and move detailed validation checklists into references. -3. Metadata and inventory: - - [x] Update `plugins/apple-dev-skills/.codex-plugin/plugin.json`. - - [x] Update `plugins/apple-dev-skills/README.md` active skill inventory and prompt list. - - [x] Update `plugins/apple-dev-skills/ROADMAP.md` status and ticket completion. -4. Tests and validation: - - [x] Add targeted tests for frontmatter, routing boundaries, docs-gate language, server-handoff language, and metadata inventory. - - [x] Run `bash .github/scripts/validate_repo_docs.sh` from `plugins/apple-dev-skills`. - - [x] Run `uv run pytest` from `plugins/apple-dev-skills` when tests change. - - [x] Run `uv run scripts/validate_socket_metadata.py` from the Socket root after metadata changes. - -## Future Questions - -- The first implementation uses `devicecheck-app-attest-workflow`; a broader `apple-app-integrity-workflow` can still be considered later if another Apple integrity signal needs a shared owner. -- Should server-validation guidance stay purely checklist-based at first, or should the initial skill include stack-specific examples for Swift server apps? -- Should DeviceCheck two-bit state and App Attest stay permanently in one skill, or should DeviceCheck split out later if two-bit state becomes common outside App Attest integrity flows? -- Should the first implementation include migration guidance for apps that already use custom device identifiers, receipt validation, or server-side abuse flags? diff --git a/docs/maintainers/tvos-skills-plan.md b/docs/maintainers/tvos-skills-plan.md deleted file mode 100644 index 01360e3df..000000000 --- a/docs/maintainers/tvos-skills-plan.md +++ /dev/null @@ -1,227 +0,0 @@ -# tvOS Skills Plan - -This plan defines the first Socket-owned tvOS guidance expansion. It is a -durable Apple Dev Skills building-block change: two narrow workflows make the -Apple TV-specific interaction and media contracts reusable without turning the -general SwiftUI, AVFoundation, or model-runtime skills into tvOS catch-alls. - -## Status - -Completed and released in Socket v9.23.0. This document remains as the -implementation and evidence record for the two shipped workflows. - -## Decision - -Add two workflows under `plugins/apple-dev-skills/skills/`: - -- `tvos-app-experience-workflow` -- `tvos-media-playback-workflow` - -Keep the first release guidance-only. It must not bundle a TVML runtime, -remote-control daemon, player abstraction, simulator wrapper, media service, -model asset, or Apple TV hardware test fixture. - -## Why Two Workflows - -The simpler extension path was to add tvOS paragraphs to -`swiftui-app-architecture-workflow`, `apple-ui-accessibility-workflow`, and -`avfoundation-media-pipeline-workflow`. That would make the common workflow -selection less clear and leave no single owner for remote focus behavior, -large-screen interaction, or media-command responsibility. - -`tvos-app-experience-workflow` owns app-wide interaction design and focus -semantics. `tvos-media-playback-workflow` owns the separate playback contract: -system-player preference, media commands, Now Playing state, and the complete -custom-player responsibility boundary. The split removes duplicated ad-hoc -advice and makes the next catalog, utility, game, or video app easier to plan -without adding a new app architecture layer. - -## Source Baseline - -Sources were checked on 2026-07-23 through Xcode DocumentationSearch, the -installed Dash Apple API references where relevant, and readable official -Apple documentation/release-note sources. - -- [Designing for tvOS](https://developer.apple.com/design/human-interface-guidelines/designing-for-tvos) -- [Adding user-focusable elements to a tvOS app](https://developer.apple.com/documentation/uikit/adding-user-focusable-elements-to-a-tvos-app) -- [About focus interactions for Apple TV](https://developer.apple.com/documentation/uikit/about-focus-interactions-for-apple-tv) -- [Creating a tvOS media catalog app in SwiftUI](https://developer.apple.com/documentation/swiftui/creating-a-tvos-media-catalog-app-in-swiftui) -- [Supporting remote interactions in tvOS](https://developer.apple.com/documentation/avfoundation/supporting-remote-interactions-in-tvos) -- [TVMLKit](https://developer.apple.com/documentation/tvmlkit) -- [tvOS 26 release notes](https://developer.apple.com/documentation/tvos-release-notes/tvos-26-release-notes) -- [tvOS 27 beta release notes](https://developer.apple.com/documentation/tvos-release-notes/tvos-27-release-notes) -- [Prepare your tvOS apps for Dynamic Type](https://developer.apple.com/videos/play/wwdc2026/221/) -- [Core AI model compilation requirements](https://developer.apple.com/documentation/coreai/compiling-core-ai-models-ahead-of-time) -- [Foundation Models updates](https://developer.apple.com/documentation/updates/foundationmodels) - -## Documented Platform Contract - -### Interaction and UI - -- Apple TV interaction is indirect: people navigate with Siri Remote gestures, - a controller, voice, or companion devices instead of direct touchscreen - positioning. -- Focus is a visible navigation and selection state. UIKit’s Focus Engine - determines directional movement; apps can request reevaluation but must not - attempt to command a directional focus move. -- SwiftUI is the primary implementation path. Use its standard tvOS lockups, - focus sections, hover effects, and scroll behavior before reaching for UIKit - focus customization. -- A custom layout must give focused content room to enlarge, elevate, and cast - a shadow. Shelf clipping and rigid focus geometry are correctness problems, - not cosmetic issues. -- Full-screen content uses gestures for content interaction, rather than using - them to move an invisible focus target. Pointer-driven app navigation is not - the default tvOS pattern. -- Text entry is intentionally limited. Do not make a typing-heavy flow the only - path through a TV experience. - -### Framework and Capability Boundaries - -- TVMLKit has been deprecated since tvOS 18. Existing clients may need a - migration plan, but new apps should use SwiftUI or UIKit. -- Prefer `AVPlayerViewController` and AVKit playback UI. A custom player must - explicitly support the remote commands and media-state behaviors that the - system player supplies by default. -- `MPRemoteCommandCenter` supplements system-player behavior and becomes an - explicit responsibility for custom playback controls. -- Web views and widgets are not supported on tvOS. The Speech framework is not - available in the tvOS SDK. -- RealityKit and Metal availability varies by Apple TV GPU family. Guidance must - identify the required capability and test device rather than treating Apple - TV hardware as one uniform target. - -### tvOS 26 to tvOS 27 Beta Delta - -| Surface | tvOS 26 | tvOS 27 beta planning rule | -| --- | --- | --- | -| Design | The new design treatment does not carry to Apple TV 4K (1st generation) and older devices. | Retain hardware-generation gates and test newer 4K devices separately. | -| Text accessibility | Large Text was not a system-wide tvOS contract. | Large Text/Dynamic Type is system-wide. Use text styles, flexible constraints, and content-density changes such as fewer grid columns. | -| Background Assets | Delivery had beta-era reliability limitations that require lifecycle testing. | Localized asset packs can reduce storage use; document language-variant retrieval and fallback behavior. | -| SwiftUI images | Existing app-controlled cache behavior remains intentional. | `AsyncImage` follows HTTP cache protocols; skill guidance must call out server headers, explicit cache policy, and custom session choice. | -| Buttons | Existing asset-catalog accent assumptions may exist. | Explicitly verify tint: buttons no longer automatically use the asset-catalog accent color as label tint when built with the tvOS 27 SDK. | -| TVMLKit | Already deprecated. | Still migration-only; no new TVMLKit authoring path. | -| Core AI and Foundation Models | No documented direct tvOS runtime support. | Still no direct tvOS target in the documented Core AI hardware list or the Foundation Models version matrix; do not imply on-device model support on Apple TV. | - -The 27-beta statements are beta-specific and must be date- and SDK-qualified in -shipped guidance. Recheck each at the release candidate and GM before calling -them stable behavior. - -## Workflow Contracts - -### `tvos-app-experience-workflow` - -Use when a request is about tvOS app structure, catalog or utility UI, -remote-first navigation, focus behavior, readable large-screen layout, -accessibility, platform availability, a TVMLKit migration decision, or an -Apple-TV-specific SwiftUI/UIKit boundary. - -The workflow must: - -1. Read current Apple documentation before making platform, framework, or beta - claims, then state the documented behavior being relied on. -2. Classify the request as SwiftUI-first layout, focus routing, UIKit focus - escape hatch, accessibility/Large Text, capability gating, TVMLKit - migration, or a handoff. -3. Prefer native SwiftUI focus behavior. Escalate to `UIFocusGuide`, preferred - focus environments, or focus-update callbacks only when geometry makes the - standard path fail. -4. Keep focus, visual selection, VoiceOver order, Dynamic Type, RTL layout, - remote/controller input, and focus restoration as distinct validation - concerns. -5. Check platform restrictions before design recommendations: hardware - generation, GPU family, remote versus controller, text-entry burden, - simulator versus device-only feature, unavailable framework, and beta SDK. -6. Treat TVMLKit as an inventory-and-migration path. Do not suggest extending a - deprecated architecture for a new feature. - -It hands off to: - -- `swiftui-app-architecture-workflow` for ordinary scene, data-flow, and - component ownership once the tvOS constraints are resolved. -- `apple-ui-accessibility-workflow` for general accessibility-tree work that is - not specific to tvOS focus or Large Text. -- `tvos-media-playback-workflow` for playback and media-command ownership. -- `xcode-build-run-workflow` and `xcode-testing-workflow` for execution and - runtime verification. -- `model-lab-skills:choose-apple-model-runtime` for a genuine model-runtime - decision; the tvOS skill must report the current direct-runtime limitation. - -### `tvos-media-playback-workflow` - -Use when a tvOS experience plays media, needs remote transport behavior, uses -custom playback UI, displays supporting content in AVKit, adopts HLS or -interstitials, manages Now Playing state, or must choose between the AVKit -system player and a custom player. - -The workflow must: - -1. Start with the `AVPlayerViewController`/AVKit system-player option and name - the concrete product requirement that prevents using it before escalating. -2. Keep player state, command enablement, Now Playing metadata, and command - routing in one explicitly owned media-control surface; do not scatter remote - handlers across views. -3. Cover AVKit tabs, overlays, content proposals, HLS/interstitial behavior, - Picture in Picture where applicable, and optional Continuity Camera as - feature-specific paths rather than a generic media checklist. -4. Require an input matrix for Play/Pause, select, scrub, skip, - previous/next, Menu/Back, controller, system media controls, interruption, - and post-playback focus restoration. -5. Preserve existing `avfoundation-media-pipeline-workflow`, - `coremedia-timing-samplebuffer-workflow`, and `avfaudio-session-workflow` - ownership for general media pipelines, time/sample correctness, and audio - session policy. - -## First Implementation Slices - -1. **Evidence and contract scaffolding** - - Recheck the official source baseline in Xcode docs, Dash, release notes, - and relevant WWDC transcripts. - - Write each `SKILL.md`, its `agents/openai.yaml`, focused reference files, - and an explicit stable/beta/version-checked evidence model. - - Keep TVMLKit and direct-AI limitations in references and guards, not as a - third workflow. - -2. **App-experience workflow** - - Add focused references for focus layout, SwiftUI lockups and shelves, - UIKit escape hatches, remote/controller input, Large Text, accessibility, - hardware/framework availability, and TVMLKit migration inventory. - - Add tests for frontmatter, trigger selection, SwiftUI-first language, - user-controlled-focus guard, TVMLKit deprecation language, AI handoff, and - Xcode/testing handoffs. - -3. **Media-playback workflow** - - Add focused references for system-player preference, remote command - handling, custom-player responsibility, Now Playing state, AVKit - extensions, media validation, and device-only checks. - - Add tests for system-player-first routing, `MPRemoteCommandCenter` scope, - command-matrix coverage, and AVFoundation/Xcode handoffs. - -4. **Discovery, portability, and release readiness** - - Update the Apple Dev Skills plugin metadata, active-skill inventory, - README prompt list, child roadmap, Hermes tap export, `mcp_servers` - translation/index only when a Socket MCP declaration changes, and - Claude/Cowork compatibility records. - - Run targeted tests, `bash .github/scripts/validate_repo_docs.sh`, `uv run - pytest`, Hermes export/validation, compatibility validation, and `uv run - scripts/validate_socket_metadata.py` at the root. - - Recheck beta sources and branch accounting before the minor release. - -## Non-Goals - -- No generic “Apple TV app” framework or a new layer above SwiftUI/UIKit. -- No new TVMLKit content authoring workflow; migration guidance only. -- No promise that Core AI, Apple’s `SystemLanguageModel`, or Foundation Models - inference is available to tvOS apps. -- No release-specific beta claim without an exact version/date and a checked - source. -- No simulator-only proof for hardware-dependent GPU, controller, Continuity - Camera, or Apple TV remote behavior. - -## Release Decision - -This is a Socket minor release because it adds two installable, backward- -compatible Apple Dev Skills workflows. The release must follow the documented -standard Socket release mode, including repository/child validation, portability -exports, branch accounting, tag/release evidence, and marketplace upgrade only -after the release is published. diff --git a/plugins/agent-engineering-skills/.codex-plugin/plugin.json b/plugins/agent-engineering-skills/.codex-plugin/plugin.json index 2329d2d9c..a8da397f7 100644 --- a/plugins/agent-engineering-skills/.codex-plugin/plugin.json +++ b/plugins/agent-engineering-skills/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "agent-engineering-skills", - "version": "9.33.0", + "version": "9.34.0", "description": "Agent-system design, orchestration, scheduling, external-agent, and evaluation workflow skills.", "author": { "name": "Gale", diff --git a/plugins/agent-engineering-skills/pyproject.toml b/plugins/agent-engineering-skills/pyproject.toml index c66e5653d..70b9937c0 100644 --- a/plugins/agent-engineering-skills/pyproject.toml +++ b/plugins/agent-engineering-skills/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "agent-engineering-skills-maintenance" -version = "9.33.0" +version = "9.34.0" description = "Maintainer-only Python tooling baseline for agent-engineering-skills." requires-python = ">=3.11" dependencies = [] diff --git a/plugins/agent-engineering-skills/uv.lock b/plugins/agent-engineering-skills/uv.lock index cde448524..98ec4babd 100644 --- a/plugins/agent-engineering-skills/uv.lock +++ b/plugins/agent-engineering-skills/uv.lock @@ -4,7 +4,7 @@ requires-python = ">=3.11" [[package]] name = "agent-engineering-skills-maintenance" -version = "9.33.0" +version = "9.34.0" source = { virtual = "." } [package.dev-dependencies] diff --git a/plugins/agent-portability-skills/.codex-plugin/plugin.json b/plugins/agent-portability-skills/.codex-plugin/plugin.json index 26e13b729..7b7afa81d 100644 --- a/plugins/agent-portability-skills/.codex-plugin/plugin.json +++ b/plugins/agent-portability-skills/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "agent-portability-skills", - "version": "9.33.0", + "version": "9.34.0", "description": "Skills for agent portability, ACP, A2A, Zed, Hermes, Codex plugin surfaces, and host adapter guidance.", "author": { "name": "Gale", diff --git a/plugins/agent-portability-skills/pyproject.toml b/plugins/agent-portability-skills/pyproject.toml index 7246afa03..ae7c333ee 100644 --- a/plugins/agent-portability-skills/pyproject.toml +++ b/plugins/agent-portability-skills/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "agent-portability-skills-maintenance" -version = "9.33.0" +version = "9.34.0" description = "Maintainer-only Python tooling baseline for Agent Portability Skills." requires-python = ">=3.11" dependencies = [] diff --git a/plugins/agent-portability-skills/uv.lock b/plugins/agent-portability-skills/uv.lock index 7bd10ebf6..edec1c33d 100644 --- a/plugins/agent-portability-skills/uv.lock +++ b/plugins/agent-portability-skills/uv.lock @@ -8,7 +8,7 @@ resolution-markers = [ [[package]] name = "agent-portability-skills-maintenance" -version = "9.33.0" +version = "9.34.0" source = { virtual = "." } [package.dev-dependencies] diff --git a/plugins/agentdeck/.codex-plugin/plugin.json b/plugins/agentdeck/.codex-plugin/plugin.json index 24eba94a2..bc189ec56 100644 --- a/plugins/agentdeck/.codex-plugin/plugin.json +++ b/plugins/agentdeck/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "agentdeck", - "version": "9.33.0", + "version": "9.34.0", "description": "Local Codex runtime utilities for thread, hook, and app-server workflows.", "author": { "name": "Gale", diff --git a/plugins/android-dev-skills/.codex-plugin/plugin.json b/plugins/android-dev-skills/.codex-plugin/plugin.json index 12cf80410..61ab491a2 100644 --- a/plugins/android-dev-skills/.codex-plugin/plugin.json +++ b/plugins/android-dev-skills/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "android-dev-skills", - "version": "9.33.0", + "version": "9.34.0", "description": "Android, Kotlin, Java, Gradle, Android Gradle Plugin, testing, lint, UI implementation, and release-readiness workflow skills.", "author": { "name": "Gale", diff --git a/plugins/apple-creator-studio-skills/.codex-plugin/plugin.json b/plugins/apple-creator-studio-skills/.codex-plugin/plugin.json index 1746fee94..2ec948b52 100644 --- a/plugins/apple-creator-studio-skills/.codex-plugin/plugin.json +++ b/plugins/apple-creator-studio-skills/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "apple-creator-studio-skills", - "version": "9.33.0", + "version": "9.34.0", "description": "Human-facing and Computer Use-aware Apple Creator Studio workflows for Final Cut Pro editing, Motion templates, Compressor delivery, Logic Pro production, MainStage concert preparation, and GarageBand projects.", "author": { "name": "Gale", diff --git a/plugins/apple-dev-skills/.codex-plugin/plugin.json b/plugins/apple-dev-skills/.codex-plugin/plugin.json index 1bf8aa6bd..5497bbcf3 100644 --- a/plugins/apple-dev-skills/.codex-plugin/plugin.json +++ b/plugins/apple-dev-skills/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "apple-dev-skills", - "version": "9.33.0", + "version": "9.34.0", "description": "Apple development workflows for Codex, including macOS privacy permissions, sandbox file access, entitlement diagnosis, virtualization, SwiftPM, Xcode, app extensions, media, provisioning, SwiftUI, AppKit, Safari, security, OpenAPI, and DocC.", "author": { "name": "Gale", diff --git a/plugins/apple-dev-skills/ROADMAP.md b/plugins/apple-dev-skills/ROADMAP.md index 3b88ce974..7d4bd047b 100644 --- a/plugins/apple-dev-skills/ROADMAP.md +++ b/plugins/apple-dev-skills/ROADMAP.md @@ -798,7 +798,7 @@ Completed ### Tickets -- [x] Use [the DeviceCheck and App Attest skill plan](../../docs/maintainers/devicecheck-app-attest-skill-plan.md) as the implementation source of truth. +- [x] Ship `devicecheck-app-attest-workflow` as the source of truth for DeviceCheck and App Attest guidance. - [x] Add `devicecheck-app-attest-workflow` with clear routing between DeviceCheck two-bit state, App Attest app-instance integrity, broader client auth, and server-side validation implementation. - [x] Add references for DeviceCheck device state, App Attest client flow, App Attest server validation, App ID and entitlement setup, sandbox/production behavior, rollout/rate-limit planning, and macOS-specific validation notes. - [x] Add skill interface metadata and update Apple Dev Skills plugin metadata, README active skill inventory, and default prompt list. @@ -1368,11 +1368,11 @@ Completed Milestone 69 by shipping privacy-permission, sandbox file-access, and ### Status -In Progress +Completed ### Scope -- [x] Use the Socket-owned [`tvOS Skills Plan`](../../docs/maintainers/tvos-skills-plan.md) as the implementation source of truth. +- [x] Ship the focused `tvos-app-experience-workflow` and `tvos-media-playback-workflow` as the source of truth for tvOS guidance. - [x] Add `tvos-app-experience-workflow` for remote-first layout, SwiftUI focus behavior, UIKit focus escape hatches, Large Text, accessibility, capability gates, and TVMLKit migration decisions. - [x] Add `tvos-media-playback-workflow` for AVKit-first playback, custom-player escalation, `MPRemoteCommandCenter`, Now Playing, transport-command ownership, and validation planning. - [x] Keep TVMLKit migration-only, and keep Core AI/Foundation Models as an explicit unavailable-on-tvos handoff until Apple supplies a direct platform contract. diff --git a/plugins/apple-dev-skills/pyproject.toml b/plugins/apple-dev-skills/pyproject.toml index c8bd5e167..87bf88352 100644 --- a/plugins/apple-dev-skills/pyproject.toml +++ b/plugins/apple-dev-skills/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "apple-dev-skills-maintainer" -version = "9.33.0" +version = "9.34.0" description = "Maintainer tooling for the apple-dev-skills repository" requires-python = ">=3.10" dependencies = [] diff --git a/plugins/apple-dev-skills/uv.lock b/plugins/apple-dev-skills/uv.lock index 54d42c0c2..19c705501 100644 --- a/plugins/apple-dev-skills/uv.lock +++ b/plugins/apple-dev-skills/uv.lock @@ -4,7 +4,7 @@ requires-python = ">=3.10" [[package]] name = "apple-dev-skills-maintainer" -version = "9.33.0" +version = "9.34.0" source = { virtual = "." } [package.dev-dependencies] diff --git a/plugins/cardhop-app/.codex-plugin/plugin.json b/plugins/cardhop-app/.codex-plugin/plugin.json index 347108812..a58369cf0 100644 --- a/plugins/cardhop-app/.codex-plugin/plugin.json +++ b/plugins/cardhop-app/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "cardhop-app", - "version": "9.33.0", + "version": "9.34.0", "description": "Cardhop.app workflow guidance plus a bundled local MCP server for contact capture and updates on macOS.", "author": { "name": "Gale", diff --git a/plugins/cardhop-app/mcp/pyproject.toml b/plugins/cardhop-app/mcp/pyproject.toml index dbddd8c71..ab5585e30 100644 --- a/plugins/cardhop-app/mcp/pyproject.toml +++ b/plugins/cardhop-app/mcp/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "cardhop-app-mcp" -version = "9.33.0" +version = "9.34.0" requires-python = ">=3.13" dependencies = [ "fastmcp>=3.0.2", diff --git a/plugins/cardhop-app/mcp/uv.lock b/plugins/cardhop-app/mcp/uv.lock index 22c214bcc..5f042f0f8 100644 --- a/plugins/cardhop-app/mcp/uv.lock +++ b/plugins/cardhop-app/mcp/uv.lock @@ -141,7 +141,7 @@ wheels = [ [[package]] name = "cardhop-app-mcp" -version = "9.33.0" +version = "9.34.0" source = { virtual = "." } dependencies = [ { name = "fastmcp" }, diff --git a/plugins/cloud-deployment-skills/.codex-plugin/plugin.json b/plugins/cloud-deployment-skills/.codex-plugin/plugin.json index a7145ec72..dce8780ec 100644 --- a/plugins/cloud-deployment-skills/.codex-plugin/plugin.json +++ b/plugins/cloud-deployment-skills/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "cloud-deployment-skills", - "version": "9.33.0", + "version": "9.34.0", "description": "Codex skills for routing cloud deployment work through official provider plugins, MCP servers, CLIs, and a reusable Dockerized-service release and deployment contract.", "author": { "name": "Gale", diff --git a/plugins/cloud-inference-skills/.codex-plugin/plugin.json b/plugins/cloud-inference-skills/.codex-plugin/plugin.json index e52fbe635..e2bb64fb2 100644 --- a/plugins/cloud-inference-skills/.codex-plugin/plugin.json +++ b/plugins/cloud-inference-skills/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "cloud-inference-skills", - "version": "9.33.0", + "version": "9.34.0", "description": "Cloud AI inference workflow skills for routing model serving, training, conversion, and GPU infrastructure work across Runpod, Hugging Face, AWS, Vast.ai, CoreWeave, and similar providers.", "author": { "name": "Gale", diff --git a/plugins/codebase-understanding-skills/.codex-plugin/plugin.json b/plugins/codebase-understanding-skills/.codex-plugin/plugin.json index 8ea1e8ace..420e1cd70 100644 --- a/plugins/codebase-understanding-skills/.codex-plugin/plugin.json +++ b/plugins/codebase-understanding-skills/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "codebase-understanding-skills", - "version": "9.33.0", + "version": "9.34.0", "description": "Code-path exploration, call-site tracing, and evidence-based codebase explanation skills.", "author": { "name": "Gale", diff --git a/plugins/cybersecurity-skills/.codex-plugin/plugin.json b/plugins/cybersecurity-skills/.codex-plugin/plugin.json index c7ccf157b..523b2c88f 100644 --- a/plugins/cybersecurity-skills/.codex-plugin/plugin.json +++ b/plugins/cybersecurity-skills/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "cybersecurity-skills", - "version": "9.33.0", + "version": "9.34.0", "description": "Defensive cybersecurity, isolated Linux and macOS analysis labs, suspicious-content and malware analysis, macOS defense, vulnerability testing, pentesting, and incident response workflows.", "skills": "./skills/", "author": { diff --git a/plugins/documentation-skills/.codex-plugin/plugin.json b/plugins/documentation-skills/.codex-plugin/plugin.json index b5654d18e..f0e2d154e 100644 --- a/plugins/documentation-skills/.codex-plugin/plugin.json +++ b/plugins/documentation-skills/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "documentation-skills", - "version": "9.33.0", + "version": "9.34.0", "description": "Documentation maintenance skills for README, contributor, agent, API, accessibility, architecture, and roadmap surfaces.", "author": { "name": "Gale", diff --git a/plugins/documentation-skills/pyproject.toml b/plugins/documentation-skills/pyproject.toml index c183df386..be8284945 100644 --- a/plugins/documentation-skills/pyproject.toml +++ b/plugins/documentation-skills/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "documentation-skills-maintenance" -version = "9.33.0" +version = "9.34.0" description = "Maintainer-only Python tooling baseline for documentation-skills." requires-python = ">=3.11" dependencies = [] diff --git a/plugins/documentation-skills/uv.lock b/plugins/documentation-skills/uv.lock index eb4039efc..21218e066 100644 --- a/plugins/documentation-skills/uv.lock +++ b/plugins/documentation-skills/uv.lock @@ -57,7 +57,7 @@ wheels = [ [[package]] name = "documentation-skills-maintenance" -version = "9.33.0" +version = "9.34.0" source = { virtual = "." } [package.dev-dependencies] diff --git a/plugins/dotnet-skills/.codex-plugin/plugin.json b/plugins/dotnet-skills/.codex-plugin/plugin.json index 7ef04c364..4a5aee0db 100644 --- a/plugins/dotnet-skills/.codex-plugin/plugin.json +++ b/plugins/dotnet-skills/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "dotnet-skills", - "version": "9.33.0", + "version": "9.34.0", "description": "Codex skills for choosing, bootstrapping, building, testing, packaging, diagnosing, and maintaining .NET projects, including F# web applications, with F# and C# as equal first-party languages.", "author": { "name": "Gale", diff --git a/plugins/game-dev-skills/.codex-plugin/plugin.json b/plugins/game-dev-skills/.codex-plugin/plugin.json index eea8fe6fe..444db4fc5 100644 --- a/plugins/game-dev-skills/.codex-plugin/plugin.json +++ b/plugins/game-dev-skills/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "game-dev-skills", - "version": "9.33.0", + "version": "9.34.0", "description": "Apple platform game development workflow skills for native Metal rendering, Game Porting Toolkit routing, MetalFX, GPU asset streaming, neural rendering, frameworks, input, haptics, and profiling.", "author": { "name": "Gale", diff --git a/plugins/messaging-collaboration-skills/.codex-plugin/plugin.json b/plugins/messaging-collaboration-skills/.codex-plugin/plugin.json index f7fb41887..ab459717c 100644 --- a/plugins/messaging-collaboration-skills/.codex-plugin/plugin.json +++ b/plugins/messaging-collaboration-skills/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "messaging-collaboration-skills", - "version": "9.33.0", + "version": "9.34.0", "description": "Codex workflows for chat apps, bots, collaboration, iMessage, Apple notifications and Push to Talk, VoIP, and default communication-app planning.", "author": { "name": "Gale", diff --git a/plugins/model-lab-skills/.codex-plugin/plugin.json b/plugins/model-lab-skills/.codex-plugin/plugin.json index f26b2b41d..0ee620285 100644 --- a/plugins/model-lab-skills/.codex-plugin/plugin.json +++ b/plugins/model-lab-skills/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "model-lab-skills", - "version": "9.33.0", + "version": "9.34.0", "description": "Reproducible model training, evaluation, intervention, and runtime research workflows.", "author": { "name": "Gale" diff --git a/plugins/network-protocol-skills/.codex-plugin/plugin.json b/plugins/network-protocol-skills/.codex-plugin/plugin.json index a26332228..531f1e78f 100644 --- a/plugins/network-protocol-skills/.codex-plugin/plugin.json +++ b/plugins/network-protocol-skills/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "network-protocol-skills", - "version": "9.33.0", + "version": "9.34.0", "description": "Codex skills for choosing, planning, implementing, and diagnosing modern application transports and real-time networking protocols, including QUIC, HTTP/3, WebRTC, Media over QUIC, WebTransport-adjacent handoffs, protocol maturity checks, and stack-specific implementation routing.", "author": { "name": "Gale", diff --git a/plugins/professional-skills/.codex-plugin/plugin.json b/plugins/professional-skills/.codex-plugin/plugin.json index 77d75eaba..f628ce49d 100644 --- a/plugins/professional-skills/.codex-plugin/plugin.json +++ b/plugins/professional-skills/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "professional-skills", - "version": "9.33.0", + "version": "9.34.0", "description": "Professional workflow skills for job search, career materials, and external professional services.", "author": { "name": "Gale", diff --git a/plugins/professional-skills/pyproject.toml b/plugins/professional-skills/pyproject.toml index 76a9c0920..125f6f75f 100644 --- a/plugins/professional-skills/pyproject.toml +++ b/plugins/professional-skills/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "professional-skills-maintenance" -version = "9.33.0" +version = "9.34.0" description = "Maintainer-only Python tooling baseline for professional-skills." requires-python = ">=3.11" dependencies = [] diff --git a/plugins/professional-skills/uv.lock b/plugins/professional-skills/uv.lock index aefc43013..0080eb6c7 100644 --- a/plugins/professional-skills/uv.lock +++ b/plugins/professional-skills/uv.lock @@ -40,7 +40,7 @@ wheels = [ [[package]] name = "professional-skills-maintenance" -version = "9.33.0" +version = "9.34.0" source = { virtual = "." } [package.dev-dependencies] diff --git a/plugins/python-skills/.codex-plugin/plugin.json b/plugins/python-skills/.codex-plugin/plugin.json index bc4fdbbe0..f436ad3de 100644 --- a/plugins/python-skills/.codex-plugin/plugin.json +++ b/plugins/python-skills/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "python-skills", - "version": "9.33.0", + "version": "9.34.0", "description": "Bundled Python-focused Codex skills for uv bootstrapping, project implementation, diagnostics, packaging, tooling, CI, upgrades, FastAPI service maintenance, FastMCP service maintenance, and testing workflows.", "author": { "name": "Gale", diff --git a/plugins/python-skills/pyproject.toml b/plugins/python-skills/pyproject.toml index 5fe27ee01..8549db64c 100644 --- a/plugins/python-skills/pyproject.toml +++ b/plugins/python-skills/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "python-skills-maintainer" -version = "9.33.0" +version = "9.34.0" description = "Maintainer tooling for the python-skills repository" requires-python = ">=3.11" dependencies = [] diff --git a/plugins/python-skills/uv.lock b/plugins/python-skills/uv.lock index 579ebdb2c..0ffd99bb4 100644 --- a/plugins/python-skills/uv.lock +++ b/plugins/python-skills/uv.lock @@ -251,7 +251,7 @@ wheels = [ [[package]] name = "python-skills-maintainer" -version = "9.33.0" +version = "9.34.0" source = { virtual = "." } [package.dev-dependencies] diff --git a/plugins/repository-skills/.codex-plugin/plugin.json b/plugins/repository-skills/.codex-plugin/plugin.json index 97d0daaef..9b27adac7 100644 --- a/plugins/repository-skills/.codex-plugin/plugin.json +++ b/plugins/repository-skills/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "repository-skills", - "version": "9.33.0", + "version": "9.34.0", "description": "Repository operations, GitHub settings, worktree, validation, and release workflow skills.", "author": { "name": "Gale", diff --git a/plugins/repository-skills/pyproject.toml b/plugins/repository-skills/pyproject.toml index 4fe369886..af753682f 100644 --- a/plugins/repository-skills/pyproject.toml +++ b/plugins/repository-skills/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "repository-skills-maintenance" -version = "9.33.0" +version = "9.34.0" description = "Maintainer-only Python tooling baseline for repository-skills." requires-python = ">=3.11" dependencies = [] diff --git a/plugins/repository-skills/skills/maintain-project-repo/tests/test_maintain_project_repo_workflow.py b/plugins/repository-skills/skills/maintain-project-repo/tests/test_maintain_project_repo_workflow.py index 0519e9d97..544b60b30 100644 --- a/plugins/repository-skills/skills/maintain-project-repo/tests/test_maintain_project_repo_workflow.py +++ b/plugins/repository-skills/skills/maintain-project-repo/tests/test_maintain_project_repo_workflow.py @@ -398,22 +398,31 @@ def test_release_guidance_reuses_healthy_pending_continuations(self) -> None: self.assertIn("pending and healthy", text) self.assertIn("do not delete/recreate", text) - def test_continuation_plan_matches_emitted_packet_schema(self) -> None: - socket_root = ROOT.parents[1] - plan = (socket_root / "docs/maintainers/deferred-work-wakeup-policy-plan.md").read_text( - encoding="utf-8" + def test_continuation_policy_matches_emitted_packet_schema(self) -> None: + socket_root = ( + ROOT + if (ROOT / "docs/maintainers/deferred-work-wakeup-policy.md").is_file() + else ROOT.parents[1] ) - self.assertIn('"minimum_delay_minutes": 5', plan) - self.assertIn('"pr_number": "123"', plan) - self.assertNotIn('"not_before"', plan) - self.assertNotIn('"observed_at"', plan) - self.assertIn("Superseded by the live", plan) - live_policy = (socket_root / "docs/maintainers/deferred-work-wakeup-policy.md").read_text( encoding="utf-8" ) self.assertIn("Reuse that item unchanged", live_policy) self.assertIn("minimum delay is five minutes", live_policy) + for field in ( + "repository", + "release tag", + "branch", + "head commit", + "PR number", + "phase", + "minimum_delay_minutes", + "resume/advance commands", + ): + with self.subTest(field=field): + self.assertIn(field, live_policy) + self.assertIn("Pre-PR packets resume with `prepare`", live_policy) + self.assertIn("post-PR\npackets resume with `inspect`", live_policy) def test_branch_accounting_guidance_is_documented(self) -> None: skill_text = (ROOT / "skills/maintain-project-repo/SKILL.md").read_text(encoding="utf-8") diff --git a/plugins/repository-skills/uv.lock b/plugins/repository-skills/uv.lock index bdf7831b0..2a360c03d 100644 --- a/plugins/repository-skills/uv.lock +++ b/plugins/repository-skills/uv.lock @@ -310,7 +310,7 @@ wheels = [ [[package]] name = "repository-skills-maintenance" -version = "9.33.0" +version = "9.34.0" source = { virtual = "." } [package.dev-dependencies] diff --git a/plugins/reverse-engineering-skills/.codex-plugin/plugin.json b/plugins/reverse-engineering-skills/.codex-plugin/plugin.json index 14b607f5f..cdf24a57d 100644 --- a/plugins/reverse-engineering-skills/.codex-plugin/plugin.json +++ b/plugins/reverse-engineering-skills/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "reverse-engineering-skills", - "version": "9.33.0", + "version": "9.34.0", "description": "Workflow skills for reverse engineering, decompilation, disassembly, symbols, artifact analysis, and exact-build macOS security-control research.", "skills": "./skills/", "author": { diff --git a/plugins/rust-skills/.codex-plugin/plugin.json b/plugins/rust-skills/.codex-plugin/plugin.json index e6843022e..4b96375c4 100644 --- a/plugins/rust-skills/.codex-plugin/plugin.json +++ b/plugins/rust-skills/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "rust-skills", - "version": "9.33.0", + "version": "9.34.0", "description": "Rust, Cargo, rustup, crate, workspace, CLI, library, package, CI, testing, linting, and formatting workflow skills.", "skills": "./skills/", "author": { diff --git a/plugins/server-side-jvm/.codex-plugin/plugin.json b/plugins/server-side-jvm/.codex-plugin/plugin.json index 76e5363dd..cc2fb9769 100644 --- a/plugins/server-side-jvm/.codex-plugin/plugin.json +++ b/plugins/server-side-jvm/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "server-side-jvm", - "version": "9.33.0", + "version": "9.34.0", "description": "Codex skills for choosing, building, testing, and maintaining server-side JVM backend projects with Java and Scala as equal first-party languages and future Clojure support planned.", "author": { "name": "Gale", diff --git a/plugins/server-side-swift/.codex-plugin/plugin.json b/plugins/server-side-swift/.codex-plugin/plugin.json index 65f606c3c..fbc6306ce 100644 --- a/plugins/server-side-swift/.codex-plugin/plugin.json +++ b/plugins/server-side-swift/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "server-side-swift", - "version": "9.33.0", + "version": "9.34.0", "description": "Codex skills for bootstrapping, syncing, building, running, containerizing, deploying, and maintaining server-side Swift services, including Vapor, Leaf-rendered web and HTML email, Hummingbird, hb, persistence, Swift OpenAPI, RPC-fit decisions, SwiftNIO, observability, auth, app sync, Docker, Apple Containerization, Fly.io, and SwiftPM-first workflows.", "author": { "name": "Gale", diff --git a/plugins/spotify/.codex-plugin/plugin.json b/plugins/spotify/.codex-plugin/plugin.json index 259dc9f8f..b2e602c63 100644 --- a/plugins/spotify/.codex-plugin/plugin.json +++ b/plugins/spotify/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "spotify", - "version": "9.33.0", + "version": "9.34.0", "description": "Placeholder plugin repository for future Spotify-focused Codex workflows.", "author": { "name": "Gale", diff --git a/plugins/swift-lang/.codex-plugin/plugin.json b/plugins/swift-lang/.codex-plugin/plugin.json index a2130ec62..6f8950778 100644 --- a/plugins/swift-lang/.codex-plugin/plugin.json +++ b/plugins/swift-lang/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "swift-lang", - "version": "9.33.0", + "version": "9.34.0", "description": "Shared Swift language and tooling skills for API style, errors, functional pipelines, formatting, source organization, SwiftSyntax, compiler inspection, SourceKit, indexing, SourceKit-LSP, and modernization.", "skills": "./skills/", "author": { diff --git a/plugins/swiftasb-skills/.codex-plugin/plugin.json b/plugins/swiftasb-skills/.codex-plugin/plugin.json index 8dad45555..c2ca00ceb 100644 --- a/plugins/swiftasb-skills/.codex-plugin/plugin.json +++ b/plugins/swiftasb-skills/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "swiftasb-skills", - "version": "9.33.0", + "version": "9.34.0", "description": "Codex skills for explaining SwiftASB and building SwiftUI, AppKit, and Swift package integrations on top of it.", "author": { "name": "Gale", diff --git a/plugins/things-app/.codex-plugin/plugin.json b/plugins/things-app/.codex-plugin/plugin.json index 77d658553..502355a03 100644 --- a/plugins/things-app/.codex-plugin/plugin.json +++ b/plugins/things-app/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "things-app", - "version": "9.33.0", + "version": "9.34.0", "description": "Things.app skills and a bundled local MCP server for reminders, planning digests, and structured task workflows.", "author": { "name": "Gale", diff --git a/plugins/things-app/mcp/pyproject.toml b/plugins/things-app/mcp/pyproject.toml index 7760cfdb3..756af6bc1 100644 --- a/plugins/things-app/mcp/pyproject.toml +++ b/plugins/things-app/mcp/pyproject.toml @@ -7,7 +7,7 @@ packages = ["app"] [project] name = "things-mcp" -version = "9.33.0" +version = "9.34.0" requires-python = ">=3.13" dependencies = [ "fastmcp>=3.0.2", diff --git a/plugins/things-app/mcp/uv.lock b/plugins/things-app/mcp/uv.lock index 52165786f..c141df5cd 100644 --- a/plugins/things-app/mcp/uv.lock +++ b/plugins/things-app/mcp/uv.lock @@ -1244,7 +1244,7 @@ wheels = [ [[package]] name = "things-mcp" -version = "9.33.0" +version = "9.34.0" source = { editable = "." } dependencies = [ { name = "fastmcp" }, diff --git a/plugins/things-app/pyproject.toml b/plugins/things-app/pyproject.toml index d863a72d3..989a85f7d 100644 --- a/plugins/things-app/pyproject.toml +++ b/plugins/things-app/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "things-app-maintenance" -version = "9.33.0" +version = "9.34.0" description = "Maintainer-only Python tooling baseline for things-app skills and plugin packaging." requires-python = ">=3.11" dependencies = [] diff --git a/plugins/things-app/uv.lock b/plugins/things-app/uv.lock index 98bbd8926..59d3cab3f 100644 --- a/plugins/things-app/uv.lock +++ b/plugins/things-app/uv.lock @@ -120,7 +120,7 @@ wheels = [ [[package]] name = "things-app-maintenance" -version = "9.33.0" +version = "9.34.0" source = { virtual = "." } [package.dev-dependencies] diff --git a/plugins/web-dev-skills/.codex-plugin/plugin.json b/plugins/web-dev-skills/.codex-plugin/plugin.json index 512ef52b8..c88f3fceb 100644 --- a/plugins/web-dev-skills/.codex-plugin/plugin.json +++ b/plugins/web-dev-skills/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "web-dev-skills", - "version": "9.33.0", + "version": "9.34.0", "description": "Codex skills for focused web and Expo native-boundary workflows.", "author": { "name": "Gale", diff --git a/pyproject.toml b/pyproject.toml index de0987716..f7a9edffd 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "socket-maintenance" -version = "9.33.0" +version = "9.34.0" description = "Root uv tooling baseline for the socket superproject." requires-python = ">=3.11" dependencies = [] diff --git a/skills/maintain-project-repo/tests/test_maintain_project_repo_workflow.py b/skills/maintain-project-repo/tests/test_maintain_project_repo_workflow.py index 0519e9d97..544b60b30 100644 --- a/skills/maintain-project-repo/tests/test_maintain_project_repo_workflow.py +++ b/skills/maintain-project-repo/tests/test_maintain_project_repo_workflow.py @@ -398,22 +398,31 @@ def test_release_guidance_reuses_healthy_pending_continuations(self) -> None: self.assertIn("pending and healthy", text) self.assertIn("do not delete/recreate", text) - def test_continuation_plan_matches_emitted_packet_schema(self) -> None: - socket_root = ROOT.parents[1] - plan = (socket_root / "docs/maintainers/deferred-work-wakeup-policy-plan.md").read_text( - encoding="utf-8" + def test_continuation_policy_matches_emitted_packet_schema(self) -> None: + socket_root = ( + ROOT + if (ROOT / "docs/maintainers/deferred-work-wakeup-policy.md").is_file() + else ROOT.parents[1] ) - self.assertIn('"minimum_delay_minutes": 5', plan) - self.assertIn('"pr_number": "123"', plan) - self.assertNotIn('"not_before"', plan) - self.assertNotIn('"observed_at"', plan) - self.assertIn("Superseded by the live", plan) - live_policy = (socket_root / "docs/maintainers/deferred-work-wakeup-policy.md").read_text( encoding="utf-8" ) self.assertIn("Reuse that item unchanged", live_policy) self.assertIn("minimum delay is five minutes", live_policy) + for field in ( + "repository", + "release tag", + "branch", + "head commit", + "PR number", + "phase", + "minimum_delay_minutes", + "resume/advance commands", + ): + with self.subTest(field=field): + self.assertIn(field, live_policy) + self.assertIn("Pre-PR packets resume with `prepare`", live_policy) + self.assertIn("post-PR\npackets resume with `inspect`", live_policy) def test_branch_accounting_guidance_is_documented(self) -> None: skill_text = (ROOT / "skills/maintain-project-repo/SKILL.md").read_text(encoding="utf-8") diff --git a/uv.lock b/uv.lock index 59ff42730..a297d3292 100644 --- a/uv.lock +++ b/uv.lock @@ -286,7 +286,7 @@ wheels = [ [[package]] name = "socket-maintenance" -version = "9.33.0" +version = "9.34.0" source = { virtual = "." } [package.dev-dependencies]