dimagi-internal/ace / skills/app-release
app-release
VerifiedBuild and release Learn and Deliver apps on CommCare HQ so Connect can read their form schema and deliver units. Needs the HQ app ids.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 37.7 KB |
| reference.md | markdown | 2.9 KB |
SKILL.md
View on GitHub---
name: app-release
description: >
Build and release Learn and Deliver apps on CommCare HQ so Connect can read their form schema
and deliver units. Needs the HQ app ids.
disable-model-invocation: false
---
# App Release
**Worker role (multi-role runs):** when the dispatch carries a `worker_role: {key, label}` block, scope this run to that role's apps and its part of the PDD, and read and write every `3-commcare/` (or `4-connect/`) file at the same name under `3-commcare/roles/<key>/` (`4-connect/roles/<key>/`). No block = a single-role run, unchanged. Contract: [`skills/_worker-roles.md`](../_worker-roles.md).
**Run workspace:** when the dispatch carries a `run_workspace:` block, its values replace the `.env` ones this skill names — `ACE_HQ_DOMAIN` → `run_workspace.hq_domain` — and a partner workspace never falls back to `.env`. Contract: [`skills/_run-workspace.md`](../_run-workspace.md).
Make a new build of each app on CCHQ and mark it as **Released**, so Connect
can read its form schema and surface deliver units to the opportunity.
## Inputs
The skill releases any HQ app, whether ACE built it this run or it is a live program's app.
Pass the values explicitly. Inside `/ace:run` each one defaults to the run's Phase 3 artifacts.
| Parameter | Used for | Resolver |
|---|---|---|
| `hq_domain` | the project space the apps live in | explicit argument; default: `run_workspace.hq_domain`, else `app-deploy_summary.md` frontmatter `hq_domain` |
| `learn_app_id` / `deliver_app_id` | the 32-char HQ app ids to build + release (either or both) | explicit argument; default: `3-commcare/app-deploy_summary.md` frontmatter |
| `learn_nova_app_id` / `deliver_nova_app_id` | Step 3a drift check and the Step 4a build-rejection fix loop | explicit argument; default: `3-commcare/pdd-to-{learn,deliver}-app_summary.md` frontmatter `nova_app_id`. Omit for an app with no Nova source: Step 3a then records `conclusive: false` and Step 4a can only surface the rejection |
| `deployed_at` | Step 3a `deployedAt` signal | explicit argument; default: `app-deploy_summary.md` frontmatter `uploaded_at`; leave unset when unknown (the classifier handles an omitted signal, never a guessed one) |
| `opportunity_id` | an EXISTING opportunity wired to these apps, whose deliver units Step 7 re-syncs | explicit argument; default: run_state `phases.connect-setup.products.opportunity.id` when that phase has run; absent on a first build |
| `summary_folder_id` | where the release summary is written | default: the run's `3-commcare/` folder; outside a run, the program project's Drive folder (`skills/partner-on-connect-program`) |
## Existing objects
Releasing a new build of an app that a **live** opportunity already uses changes what
working FLWs run, and some of what it touches is shared:
- **Workers get the new build.** A released build is what CommCare offers on the next app
update. Release only content you mean every worker on every opportunity wired to this app
to receive.
- **Deliver units are keyed per app and shared within the holding org** (ace#573). Re-releasing
the same `deliver_app_id` re-uses the existing `DeliverUnit` rows: it cannot give you a
fresh payment unit. A new deliver form shows up only after the deliver-unit sync in Step 7.
- **The Learn passing score lives on the shared `CommCareApp` row** (ace#1350), not on the
opportunity. A release does not change it, but every opportunity on this Learn app reads the
same score, so don't "fix" it per opportunity.
- **Whether a live opportunity picks up a re-released build without a manual sync is
unverified.** Read back with `connect_list_deliver_units` after Step 7 rather than assuming.
See `playbook/integrations/connect-api.md`.
## Products
- `3-commcare/app-release_summary.md` — released build IDs + version numbers per app. Outside a run the same file goes into `summary_folder_id` (§ Inputs).
**Frontmatter contract (ace#1439).** `app-release-eval § both_apps_released`
reads these keys, so they are declared here rather than left to whatever the
run happened to write. This file is the **sole owner of released build
state** — `is_released`, `build_id` and `version` live HERE and nowhere
else, and every reader (`app-release-eval`, `app-release-qa`,
`llo-launch`'s app-verdict-freshness gate) reads them from here:
```yaml
apps:
learn_app: { hq_app_id: <id>, build_id: <id>, version: <n>, is_released: true, released_at: <iso> }
deliver_app: { hq_app_id: <id>, build_id: <id>, version: <n>, is_released: true, released_at: <iso> }
# Step 3a's pre-build drift decision, per app (ace#1643). Present on
# every run — `drift: false` is a RESULT and must be recorded, because a
# skip that is not written down is indistinguishable from a check that
# never ran.
drift_check:
learn: { drift: <bool>, conclusive: <bool>, action: <build-directly|reupload-reapply-settings-then-build>, reupload: <bool>, settings_reapplied: [...], reasons: [...] }
deliver: { drift: <bool>, conclusive: <bool>, action: <...>, reupload: <bool>, settings_reapplied: [...], reasons: [...] }
```
`is_released` and `version` mirror what HQ returns from the release POST
(`{"is_released": true, "latest_released_version": <n>}` — note HQ's field is
`latest_released_version`; the artifact key is `version`, and conflating the
two is what put a phantom key in the rubric for four months).
## Why this skill exists
Nova uploads apps to CCHQ as a **draft** only; Connect surfaces deliver
units only from a **released build**. This skill makes the versioned build
and releases it. For the full rationale, see reference.md § Why this skill
exists.
## Prerequisites
The CCHQ user backing `ACE_HQ_USERNAME` (`ace@dimagi-ai.com`) **must
have a role with `edit_apps` permission** on the target project space.
The standard `Admin` role on connect-ace-prod includes this. Verify
once via the Web Users page (`/a/<domain>/settings/users/`) if you hit
auth-shaped errors. Note the CCHQ `Sorry, you don't have permission to
do this action!` banner is a generic Knockout error fallback, NOT a
literal permission verdict — see § Failure Modes before treating it as
diagnostic.
## Endpoints (verified 2026-04-29)
CCHQ's URL patterns are internal UI routes, not public APIs. For how they
were discovered, see reference.md § How the endpoints were discovered.
```
# Step 1 — Make a versioned build (creates a "build" doc; sets built_on)
GET /a/<domain>/apps/view/<app_id>/releases/ # GET first to refresh csrftoken
POST /a/<domain>/apps/save/<app_id>/ # empty body suffices
→ 200 { "saved_app": { "_id": "<build_id>", ... } } # _id IS the new build_id
# Step 2 — Release that build (toggles is_released=true)
POST /a/<domain>/apps/view/<app_id>/releases/release/<build_id>/
Body: ajax=true&is_released=true
→ 200 { "is_released": true, "latest_released_version": <n> }
```
CSRF: extract from the `csrftoken` cookie set by the GET in step 1; pass
it as `X-CSRFToken` header on both POSTs.
Verify via the read-only HQ API (no UI session needed):
```
GET /a/<domain>/api/v0.5/application/<build_id>/
Authorization: ApiKey <ACE_HQ_USERNAME>:<ACE_HQ_API_KEY>
→ { "is_released": true, "version": <n>, "built_on": "<iso>" }
```
If the URL pattern shifts in a future CCHQ release, use the probe
procedure below to rediscover.
### Probe procedure (only when the verified URLs above fail)
1. Open `/a/<domain>/apps/view/<app_id>/releases/` in `/browse` with the
CCHQ cookies imported from `~/.ace/connect-session.json`.
2. Inject an XHR/fetch interceptor (`window._cap = []; XMLHttpRequest…`).
3. Click `Make New Version`. Capture the POST URL + body.
4. Once a build appears, click the `Released` toggle (CSS-styled button,
bound to `$root.toggleRelease`). Capture that POST URL + body.
## Process
1. **Resolve the app ids** per § Inputs. Explicit arguments win.
- Inside a run, `ACE/<opp-name>/runs/<run-id>/3-commcare/app-deploy_summary.md` frontmatter
has `learn_app_id` and `deliver_app_id` (the 32-char HQ app IDs Nova wrote there), plus
`hq_domain` (typically `connect-ace-prod`) and `hq_base_url`.
- Outside a run, take them from the caller, or from the program context doc's HQ apps row.
Confirm each id exists in `hq_domain` (`commcare_list_apps`) before building, so a stale
id fails here and not mid-release.
2. **Establish session.** Use the `~/.ace/connect-session.json` cookie jar
(Connect's OAuth-via-CCHQ flow leaves valid CCHQ cookies). If
expired, run `/ace:connect-login` to refresh.
3. **Pre-flight: Connect-marker coverage must be clean.** Releasing an
app whose forms lack Connect markers succeeds at the build level, but the
opportunity then gets stuck with empty deliver units (Phase 4 Step 2 on a
build, a silently unpayable form on a live program). This gate is not
optional, and it is a check this skill RUNS, never a file it trusts blindly:
- **In a run where Phase 3 Step 1.5 already ran:** read
`3-commcare/app-connect-coverage_{learn,deliver}.md`. `status: clean`
passes. `blocked` halts.
- **Otherwise (no coverage verdict for this app, or outside a run):** run
`app-connect-coverage` now against each app's Nova app id. Its auto-fix
edits Nova, so any fix it makes leaves the HQ draft stale. Step 3a then
reports drift and forces the re-upload before the build. With no Nova app
id, check the HQ draft's form XML for the markers instead
(`commcare_get_form_source`). If any are missing, halt: there is no
source to fix them in.
- Either way, `blocked` or missing markers halt. Never build past them.
3a. **Pre-build drift check — is the HQ draft still the Nova app? (ace#1643)**
`commcare_make_build` versions the **CCHQ draft**. It does not pull
from Nova. So any Nova edit made after `app-deploy` is absent from
the released CCZ and the release still reports success. Run this
check per app, BEFORE Step 4.
**Step 6's marker verification cannot cover this.** The markers were
correct on the stale build too — it was a well-formed build of the
wrong content. **Marker integrity is not a proxy for content
integrity**, which is why this check is content-level and sits
before the build. (`app-release-eval`, ace#1643.)
1. **Gather the signals** (all cheap, all read-only):
| Signal | Source |
|---|---|
| `deployedAt` | `deployed_at` per § Inputs (in a run: `3-commcare/app-deploy_summary.md` frontmatter `uploaded_at`) |
| `novaEditedSinceDeploy` | THIS RUN's own knowledge — did any step dispatch `/nova:edit`, an eval-driven repair, or a Step 4a build-rejection fix on this app AFTER `app-deploy`? `true` / `false`; leave unset if genuinely unknown (the usual case outside a run — the content counts below still decide) |
| `novaFormCount` | `get_app({app_id: <nova_app_id>})` — one call per app |
| `novaVisibleFieldCount` | Same `get_app` response, normalized to the HQ walk's basis: **every non-`hidden` LEAF, plus every `group`/`repeat` whose label is NON-EMPTY**. Use `countNovaVisibleFields` from `lib/app-release-drift.ts` — don't do this arithmetic by hand. Two corrections, each found by a live mismatch: the walk emits no hidden fields (`user_score`, `qN_score`, `case_name`, `entity_key`, `entity_label`, … — every ACE app has them, ace#1789), and it emits a container only when that container rendered a `<label>`, so an EMPTY-labelled group compiles to a self-closing `<group ref="…"/>` and contributes nothing while Nova still counts 1 (ace#1807). **The exclusion is on the LABEL, not on "all children are hidden"** — the compiled CCZ emits the group element either way; ace#1807's original wording said otherwise and was refuted against `test/fixtures/ccz/spark-facilitator-meeting-record.xml` |
| `hqDraftFormCount` / `hqDraftVisibleFieldCount` | `run-form-walk.ts <hq_domain> <hq_app_id> --draft-only --with-fields --out-scratch` (same invocation `app-hq-settings § Step 2` documents; check `fields_available: true` before trusting the field count) — already visible-only, nothing to exclude on this side |
| `novaEditedAt` | optional — pass only if the Nova surface actually exposes a last-edited timestamp. Do NOT invent one; an omitted signal is handled, a guessed one is not |
2. **Classify** with `classifyAppDrift` from `lib/app-release-drift.ts`
(a pure function, unit-tested in `test/lib/app-release-drift.test.ts`
— the decision is not left to prose). It returns
`{drift, action, conclusive, reasons}`.
Two properties of the classifier are deliberate and must not be
"optimised" away:
- **Matching counts never clear the build-directly branch.** Of the
three drifting Deliver edits in the ace#1643 repro, only
`gps_lat`/`gps_lon` moved a count; the extended consent paragraph
and the `area_ref` constraint moved none. Counts detect drift;
they cannot prove its absence. Clearing the skip needs an
ORDERING fact.
- **Unresolved signals default to `drift: true`** (with
`conclusive: false`). A needless re-upload costs one idempotent
call; a skipped one ships the wrong app and reports success.
- **A field-count mismatch is a SOFT signal; a form-count mismatch
is not (ace#1789).** A hidden field never creates a new form, so a
form-count mismatch always forces drift. A field-count mismatch
can be a basis artifact (see `novaVisibleFieldCount` above), so
once an ORDERING fact is clear it is downgraded to corroboration
rather than forcing drift — it still forces drift when no
ordering fact resolves the question, matching the conservative
default above.
3. **On `action: 'reupload-reapply-settings-then-build'` — an ordered
TRIPLE, and the middle item is the one a naive fix omits:**
1. `/nova:upload_to_hq <nova_app_id> <ACE_HQ_DOMAIN>` — updates the
HQ app in place (`hq_app_action: updated`, id unchanged,
`left_behind: []`). Honour `app-deploy § HQ-id stability` if the
id DID change.
2. **Re-apply `app-hq-settings` and re-verify from
`GET /apps/source/`.** The re-upload REVERTS two of the four
settings that skill applies — measured on
hh-poverty-targeting/20260824-1404 (ace#1643):
| Setting | Survives a re-upload? |
|---|---|
| `appearance="acquire"` on Deliver image fields | **no — wiped** |
| per-module `display_style: grid` | **no — reverted to list** |
| app-level `use_grid_menus` | yes |
| app-level `grid_form_menus` | yes |
`app-release-qa` Step 2.8 BLOCKER-gates all three grid fields
and the `acquire` appearance, so re-uploading WITHOUT this
re-apply converts a silent stale-content bug into a hard Phase 3
halt.
After a re-upload the form uids are the 40-hex SHA-1 variant, not
32-hex. `commcare_get_form_source` / `commcare_patch_xform` and
`run-form-walk --draft-only` all accept both widths (ace#1644,
`lib/hq-unique-id.ts`) — a `unique_id` validation error or a
`resolved 0 forms` here means the plugin predates that fix, and
**MCP code needs a full Claude Code restart, not `/reload-plugins`**.
3. Only then proceed to Step 4.
4. **On `action: 'build-directly'`**, go straight to Step 4 — and say
so explicitly in the summary. A skip that is not recorded is
indistinguishable from a check that never ran.
5. **Record the decision** in `3-commcare/app-release_summary.md`
frontmatter, per app, so it is auditable:
```yaml
drift_check:
learn: { drift: false, conclusive: true, action: build-directly, reupload: false, settings_reapplied: [], reasons: [...] }
deliver: { drift: true, conclusive: true, action: reupload-reapply-settings-then-build, reupload: true, settings_reapplied: [camera_only_acquire, module_display_style_grid], reasons: [...] }
```
`reasons` is `AppDriftDecision.reasons` verbatim. When
`conclusive: false`, the body MUST say the verdict was a default
taken on missing signals, not an observation.
4. **For each app (learn + deliver):** run the verified Step 1 + Step 2
POSTs above. Each call is idempotent on the build side: re-POSTing
`/apps/save/` after a release creates a new build at the next version,
leaving prior builds released. So safe to re-run.
4a. **If `commcare_make_build` throws `BuildRejectedError` — auto-fix
loop with the Nova architect.** This loop fixes the bad XForm at the
source (the Nova app) and retries. For origin, see reference.md
§ BuildRejectedError auto-fix loop.
The MCP atom now returns
`{error: 'build_rejected', app_id, error_text, error_html, retryable: false}`
with `error_text` already HTML-stripped (see
`mcp/connect/backends/commcare.ts § BuildRejectedError`). Catch
it; do **not** treat `retryable: false` as "give up." That field
means "the same args won't succeed against this app id" — the loop
fixes the app first, then retries.
**Loop invariants (max 3 iterations per app):**
1. **Parse `error_text` into a structured form locator.** CCHQ's
canonical shape is:
Cannot make new version
"<form-name>" Form in the "<menu-name>" Menu
Error parsing XML: <parser-message>, line <N>, column <M>
Error in form "<form-name> [<lang>]": <repeat>
Extract: `form_name`, `menu_name`, `line`, `col`,
`parser_message`. The form-name is the human label (e.g. "Unique
ID check"), not the form_unique_id; it's all you have at this
point because the CCZ never built.
2. **Map `form_name` → Nova `form_id`.** Resolve the app's
`nova_app_id` per § Inputs (in a run:
`3-commcare/pdd-to-{learn,deliver}-app_summary.md` frontmatter
`nova_app_id`; with none, skip to step 6 and surface the rejection —
there is no source to fix). Call
`nova__get_app({app_id})` for the live structure and walk to
the form whose name matches `form_name`. On ambiguity (two
forms with the same name in different modules), use
`menu_name` to disambiguate. If still ambiguous, halt the loop
and surface the ambiguity in `auto_surfaced` — operator decides.
3. **Dispatch the Nova architect** via `/nova:edit <nova_app_id>`
with a brief that names the form, the line/col, the parser
message, and the most-likely fix class. Template:
Form "<form_name>" in module "<menu_name>" produces invalid
XForm XML. CCHQ rejected `make_build` with:
<parser_message>
at line <N>, column <M>
The most common cause is unencoded `<`/`>`/`&`/`"` in label,
option, hint, or constraint-message text — Nova's emitter
does not entity-encode these (tracked at
voidcraft-labs/nova-plugin issue #15). Inspect every label,
option, hint, and constraint_message in this form via
`get_form` + the per-field `edit_field` getter. For any
string that contains a literal `<`, `>`, `&`, or `"`,
replace with words ("three letters") or backticks
(`three letters`) via `update_form` / `edit_field`, then
SAVE the checkpoint with `save_work` and confirm it answered
`saved: true` — only saved changes are uploaded, and the
save is where Nova validates the whole candidate. If you
cannot save, report the work id instead of claiming a fix.
4. **Re-upload via `/nova:upload_to_hq <nova_app_id> <ACE_HQ_DOMAIN>`**
— only once the edit's return names a saved checkpoint. `/nova:edit`
(plugin v2) works in private work (voidcraft-labs/commcare-nova#693):
if it returns a `work_id` with pending changes, the fix is NOT in the
saved app and re-uploading changes nothing — treat that iteration as
a failed fix, not a retry of the build.
Pass the target project space explicitly (same as `app-deploy`,
Nova plugin voidcraft-labs/nova-plugin#12). Nova **updates the
HQ app in place**: the id is unchanged and `hq_app_action` comes
back `updated` (verified live 2026-08-18 — see
`playbook/integrations/nova-integration.md § Uploading to HQ
updates in place`). So there is normally no new id to chase and
no orphan left behind.
Read `hq_app_action` and `deployment.left_behind` anyway rather
than assuming. If the id DID change (`left_behind` non-empty, or
`hq_app_action: created` for an app already uploaded — reachable
when the linked HQ app was deleted on HQ and the call refused
with `remote_app_missing`), update the in-memory app reference to
the new `hq_app_id`, record both ids in
`3-commcare/app-release_summary.md.frontmatter.hq_app_id_history`
so Phase 4's downstream wiring (which reads the LATEST id) lines
up, and surface the change loudly.
5. **Retry `commcare_make_build` against the current HQ app id** (the
same one, unless step 4 reported it changed). If
it still throws `BuildRejectedError`, parse the new
`error_text` (it may name a different form / line / cause) and
loop. **Cap at 3 total attempts per app.**
6. **On exhaustion (3 failed attempts),** surface the FINAL
`BuildRejectedError` to the orchestrator as a `[BLOCKER]` in
this skill's returned summary with: every iteration's
`error_text`, every Nova edit dispatched, the final
`hq_app_id`, the operator-facing remediation (manual CCHQ
form-designer edit on the final orphan id, OR wait for Nova
upstream fix). Phase 3 halts. Do not silently downgrade to
success.
**Why bounded (3 attempts).** For the rationale, see reference.md
§ Why the BuildRejectedError loop is bounded at 3.
**Dispatch-depth note.** `/nova:edit` runs the Nova architect via
`Agent`, which costs a level of dispatch depth. `app-release` is
invoked from Phase 3 (`commcare-setup`), a subagent, so the architect
lands at depth 2. Moving `app-release` under more layers pushes it down;
past the budget the `Agent` tool is withheld and the loop degrades
silently instead of failing. `test/lib/agent-depth.test.ts` holds
the number. Keep the
invariant.
5. **Verify both apps show `is_released: true`** via the API.
6. **Verify the released CCZ via `commcare_download_ccz` projection.**
Call `commcare_download_ccz(domain, app_id, build_id, include_multimedia=false)`
and read all three gates on the response:
- **`projected_connect_state.collision_count`** — MUST be `0`.
This is a deterministic projection of what Connect's HQ→Connect
sync will produce: every `<learn:deliver>` / `<learn:module>` /
`<learn:task>` / `<learn:assessment>` element across every form,
deduplicated by `(app, slug)` exactly like
`commcare-connect/opportunity/tasks.py:sync_learn_modules_and_deliver_units`.
A non-zero count means N forms emit the same `id` attribute and
Connect will silently collapse them, leaving the non-first forms
unwired to any payment_unit and unpaid in production.
- **Per-type record counts** (`projected_connect_state.deliver_units.length`
etc.) MUST be > 0 for the app type — Learn apps have ≥ 1 module,
Deliver apps have ≥ 1 deliver_unit. Zero means the form lacks
Connect metadata at the source (Nova didn't generate it).
- **`projected_connect_state.oversized_slugs`** — every per-type array
MUST be empty (`oversized_slugs.deliver_units === [] && .learn_modules
=== [] && .task_units === [] && .assessments === []`). Equivalently:
`projected_connect_state.max_slug_length <= projected_connect_state.slug_length_limit`
(50 today; constant on the projection so this gate is self-documenting).
Connect's `LearnModule.slug` and `DeliverUnit.slug` are
`SlugField()` with the Django default `max_length=50`. A slug > 50
chars raises Postgres `DataError: value too long for type character
varying(50)` at sync time, which falls through the narrow `except
(CommCareHQAPIException, AppNoBuildException, httpx.*)` in
`commcare_connect/program/api/views.py:102` and surfaces as HTTP 500
with an empty body — Phase 4's `connect_create_opportunity` 500s
opaquely. Reproducer: `leep-paint-collection/20260517-1515` Phase 4,
module name "Stage 2: Sample Preparation, Drying, Bagging, Shipment"
→ slug `module_6_stage_2_sample_prep_drying_bagging_shipment`
(52 chars). See `docs/learnings/2026-05-12-boundary-probe-registry.md`.
On `collision_count > 0`, halt with a `[BLOCKER]` in this skill's
returned summary to the orchestrator. The BLOCKER MUST name every
`collisions.deliver_units[].slug` + the `kept` form + each `dropped`
form so the operator can grep the source. Concrete remediation:
re-build the affected app (typically Deliver) with **one form per
module**, since Nova's `compile_app` emits the module slug as
`<learn:deliver id>` for every form in a module, and the only
reliable way to get N unique slugs is N modules. See
`feedback_connect_deliver_unit_per_module` memory for full mechanism.
On any `oversized_slugs.*` non-empty, halt with a `[BLOCKER]` in
`auto_surfaced`. It MUST list each offender as
`<type>: <slug> (<length> chars, in <first_seen_in>)`. Concrete
remediation: rename the offending Nova module / deliver-unit to
produce a shorter slug. Rule of thumb — keep `connect.learn_module.name`
/ `connect.deliver_unit.name` ≤ 40 chars so Nova's `module_<index>_`
prefix + slugified name fits Connect's 50-char column. The
`pdd-to-learn-app` / `pdd-to-deliver-app` SKILL.md brief templates
carry this constraint upstream of `app-release` — but oversized slugs
can still leak past the brief (e.g., when an operator re-runs Nova
manually), so this gate is the structural wall.
On `< 1` records of the expected type, halt with the same Step 3
remediation (re-run coverage; this is a Nova autobuild marker-skip,
not a slug collision).
**Pre-0.13.81 fallback** (legacy `connect_markers` count, retained
for one release): if the response only has `connect_markers` and not
`projected_connect_state`, fall back to the old shape — count > 0
per type, but cannot detect slug collisions. Treat that path as a
degraded build (operator has not pulled the projection-aware MCP).
7. **Trigger Connect's deliver-unit sync.** Connect caches per-opp
deliver units; after a release, the next opp create or wizard step
will pick up the new schema. **If an opp ALREADY exists** (a re-release
of an app that a live or earlier opportunity already uses), sync THAT
opportunity. **Do not re-run `connect-opp-setup`**: it creates a new
opportunity rather than re-syncing the existing one. A new opportunity
on the same release also cannot get a payment unit, because deliver
units are shared (ace#573).
No atom syncs deliver units on its own. `connect_list_deliver_units`
and `connect_create_payment_unit(s)` fire the sync only as a side
effect, and only when the create-payment-unit form's checkbox list is
EMPTY (`mcp/connect/backends/playwright.ts` `listDeliverUnits` /
`createPaymentUnit`). So on an opp that already has deliver units,
neither one re-syncs a changed schema. Instead:
1. POST the sync route below for the existing opportunity at the
program org's URL, the same org `app-modify` uses (`runConnectOrgs()`
`pm_org_slug`). Or click `Sync Deliver Units` in that opp's wizard.
The full live-change procedure, including a new deliver unit that
needs its own payment unit, is `skills/app-modify`.
2. Read back with `connect_list_deliver_units` on the same opp, and
confirm every deliver-unit slug in the new release's
`projected_connect_state` is listed.
3. If an expected slug is still missing after the sync, halt and report
it. Do not create a new opportunity to work around it.
Sync URL pattern:
```
POST /a/<connect_org>/opportunity/<opp_id>/sync_deliver_units/
X-CSRFToken: <from hx-headers in form HTML>
```
**`opp_id` takes the opportunity UUID OR the int PK — either works**, so
there is nothing to discover from a wizard page. Connect resolves it with
`get_object_by_uuid_or_int(..., uuid_field="opportunity_id")` inside
`@opportunity_required`
(`commcare_connect/organization/decorators.py:141`,
`commcare_connect/utils/db.py:66-79`). The route itself is
`commcare_connect/opportunity/urls.py:160` under the
`a/<org_slug>/opportunity/` prefix (`config/urls.py:44`).
> **Verification status (2026-09-07, ace#2185).** Route and ID-shape are
> verified against upstream SOURCE at the commit above; the POST was **not
> exercised live** (it is a state mutation and needs an existing opp).
> Falsified by: a 404 on that path, or a 404 from the decorator when a UUID
> is passed. The prior "int FK only, read it off the wizard's `hx-post`"
> note was over-constrained and is retired.
8. **Verify Connect's HQ credential can see the release.**
Optional but recommended sanity check before Phase 4 starts. Steps 5–6
already establish `is_released` authoritatively on the HQ side, and
**Connect stores no independent copy of that fact** — it re-reads the same
`/a/<domain>/api/v0.5/application/` endpoint. So the only *additional*
thing this step can tell you is whether **Connect's own stored HQ API key
reaches `<hq_domain>` and resolves your app as released**. That is a real
Phase-4 precondition (a wrong/expired key here surfaces as a confusing
opportunity-create failure), and it is all this step is for. It cannot
detect a release problem Steps 5–6 missed.
Do NOT load the wizard page and read the dropdown — the app `<select>`
ships as `<option value="">Loading...</option>` and is populated lazily
over htmx. Call the fragment endpoint directly:
```
GET /users/api_keys/?hq_server=<n> -> <option value="<api_key_id>">…
GET /hq/applications/?hq_server=<n>&learn_app_domain=<hq_domain>&api_key=<api_key_id>
```
`hq_server` is Connect's own FK, **not** ACE's cluster key:
`1` = `https://www.commcarehq.org`, `2` = `https://india.commcarehq.org`,
`3` = `https://eu.commcarehq.org`. Use `deliver_app_domain=` instead of
`learn_app_domain=` for the Deliver app; the view accepts either
(`commcare_connect/commcarehq/views.py`, `get_application`).
**Match by app id, never by label text.** Each `<option value>` is
HTML-escaped JSON `{"id": "<hq_app_id>", "name": "<label>"}`. Find the
option whose `id` equals the `hq_app_id` recorded in Step 5, then judge:
| Observation | Meaning |
|---|---|
| option present, label is the **bare app name** | released — PASS |
| option present, label starts `Unreleased - ` | **not** released — investigate Steps 5–6 |
| option **absent** | INCONCLUSIVE — not a failure (see below) |
**There is no `Released - ` prefix.** Connect prefixes only the negative
case: `app_name = f"Unreleased - {app_name}"` when no version has
`is_released` (`commcare_connect/utils/commcarehq_api.py:74-82`). Asserting
the presence of `Released - ` waits for a string the server never emits and
would report a correctly-released app as unreleased (ace#2185).
**Absence is inconclusive, not a failure.** `get_application` drops every
app already bound to an *active, unexpired* opportunity on that domain
(`existing_apps` in the same view). So the same app that passes here before
Phase 4 legitimately vanishes from this list after Phase 4 activates the
opportunity. Never treat a missing option as "the release did not
propagate", and never assert "no `Unreleased - ` prefix appears" over the
whole response — that passes vacuously when the option isn't there at all.
> **Verification status (2026-09-07, ace#2185).** Live-verified read-only
> against `connect.dimagi.com` on run `bednet-check-2-visit/20260907-1126`:
> the fragment returned 143 options, 19 carrying `Unreleased - `, zero
> carrying `Released - `, with both released app ids
> (`cbf35cb3…`, `0f4f2a46…`) present under bare labels and matched by
> option-value `id`. The `existing_apps` exclusion is verified against
> upstream source only, **not** observed live.
If you need the wizard page itself, it is
`GET /a/<connect_org>/program/<program_id>/opportunity-init` — **hyphen, no
trailing slash** (`commcare_connect/program/urls.py`, route name
`opportunity_init`; `program_id` comes from `opp.yaml`
`connect.program.id`). The trailing-slash and the old
`/a/<org>/opportunity/init/` spellings both 404.
## Connect-marker verification
The `app-connect-coverage` skill (Phase 3 Step 1.5) verifies and
auto-fixes Connect markers before deploy — this skill consumes its
`clean | blocked` verdict. Step 6's CCZ structural verification
(the `projected_connect_state` per-type record counts) is the
post-release boundary check.
> **If you hand-check the CCZ, match markers by NAMESPACE, never by a
> `<learn:` prefix.** Nova emits them as **default-namespace** elements
> — there is no `xmlns:learn` declaration anywhere in the CCZ, so a
> literal `grep '<learn:module'` returns **0 on a perfectly clean app**
> and reads as a missing-marker halt. The wire format is:
>
> ```xml
> <module xmlns="http://commcareconnect.com/data/v1/learn" id="m1_role">
> <assessment xmlns="http://commcareconnect.com/data/v1/learn" id="readiness_quiz">
> <deliver xmlns="http://commcareconnect.com/data/v1/learn" id="vmf_visit">
> ```
>
> `commcare_download_ccz`'s own parser is namespace-aware and correct —
> prefer its `connect_markers` / `projected_connect_state` counts over any
> hand-rolled grep. The prefixed spelling used elsewhere in this file is
> shorthand for the element TYPE, not a literal string to search for.
> (dimagi-internal/ace#680 fixed this in the sibling `app-release-qa`;
> observed again from this file on spark-facilitator/20260813-2126.)
## MCP Tools Used
- **Google Drive MCP:** `drive_read_file`, `drive_update_file`
- **ace-connect MCP (CCHQ atoms, added 0.10.38+):**
- `commcare_make_build` — POST `/apps/save/<app_id>/`, returns build_id.
- `commcare_release_build` — POST `/apps/view/<app_id>/releases/release/<build_id>/`,
sets `is_released: true`.
- `commcare_download_ccz` — GET `/apps/api/download_ccz/?app_id=...&latest=release`,
returns CCZ bytes (base64) + Connect-marker counts grepped from the
inflated form XML.
These run against `ACE_HQ_BASE_URL` (default `https://www.commcarehq.org`)
using the same Playwright session as the Connect atoms — Connect's
OAuth-via-CCHQ flow leaves valid CCHQ cookies in
`~/.ace/connect-session.json`, so a single login covers both services.
**Prefer these atoms over raw `Bash` + `curl`.** The bash/curl path
documented earlier in this file is the fallback when the URL contract
shifts and a re-probe is needed. For why, see reference.md § Why prefer
the MCP atoms over raw Bash + curl.
## Mode Behavior
- **Auto:** Pre-flight, build, release, verify, update summary, proceed.
- **Review:** Same, but pause after step 4 and present the release status
for confirmation before updating the summary.
## Dry-Run Behavior
When `--dry-run` is active:
- Run pre-flight (read-only).
- Do NOT POST to `save/` or `release/`.
- Write the intended invocations and the current `is_released` state to
`comms-log/dry-run-app-release.md`.
- State tracks as `dry-run-success`.
## Failure Modes
- **HTTP 500 on `/apps/save/` with full payload**: usually a malformed
app-state JSON (deprecated case types, missing required fields, etc).
CCHQ's UI shows the generic `Sorry, you don't have permission to do
this action!` banner regardless of the underlying cause — that text
is bound to `buildState() == 'error'` in Knockout, NOT to a literal
permission check. Don't let the banner mislead the diagnosis. Look
at the actual response body or the CCHQ project's logs.
- **HTTP 200 from `/apps/save/` but no new build appears**: empty-body
POST to /apps/save/ is a no-op that just reflects the saved app.
You need to POST the full app-state JSON, which is non-trivial to
reproduce outside the UI's Knockout viewmodel.
- **Broken existing build warning**: CCHQ's app-versions page sometimes
shows "One or more of your versions is broken". This is a benign
warning about prior builds; new build creation should still work.
- **`is_released` doesn't flip after release POST**: probe URL pattern;
the release endpoint may have moved.
- **The release succeeded but ships stale content (ace#1643)**: the
symptom is a green build + a green Step 6 whose CCZ is missing a Nova
edit made after `app-deploy`. Step 3a is the guard; if the summary has
no `drift_check` block, the guard did not run. Repair is the same
ordered triple Step 3a prescribes — re-upload, **re-apply
`app-hq-settings`**, rebuild, re-release.
- **`unique_id` validation error, or `--draft-only resolved 0 forms`,
right after a re-upload (ace#1644)**: CCHQ hands back 40-hex SHA-1 form
uids after `upload_app_to_hq`. Both widths are accepted since the
ace#1644 fix (`lib/hq-unique-id.ts`). Seeing the old behaviour means
the running MCP subprocess predates it — **quit and reopen Claude Code**;
`/ace:update` + `/reload-plugins` do not respawn MCP children.
| 2026-09-28 | **The build-rejection fix loop requires a SAVED `/nova:edit` checkpoint (voidcraft-labs/commcare-nova#693).** Nova now stages edits until `save_work`, and upload reads only the saved app. The edit brief now asks the architect to save and confirm `saved: true` (replacing a call to the non-existent `validate_app`), and step 4 re-uploads only after a saved checkpoint — a returned `work_id` with pending changes is a failed fix. | ACE team |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |