feat(clearfolio): expose queryable capability readiness to planners

[cursor]

Buyer and operator impact

Startup logs are not a planner control surface. This bounded Clearfolio slice gives authenticated operators the same non-secret readiness record that the planner UI uses, prevents avoidable upload/view work when local conversion configuration is unsafe or unavailable, and keeps whole-process /api/health liveness independent from the optional document-viewer capability.

This is a child of #502 and does not close #489.

Exact current stack

• protected develop: 2c328875e00e86537df3e965170be80532571cad;
• exact live parent feat(clearfolio): expose capability readiness without failing liveness #502: feat/clearfolio-capability-readiness-489@9e465a2cdebc6769717914160f24ecb2b339e163;
• exact contributor head: abcd68c20ef073818d1869f2a5e891fb99248a05;
• branch: cursor/bc-7295b3cf-ffc9-426a-b244-d93d50dc6d53-190f;
• Ready/non-Draft and mechanically mergeable at the latest fresh refetch; and
• no qualifying independent current-head/last-push approval.

The current child remains stacked directly on the exact #502 head. Any parent, contributor-head, protected-base, review, or check movement invalidates revision-sensitive evidence until freshly revalidated.

Production contract

• Authenticated GET /api/capabilities returns {capabilities:{clearfolio:{ready,mode,reason,action}}} from configuration-only evaluation. Anonymous callers receive 401; the query performs no provider DNS/HTTP request.
• Attachment upload and view fail closed with HTTP 503 and the same bounded capability record when local Clearfolio configuration is unavailable/unsafe, before upload bytes or provider artifact transport is consumed.
• Persisted non-succeeded attachments follow the same unready-capability contract: local unavailability is reported first as actionable 503 remediation rather than an ambiguous 409 status-only response.
• The 산출물 dialog displays the concrete remediation action, disables the upload control when a known-unready record is returned, and keeps the server authoritative if the advisory readiness request itself fails.
• Whole-process GET /api/health stays liveness-only {ok:true} so an optional conversion dependency cannot take the planner process out of service.
• Tests cover weak HMAC configuration, authenticated/anonymous capability access, upload and persisted-view 503 short-circuits with provider fetch replaced by a throwing function, and client-side notice behavior.

Current informational review observations do not demonstrate product defects: already-converted artifacts intentionally stop opening when the locally configured trust boundary becomes unready; a failed advisory capability query leaves the client input enabled but the server remains authoritative; authenticated capability 401 follows the existing global unauthorized-session contract; capability readiness is process-bound and consistent with startup logging; and the duplicate local readiness parse is negligible. They are not promoted into blockers without a realistic failing reproduction.

Current repaired finding and evidence

A current-head review observation exposed a real contract mismatch on the predecessor: view checked attachment status before local Clearfolio readiness, so a persisted PENDING attachment in unconfigured production returned 409 instead of the documented actionable 503.

• RED exact head 96af8abfa0d9c73671cfad1d0d21eedd06e7adc0: Server Tests run 33035773372 reproduced 409 !== 503 with provider fetch replaced by a throwing function.
• Fix: move the local Clearfolio capability gate ahead of the attachment-status gate; semantic source delta from RED to GREEN is one insertion/one deletion in server/app.mjs.
• GREEN exact contributor head abcd68c20ef073818d1869f2a5e891fb99248a05: Server Tests run 33036284907 completed successfully; unit-and-api and cloud-e2e both passed, including the new persisted-pending view regression.
• Current-head OSV checks are successful; no current-head failing check was observed in the latest refetch.

These results are behavioral evidence only, not merge-authorizing exact-head evidence: the current repository Server Tests workflow still checks out synthetic pull-request merge revision 2f1dd611f0bebe129aca611515a776cee5160988 rather than proving the immutable contributor SHA. ScopeWeave #523 owns repository-native exact-head Server Tests/coverage integrity; ContextualWisdomLab/.github#1222 owns organization-reusable SAST/Security exact-head integrity. Pending, queued, skipped-required, cancelled, absent, neutral, failed, stale, predecessor, synthetic-only, status-only, author-only, or model-only evidence is non-authorizing.

Stack and merge boundary

Do not integrate independently of #502/#538/#498/#493 and their protected predecessors. After the prerequisite stack reaches protected develop, reconcile this bounded semantic delta onto the resulting protected head and regenerate every then-applicable exact-head deterministic/browser/owned statement-branch-function-line coverage/docstring/CodeQL/SAST/security/dependency/supply-chain/package/SBOM/provenance/review gate. Require zero valid unresolved defect findings and a qualifying independent current-head/last-push approval under live governance.

Remote Clearfolio reachability, retry/idempotency, persisted provider lifecycle, and final release acceptance remain #489 work; do not duplicate the Clearfolio repository's source authority or invent a second wire contract.

Refs #489 #502 #523

[devin-ai-integration]

Devin Review found 3 potential issues.

[devin-ai-integration]

Devin Review found 2 new potential issues.