Skip to content

lidge-jun/codexclaw / plugins/codexclaw/skills/dev-devops

cxc-dev-devops

Verified

Use for infra, CI/CD, releases, repo policy, worktree cleanup and native desktop apps. Triggers: Dockerfile, K8s, IaC, SRE, Tauri, 스택 PR CI, 배포, 인프라, 쿠버네티스, 브랜치 정리, 브랜치 삭제, 워크트리 정리, 저장소 세팅, 브랜치 보호, 에이전트 PR, PR 정책, 데스크톱 앱, 메뉴 막대.

references/native-desktop-acceptance.md

View on GitHub
# Native Desktop Acceptance — Tauri, AppKit/SwiftUI, WidgetKit, Menu-bar Apps

Last reviewed: 2026-09-24
Applies to: Tauri apps, AppKit/SwiftUI code linked into another host (Swift static library + C ABI), WidgetKit extensions, menu-bar/tray apps, native window materials, embedded runtimes and sidecars, macOS desktop release paths
When to read: A change touches one of those surfaces, or you are asked for a desktop regression audit or release readiness
Canonical owner: dev-devops native desktop acceptance
Non-goals: building a desktop app for the user; iOS/Android (→ `dev-frontend/references/stacks/mobile-native.md`); approval prompts in depth (→ `macos-system-approvals.md`)

---

## §1 Scope and triggers (DESKTOP-SCOPE-01)

A desktop app is several products in one bundle: a UI, a host runtime, embedded
executables, extensions, and a signed, distributed artifact. Source review,
host-only CI and a screenshot each cover one of them. Name which one before
claiming anything.

- A Swift, Rust or web change that alters a **presented native surface** (panel,
  popover, window, material, tray menu) triggers UI rows.
- A non-UI change (a Swift model, a Rust command, a sidecar flag) triggers
  runtime and packaging rows only. Do not demand screenshots for code nobody sees.
- A signing, entitlement, bundle-layout, architecture or updater change triggers
  packaging and distribution rows even when no code changed.

When a goalplan tracks this work, register each criterion on a session-bound
plan with `cxc loop add-criterion --session <id> --criterion <text> --surface
desktop [--presented native]` (`init` refuses `--surface`). Use `--presented
native` only when the criterion needs inspection of a presented native surface.
It activates a soft, fail-open C-phase Stop advisory requesting an explicit
native observation; it does not block completion. Without a recorded final gate,
the desktop classification still calls for this matrix. A schemaVersion 2+
plan with a recorded final gate requires a QA receipt, and each non-native
desktop criterion needs a matching artifact-identity entry in that receipt.
Default v1 plans rely on QA ingress validation. Hosts editing plans need a
build that preserves `desktop` and `presented` on read and write.

## §2 Acceptance matrix (DESKTOP-MATRIX-01)

One row per boundary, never one "desktop OK" row.

| Column | Content |
|---|---|
| Row id | Stable id, e.g. `D-UI-03` |
| Boundary | What joins what: popup ↔ status item, Rust ↔ Swift ABI, app ↔ sidecar |
| Scenario | The exact situation exercised |
| Verdict class | UI, runtime, packaging or distribution |
| Required level | The weakest evidence level that can prove this row (ladder below) |
| Achieved level | The level the evidence actually reached |
| State | pass, fail, not_verified, needs_human, hosted_required, na |
| Artifact id | Which artifact the evidence came from (§6) |
| Baseline class | §5 |

Evidence levels, weakest to strongest: source review → host-only build → signed
bundle inspection → bundled runtime launch → native interaction → publication.
A row can pass only when the achieved level is at least the required level.

Mapping to cxc-qa: each row is one cxc-qa scenario whose scenario id is the row
id; `note` carries the state, required and achieved levels. UI rows are `gui`
verdicts with `captureChecks`. Runtime, packaging and distribution rows are
`cli` verdicts, except a distribution row observed as a dialog (Gatekeeper),
which is `gui`. `not_verified`, `needs_human` and `hosted_required` roll up as
QA `FAIL` with the blocker named, because cxc-qa has no skip. `na` maps to
`NA` and needs the recorded structural reason cxc-qa requires. Evidence from a
hosted runner enters the scenario directory as the downloaded job log or
artifact, with the run id, attempt and head SHA recorded (cxc-dev
DEV-CI-EVIDENCE-01). The hosted head SHA must equal the verdict's
`sourceSnapshotAt.commitSha` on a clean tree; otherwise the row stays
`not_verified`, because nothing else checks that the run built this tree.

Example rows for a change to a Tauri tray popup rendered by a native panel:

| Row | Boundary and scenario | Class | Required | Achieved | State |
|---|---|---|---|---|---|
| D-UI-01 | Popup opened over another app's window, dark appearance | UI | native interaction | native interaction | pass |
| D-UI-02 | Popup content longer than the panel: scroll bounded, footer visible | UI | native interaction | source review | not_verified |
| D-RT-01 | Bundled CLI runs from the signed app with final entitlements | runtime | bundled runtime launch | bundled runtime launch | pass |
| D-PK-01 | `lipo -archs` on app executable and sidecar equals `x86_64 arm64` | packaging | signed bundle inspection | host-only build | not_verified |
| D-DS-01 | `xcrun stapler validate` on the notarized DMG | distribution | signed bundle inspection | — | hosted_required |
| D-DS-02 | First launch of the downloaded DMG app shows the expected Gatekeeper dialog | distribution | native interaction | — | needs_human |

## §3 Downstream rows (DESKTOP-DOWNSTREAM-01)

A failure at one level leaves every row that depends on it `not_verified`: a
build that fails before bundling cannot say anything about launch, notarization
or installation. After a repair, review every assertion the repair newly makes
reachable. A removed upstream failure often exposes an assertion that was never
executed, such as a hardcoded executable path that the bundle does not declare.

## §4 Ordinary CI versus the release path (DESKTOP-CI-MAP-01)

Before claiming a regression audit or release readiness, tabulate what ordinary
CI builds against what the release workflow ships:

| Dimension | Ordinary CI | Release path |
|---|---|---|
| Architectures | often host-only | universal or per-arch set |
| Toolchains | Bun/Rust/Xcode/SDK/deployment target as pinned in CI | as used by release |
| Sidecar preparation | may be skipped | target-triple names, universal merge |
| Signing | ad-hoc, no secrets | Developer ID, entitlements, timestamp |
| Nested bundles | may be absent | `.appex`, frameworks, helpers |
| Distribution | usually none | DMG, updater archive and signature |
| Final artifact execution | rarely | launch and bundled CLI execution |
| Install/upgrade | never | coexistence with an existing install |

Every row where the columns differ is coverage ordinary CI does not provide.
Run the supported non-publishing release-equivalent job (dry run) early rather
than discovering each difference in turn. Never give signing secrets to
untrusted pull-request code.

## §5 Baseline classification (DESKTOP-BASELINE-01)

Classify each row as unchanged, regressed, new, removed or repair-introduced,
against a real baseline oracle: an earlier artifact you actually ran, not a
memory of one. If the baseline version has no desktop surface at all, write
"baseline absent" and treat the rows as new-feature obligations. "No desktop
regressions" is not a finding when there was no desktop to regress.

## §6 Artifact identity (DESKTOP-ARTIFACT-01)

When a desktop row depends on a built artifact, set `desktopArtifact: true` in
its `verdict.json`, list its goalplan IDs in `criterionIds` (for example
`["c-3"]`), and include exactly one `artifact-identity.json` in `artifactRefs`.
The identity file uses `version: 1` and these fields:

- Required `bundlePath` (the `.app` path) and `bundleExecutable` (the
  `CFBundleExecutable` value); optional non-empty `bundleIdentifier`. The
  executable component path must derive from
  `<bundlePath>/Contents/MacOS/<bundleExecutable>`. The validator checks path
  consistency; it does not read `Info.plist` to verify that value.
- `components` contains exactly one record each for `app`, `executable`,
  `archive`, `dmg`, and `updater`, plus any `sidecar` and `extension` records.
  Each has a unique non-empty `id` and a `kind`. An applicable `app` has a path
  to a `.app` directory containing `Contents/Info.plist` and a lowercase
  `sha256` bundle tree digest. Compute it with
  `node plugins/codexclaw/skills/qa/scripts/validate-evidence.mjs --bundle-digest <path.app>`.
  The tree digest covers file bytes, paths, directories and symlink targets;
  bundle symlinks must resolve inside the bundle. Applicable executable and
  archive records carry file SHA-256 digests; every other applicable file
  component also carries a lowercase SHA-256 digest. Applicable executable,
  sidecar and extension records additionally carry non-empty `architectures`.
  An unavailable component uses `{ "applicable": false, "reason": "..." }`
  and needs no path, digest or architectures. An applicable app requires an
  applicable executable and archive.
- `signing.mode` is `ad-hoc` or `Developer ID`. A Developer ID identity needs
  non-empty `signing.teamId`; ad-hoc requires it absent or null.
  `signing.entitlements` is a normalized object of boolean, string, finite
  number or string-array values. Record values from the signature inspection.
- `toolchain.xcodeSelectPath`, `toolchain.sdk` and
  `toolchain.swiftcVersion` are required non-empty strings; `rustVersion` and
  `bunVersion` are optional when those tools were used. `coveredRowIds` must
  include the verdict's desktop scenario ID.

`validate-evidence.mjs --emit-receipt` validates referenced identities and
hashes each verdict and identity file into typed QA receipt `artifactManifest`
entries (`path`, `sha256`, `kind`, optional `criterionIds`). It copies the
validated verdict's IDs to its identity entry; receipt parsing rechecks bytes
and that binding. A schemaVersion 2+ recorded final gate requires a matching
identity entry for every non-native desktop criterion. Default v1 plans use QA
ingress validation only. A `presented: "native"` criterion uses the soft native
observation advisory and has no artifact-manifest requirement from this gate.
An ad-hoc single-architecture `.app` does not satisfy a universal Developer
ID, DMG or updater row. The archive hash binds its bytes but the validator
does not unpack it to prove the app is inside.

## §7 Tauri, Rust and Swift boundary (DESKTOP-FFI-01)

When Swift UI code is compiled into a static library and linked into the Tauri
executable:

- Swift `@_cdecl` exports match the Rust `extern "C"` declarations. Check with
  `nm` on the archive and on the final executable.
- The archive the build script emitted is the one that was linked. A SwiftPM or
  Xcode build of the same sources proves nothing about the Cargo-linked app.
- Status-item and panel calls stay on the AppKit main thread (engineering
  practice).
- Borrowed pointers are copied before the call returns; callbacks are torn down
  with the panel.
- Minimum OS values agree between the `swiftc -target` triple and
  `Package.swift`, or the difference is a recorded decision.
- Glass materials (`NSGlassEffectView`) versus the fallback view depend on the
  build toolchain and the runtime OS. A symbol check proves the code path
  exists, not that the material is visible or clipped correctly.

## §8 WidgetKit (DESKTOP-WIDGET-01)

Widgets live in their own extension and update through timelines. In practice
the extension has its own build product, compile mode, entry point, placement
under `Contents/PlugIns` and signature (the OpenCodex case in codexclaw issue
#232). Widget success says nothing about the menu-bar panel, and the reverse.

## §9 Sidecars and universal binaries (DESKTOP-UNIVERSAL-01)

- Tauri `bundle.externalBin` needs a file with a `-<target-triple>` suffix for
  every supported architecture. A universal build also needs a universal
  sidecar under the name the bundler looks for (in the #232 case,
  `ocx-universal-apple-darwin`); confirm the expected name from the failing or
  succeeding bundler run, not from memory.
- Each embedded executable reports exactly the expected architectures.
- The bundled CLI runs from the **final signed bundle** with its final
  entitlements. JIT runtimes under Hardened Runtime need
  `com.apple.security.cs.allow-jit`, or they may fall back or crash.
- Use the shipped behavioral oracle:
  `node plugins/codexclaw/skills/dev-devops/scripts/verify-lipo-command.mjs --artifact <file> --arch <a> --arch <b> --candidate-json '<argv-json>'`.
  It compares the reported architecture set exactly (`arm64` and `arm64e`
  differ), runs the candidate argv against the good artifact, creates a thin
  negative control and requires the candidate to fail on it. The candidate
  JSON must contain one `{artifact}` placeholder. No shell string is evaluated.
  Record the lipo executable/toolchain identity and fixture with the result.
  This proves only that candidate's behavior on that toolchain and fixture;
  it does not prove packaging, signing, notarization or native interaction.
  Multi-architecture `-verify_arch` forms observed on this Mac failed with
  `requires exactly one input file`, so do not prescribe them.

## §10 Menu-bar and popup scenarios (DESKTOP-POPUP-01)

Capture the native panel itself. A browser or web-dashboard screenshot cannot
satisfy a native panel row. The status item is customized through its
`button`; record where the panel appeared relative to it on each display.

| Scenario | Why it breaks |
|---|---|
| Plain desktop behind the popup, and another window behind it | Materials and corner clipping render differently over content |
| Light and dark appearance | Material and text contrast |
| Long content | Scrolling must stay bounded and the footer visible |
| Focus, Escape, click outside, reopen | Panels that do not dismiss or reopen cleanly |
| Several displays and the notch | Placement relative to the status item |
| Full-screen Space, auto-hidden menu bar | Panel never appears or appears off-screen |

Scenarios that need a person, or a prompt only a person may answer, are
`needs_human` rows with exact instructions (`macos-system-approvals.md` §6).

## §11 Signing, notarization and distribution (DESKTOP-DIST-01)

- Notarization needs a Developer ID certificate, Hardened Runtime, a secure
  timestamp and no `get-task-allow` entitlement.
- Entitlements attach to executables. Shared libraries, frameworks and
  in-process plug-ins inherit the host's; app extensions, widgets included, are
  separate executables with their own signature and entitlements. Check each
  with `codesign -d --entitlements -`.
- `codesign -vvv --deep --strict` checks nested code at notarization
  strictness. Changing any file in a bundle after signing invalidates it.
- `spctl --assess -vv` and `xcrun stapler validate` on the distributed
  artifact (engineering practice).
- Tauri updater signatures cannot be disabled; `createUpdaterArtifacts` produces
  the `.app.tar.gz` and `.sig`; `pubkey` must be the key content, not a path.
- Notarized is not launch-tested. Apple notes that some software fails to run
  after notarization because Gatekeeper enforces checks a relaxed notarization
  did not, and advises testing before distribution.

## §12 When local execution is not allowed (DESKTOP-NOLOCAL-01)

If the user forbids local runs, keep every row and mark it `hosted_required`
(a hosted macOS runner or an authorized native session can execute it) or
`not_verified`. A person's acceptance covers only the scenario they state.
Source-string tests and reviewer attestations never replace executing the tool.

## §13 Report shape

Report UI, runtime, packaging and distribution verdicts separately, each with
its rows, evidence levels and artifact ids, and list every row that is not
`pass` with its blocker.

## Sources

- Tauri v2: [System tray](https://v2.tauri.app/learn/system-tray/), [tray API](https://v2.tauri.app/reference/javascript/api/namespacetray/), [sidecars](https://v2.tauri.app/develop/sidecar/), [macOS signing](https://v2.tauri.app/distribute/sign/macos/), [app bundle](https://v2.tauri.app/distribute/macos-application-bundle/), [DMG](https://v2.tauri.app/distribute/dmg/), [updater](https://v2.tauri.app/plugin/updater/)
- Apple: [NSStatusItem](https://developer.apple.com/documentation/appkit/nsstatusitem), [NSGlassEffectView](https://developer.apple.com/documentation/appkit/nsglasseffectview), [WidgetKit](https://developer.apple.com/documentation/widgetkit), [notarizing](https://developer.apple.com/documentation/security/notarizing-macos-software-before-distribution), [common notarization issues](https://developer.apple.com/documentation/security/resolving-common-notarization-issues), [Hardened Runtime](https://developer.apple.com/documentation/security/hardened-runtime), [allow-jit](https://developer.apple.com/documentation/bundleresources/entitlements/com.apple.security.cs.allow-jit)
- The OpenCodex case: codexclaw issue #232. Executed `lipo` results: repository devlog `260923_native_desktop_acceptance/001_research.md` (not shipped in the plugin payload)
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 319kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall