docs: enforce media types and worktree workflow

[gaelic-ghost]

Summary

• make Socket implementation worktree-first while keeping main as the clean coordination and release-verification checkout
• add a shared Apple media type ownership contract for AVFoundation, AVFAudio, Core Media, Core Audio, and Audio Toolbox
• bump the shared Socket version to 7.4.0 for the requested minor release

Verification

• uv run --directory plugins/apple-dev-skills pytest tests/test_media_audio_workflows.py
• bash .github/scripts/validate_repo_docs.sh
• uv run pytest
• uv run scripts/validate_socket_metadata.py

Summary by CodeRabbit

• New Features

  • Added clearer guidance for working with Apple media, audio, and timing concepts across related workflows.
  • Expanded the shared reference material for choosing the right Apple framework types and preserving type-safe boundaries.

• Documentation

  • Updated contributor, maintainer, and roadmap docs to favor branch-based worktrees and keep the main checkout clean.
  • Refined plugin descriptions and usage notes for stricter media type selection.

• Tests

  • Added coverage to verify the new Apple media type ownership guidance.

• Chores

  • Bumped the release version across the project and plugins to 7.4.0.

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

Introduces a shared apple-media-type-ownership.md reference contract for Apple media frameworks and propagates it across five apple-dev-skills workflows (AVAudio engine, AVFAudio session, AVFoundation pipeline, Core Audio modernization, Core Media timing). Repo workflow policy is updated to make branch-backed worktrees the default implementation surface. All plugins are bumped from version 7.3.1 to 7.4.0.

Changes

Apple Media Type Ownership Contract

Layer / File(s)	Summary
Shared Apple media type ownership reference plugins/apple-dev-skills/shared/references/apple-media-type-ownership.md	New document defining default Apple type choices, framework selection guidance, escape-hatch rules, and review checks across all five media/audio workflows.
AVAudio engine workflow integration plugins/apple-dev-skills/skills/avaudio-engine-workflow/SKILL.md, plugins/apple-dev-skills/skills/avaudio-engine-workflow/references/engine-graph-and-repair.md	SKILL.md updated to reference the shared contract in purpose, workflow steps, repair modes, inputs, and guards; reference doc gains a Type ownership subsection.
AVFAudio session workflow integration plugins/apple-dev-skills/skills/avfaudio-session-workflow/SKILL.md, plugins/apple-dev-skills/skills/avfaudio-session-workflow/references/session-policy-and-repair.md	SKILL.md gates on the shared contract before string-backed policy models; reference doc gains a Type ownership subsection for audio policy/route/permission surfaces.
AVFoundation media pipeline workflow integration plugins/apple-dev-skills/skills/avfoundation-media-pipeline-workflow/SKILL.md, plugins/apple-dev-skills/skills/avfoundation-media-pipeline-workflow/references/...	SKILL.md adds shared contract gates, repair bullets, and guards; async-loading and media-pipeline reference docs gain Type ownership and repair checklist additions.
Core Audio modernization workflow integration plugins/apple-dev-skills/skills/coreaudio-modernization-repair-workflow/SKILL.md, plugins/apple-dev-skills/skills/coreaudio-modernization-repair-workflow/references/...	SKILL.md adopts ownership/escape-hatch framing; reference docs gain Framework choice, Type ownership, and legacy-archive boundary constraints.
Core Media timing/sample-buffer workflow integration plugins/apple-dev-skills/skills/coremedia-timing-samplebuffer-workflow/SKILL.md, plugins/apple-dev-skills/skills/coremedia-timing-samplebuffer-workflow/references/...	SKILL.md gains shared contract gates and strengthened guards; reference docs add Type ownership checklists and typed diagnostics guidance.
apple-dev-skills plugin metadata, docs, and tests plugins/apple-dev-skills/.codex-plugin/plugin.json, plugins/apple-dev-skills/AGENTS.md, plugins/apple-dev-skills/README.md, plugins/apple-dev-skills/ROADMAP.md, plugins/apple-dev-skills/pyproject.toml, plugins/apple-dev-skills/tests/test_media_audio_workflows.py	plugin.json longDescription updated; AGENTS.md, README, and ROADMAP gain media type ownership notes; test fixtures expanded and test_shared_media_type_ownership_contract_is_strict added.

Worktree-first Workflow Policy

Layer / File(s)	Summary
Worktree-first policy across repo docs AGENTS.md, CONTRIBUTING.md, ROADMAP.md, docs/maintainers/release-modes.md, docs/maintainers/subtree-workflow.md	Establishes main as a clean coordination/release-verification checkout, makes branch-backed worktrees the default implementation surface, restricts direct-main work to explicit cases, and records the policy change in history.

Version Bump 7.3.1 → 7.4.0

Layer / File(s)	Summary
All plugin manifests and pyproject.toml pyproject.toml, plugins/*/.codex-plugin/plugin.json, plugins/*/pyproject.toml	Version field bumped from 7.3.1 to 7.4.0 across root and all plugins.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• gaelic-ghost/socket#51: Also edits plugins/apple-dev-skills plugin.json interface.longDescription and README to expand skill scope descriptions.
• gaelic-ghost/socket#89: Touches plugins/android-dev-skills/.codex-plugin/plugin.json version and plugin catalog, same manifest field bumped here.
• gaelic-ghost/socket#62: Bumps plugins/server-side-swift/.codex-plugin/plugin.json version, same pattern as this PR's version bump cohort.

Suggested labels

enhancement

🐇 A contract for types, crisp and clear,
AVFoundation kept near and dear.
No raw strings shall pass the gate,
CMTime holds its form straight.
Worktrees first, and main stays clean —
The tidiest repo this hare has seen! 🎉

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately reflects the main documentation changes around media types and the worktree-first workflow.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/apple-media-worktree-policy

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}