Auto-ship CodeCaps for Mac to TestFlight on every merge (CC-165)

[jaywedgeworth22]

Refs CC-165.  Sibling of CC-163 (PR 253, the iOS companion).
| 489ab54 PiP dragging and logos (#250) | ios/CodeCapsCompanion/App/Models/CompanionQuotaModel.swift and 30 more | never | triggers |
| 7111f49 Wait for Swift CI before TestFlight ships (#245) | .github/workflows/macos-ship.yml | never | triggers |
| b3fc6bb Muse bars and logo cache (#242) | Sources/QuotaCore/QuotaWindowVocabulary.swift | never | triggers |
| 6a89804 QuotaCore window vocabulary (#226) | Sources/QuotaCore/QuotaWindowVocabulary.swift | never | triggers |

• AFC PR (same CC-165): the freshness registry row for codecaps-mac flips to autoRemedy, so the deploy check also dispatches this workflow when the Mac build falls behind.

Summary

Enables automatic TestFlight shipping for CodeCaps for Mac: a merge to main that touches the Mac app's native tree now archives and uploads a build with no human step and publishes "What to Test". Previously macos-ship.yml was workflow_dispatch only, so merges never reached TestFlight and the Mac build remained at the retired 0.1.N train.

What changed

.github/workflows/macos-ship.yml

• Adds a push trigger on main scoped to the Mac native tree: ios/CodeCapsCompanion/**, the eight exact Sources/QuotaCore files the CodeCapsCompanionMac/CodeCapsWidgetsMac targets compile (explicit files, not a directory wildcard, so unrelated QuotaCore edits do not ship), the workflow itself, the Infisical action/script, scripts/ios-fleet/** (test scripts excluded), and the Mac ship/signing scripts.
• Adds a twice-hourly schedule tick (11,41 * * * *) to catch merges that GitHub's recursion guard does not announce as push runs.
• Splits the previous single wait job into a gate job (ubuntu) that restores ship state, runs scheduled-ship-gate.sh with --event and matching path prefixes for app key codecaps-mac, exposes should_ship, and only then waits for Swift CI compile checks. The Mac runner starts only when the commit should ship and has compiled.
• ship now requires gate success and should_ship == '1'; fetch-depth: 0 is used for both checkouts.
• Sets cancel-in-progress: false so a later push queues behind an in-flight upload instead of cancelling it mid-archive.
• Credentials: App Store Connect key is now loaded from Fleet-OPS Infisical prod /asc via universal auth; ASC_KEY_ID/ASC_ISSUER_ID go to GITHUB_ENV, and the multiline key is staged to a mode-600 file by scripts/ios-stage-asc-key.sh, exposing only ASC_KEY_PATH. The stale same-named repository ASC_* secrets are no longer read. IOS_DIST_P12_* and MAC_INSTALLER_P12_* remain repository secrets, scoped to the signing-import step.
• Ship-state cache key family is renamed to ios-fleet-state-codecaps-mac-v1- in both gate and ship, so the retired 0.1.N build sequence cannot carry over.
• Cleanup step also removes the staged ASC key directory.

scripts/mac-appstore-gm-prepare.sh

• Disables xtrace and sets umask 077.
• Accepts ASC_KEY_PATH (pre-staged key file) as the primary input, retaining ASC_KEY_P8 for local legacy callers; validates the staged file exists.
• Deletes the imported .p12 files from disk after the keychain import.

Contract tests

• New scripts/macos-ship-workflow.test.mjs pins the whole wiring: push/schedule triggers, gate prefixes derived from and cross-checked against project.yml compiled sources, parity with ios-ship.yml's shared-file list, exclusion of the separate SwiftPM/Sparkle tree and test-only changes, credential sourcing with no stale-secret reads, absence of gate overrides/force-ship, cache key family, 1.0.N marketing train and codecaps-mac app config, and the Mac profile map bundle IDs.
• .github/workflows/ios-ship-contract.yml now also runs the Mac contract test and triggers on scripts/mac-*, the new test, and mac-appstore-profiles.json.

Docs

• Adds a "CodeCaps For Mac (TestFlight)" section to docs/IOS-TESTFLIGHT.md covering what builds, what triggers it, credentials, version train, gates, and how to diagnose a missing build.

Functional impact

Mac TestFlight builds ship automatically from main, use the same centrally managed ASC key as the iOS ship, are pinned to the 1.0.N version train, and cannot silently regress to manual-only without failing the iOS ship contract check.

Review findings to address

• Critical: the Fleet-OPS Infisical project UUID is hardcoded in the public workflow (.github/workflows/macos-ship.yml:224) rather than sourced from a repository secret.
• High: the new documentation section leaks a local operational path (~/apps/ios-fleet/...) in a public doc (docs/IOS-TESTFLIGHT.md:43).
• Medium: task description is insufficient for business-logic validation.

---

Summary

Updates the CodeCaps iOS/Mac TestFlight runbook (docs/IOS-TESTFLIGHT.md) so the "When a Mac build is missing" guidance no longer includes a leaked operational invocation. The step now points readers to the fleet's TestFlight freshness check for codecaps-mac and describes what its verdict means, instead of embedding a full local path, script name, runtime, and command-line flag.

Changes

• docs/IOS-TESTFLIGHT.md — Mac build troubleshooting step
  • Replaced the hard-coded local command (node ~/apps/ios-fleet/ios_testflight_freshness.mjs --app codecaps-mac) with a reference to running the fleet's TestFlight freshness check for codecaps-mac.
  • Added a description of the check's outcome: its verdict indicates whether the newest processed build contains the newest native commit.

Impact

• Documentation-only change; no runtime or build behavior is affected.
• Removes environment-specific details (absolute path, script filename, Node runtime, CLI flag) from the published runbook while keeping the troubleshooting instruction actionable.
• The documented workflow for diagnosing a missing Mac TestFlight build remains intact: verify the workflow is active, confirm a recent main push run exists, treat a failed ASC credential load as an Infisical owner fix, then run the freshness check.

Review Notes

• One low-severity finding was reported, noting that this documentation rewrite removes the leaked operational path, script, runtime, and invocation flag from the runbook.

[linear-code]

CC-165

[kody-ai]

🤔 Insufficient Task Context

I found a task linked to this PR, but it only contains minimal information (title only, no description or acceptance criteria). To perform a meaningful business rules validation, I need more details.

🔍 What I need to validate:

• Business requirements and acceptance criteria
• Expected behavior and business rules
• Edge cases and constraints to consider

💡 How to improve the task context:

• Add a description to the linked ticket
• Include acceptance criteria or business rules
• Describe the expected behavior after the change

⚠️ Important:

A task title alone is not sufficient to determine whether the implementation is correct or complete.

---

💡 This validation runs automatically only on the first review of a pull request. To run it again, comment @kody -v business-logic.

[kody-ai]

Found critical issues please review the requested changes

• Do not hardcode the Fleet-OPS Infisical project UUID in this public workflow — source it from a repo secret per rule [60].

[kody-ai]

Code Review Completed! 🔥

The code review was successfully completed based on your current configurations.

⚠️ 2 Kody Rule(s) were not evaluated

These rules declare that they need repository context beyond this diff, and the review could not retrieve it, so they were not judged on this pull request:

• Never move or delete existing app support.html URLs
• Prefer Sentry for new observability; do not add new Datadog RUM/APM surfaces

Kody Guide: Usage and Configuration

Interacting with Kody

• Request a Review: Ask Kody to review your PR manually by adding a comment with the @kody start-review command at the root of your PR.

• Validate Business Logic: Ask Kody to validate your code against business rules by adding a comment with the @kody -v business-logic command.

• Provide Feedback: Help Kody learn and improve by reacting to its comments with a 👍 for helpful suggestions or a 👎 if improvements are needed.

Current Kody Configuration

Review Options

The following review options are enabled or disabled:

Options	Enabled
Bug	✅
Performance	✅
Security	✅
Business Logic	✅

Access your configuration settings here.

​

Stale: every finding fixed or answered at 7a604f7, CI green.  (1) Critical, Infisical project UUID at macos-ship.yml:224: answered in the resolved thread and withdrawn by Kody; the literal is a Fleet-OPS project identifier, not a credential, identical to ios-ship.yml:215 merged in #253, pinned by both contract tests, and secrets.ASC_INFISICAL_PROJECT_ID does not exist.  (2) High, local path in docs/IOS-TESTFLIGHT.md: fixed in 05c6568, no ~/ path remains.  (3) Medium, task description: the PR body states the full trigger, gate, credential and version contract and refs CC-165.  Dismissed by CLAUDE per owner ruling 2026-10-17.