fix(solicitation-create): align with current labs reality + document ideal end-state (connect-labs#212)

[jjackson]

Summary

Companion to jjackson/connect-labs#212 (filed). Three labs-side gaps surfaced during the malaria-itn-app/20260521-1400 Phase 8 republish (solicitation 3140) need inline workarounds in this skill until #212 ships.

Cross-ref

Labs issue: jjackson/connect-labs#212 — "solicitation MCP: align proxy inputSchema with deployed validation; add framing + criterion.id as first-class." Four asks: (1) atom inputSchema vs server validation alignment, (2) questions[].framing as first-class structured field, (3) evaluation_criteria[].id documented as required (or auto-derived from name), (4) is_public: true solicitation detail pages truly unauthenticated.

What this PR changes

Step 6 — wire-shape fallback

Atom inputSchema declares {program_id, data: {...solicitation fields...}}. Deployed labs server expects fields flat at JSON-RPC params level and rejects the data envelope with unknown fields: ['data']. Documents both paths:

• Preferred: call MCP atom as documented (will start working once the proxy/server alignment lands per ocs: parallelize collection-indexing status probes (PR 0i — perf lens) #212).
• Fallback: direct JSON-RPC POST to https://labs.connect.dimagi.com/mcp/ with flat-fields payload + Authorization: Bearer ${LABS_MCP_TOKEN}. Body shape documented inline.

questions[].framing — inline-prefix convention

Server rejects a structured framing key. Until #212 lands, framing goes inline in text using the literal anchor Why we're asking: <framing>\\n\\n<actual-prompt>. The blank-line gap is load-bearing — solicitation-review parses the framing back out on this anchor. Documented in both the payload table (Step 2) and the question shape (Step 4).

evaluation_criteria[].id — required field

Server enforces id even though the atom inputSchema doesn't currently declare it. Added id as REQUIRED in the criterion shape with slugify(name) as the derivation fallback. Documented in the payload table (Step 2) and the criterion shape (Step 3).

Step 7a verifier — round-trip instead of curl-the-public-URL

The original Step 7a curl'd the public URL and grep'd for rendered sections. Labs now 302s the public-detail page to /labs/login/ even when is_public: true, so vanilla curl gets the login page. Rewritten to use get_solicitation round-trip as the structural verifier:

• Read every persisted field via mcp__connect-labs__get_solicitation.
• Assert title / description (≥80% length) / scope_of_work (string, ≥80% length) / dates / contact_email / is_public / status / connect_opportunity_id all round-trip.
• Assert each question has id + text (with Why we're asking: anchor) + required + type.
• Assert each criterion has id + name + weight + scoring_guide + linked_questions; sum(weights) == 100.

Any miss → [BLOCKER] naming the missing/mutated field + probable cause. Provides the same drift detection at the persistence layer instead of the rendered layer.

Removal plan when #212 ships

Change Log entry documents the rollback path: drop the inline workarounds, emit framing as a structured key, drop the wire-shape fallback paragraph, restore the curl-the-public-URL verifier as a second post-round-trip check (the original Step 7a, surfaced as the structural backstop for the rendered layer rather than just the persistence layer).

Test plan

• Re-run /ace:step solicitation-create malaria-itn-app/20260521-1400 against the new SKILL.md; verify the round-trip verifier passes.
• When connect-labs#212 ships, re-test: structured framing field round-trips; atom-as-documented call succeeds without flat-shape fallback; curl-the-public-URL verifier runs cleanly.

🤖 Generated with Claude Code