feat(clearfolio): expose capability readiness without failing liveness

[seonghobae]

Buyer and operator impact

ScopeWeave keeps whole-process liveness independent from its optional Clearfolio integration while giving operators an actionable, non-secret capability-readiness signal. Planning remains live when document conversion is unavailable, while operators can distinguish unconfigured production, explicit development mock, valid provider configuration, and unsafe configuration.

This is a bounded follow-up slice of #489. It is stacked on #538 and does not close #489.

Exact current stack and scope

Current parent: cursor/bc-d8443854-d031-4b84-b085-56f439fcbf05-df45@7b4b9fd0991673263b0cec16ee1f7f2f7e01fa60 (#538).
Current child head: 96f217715783c2e906c916113aad93ab890d9212.

The parent advanced from the prior artifact-policy snapshot through a substantive reconciliation with current #498. Current #502 was rebuilt from the exact new #538 tree and only the seven readiness-owned semantic paths were overlaid; shared CHANGELOG.md and package.json were merged deliberately so #538's artifact-origin policy and protected toast-accessibility registrations are retained. Fresh parent→child comparison is ahead-only, zero-behind, has 7b4b9fd0... as the exact merge base, and contains exactly seven readiness-scope files.

• CHANGELOG.md (+4/-0 relative to fix(clearfolio): require canonical artifact-origin allowlist entries #538);
• docs/deploy.md (+25/-1, replacing the liveness-only health sentence with explicit optional-capability readiness separation while preserving fix(clearfolio): require canonical artifact-origin allowlist entries #538 artifact-origin operations guidance);
• docs/doctoring/clearfolio-capability-readiness.md;
• package.json;
• server/clearfolio.mjs;
• server/server.mjs;
• tests/unit/clearfolio-capability-readiness.test.mjs.

The branch preserves #538's canonical CLEARFOLIO_ARTIFACT_ORIGINS validation and regressions, parent Clearfolio artifact-origin/operator documentation, current provider response/resource hardening, protected Microsoft Project XML behavior, and toast accessibility coverage. No database, auth/session, attachment-refresh engine, dependency lockfile, workflow, scanner suppression, contextual-orchestrator runtime contract, or branch-protection artifact is changed by the final parent→child delta.

Readiness contract

clearfolioCapabilityStatus() performs configuration-only evaluation and deliberately makes no DNS, HTTP, authentication, or provider-health request.

• unconfigured production returns ready=false, mode=unavailable, stable reason clearfolio_not_configured, and a concrete non-secret remediation action;
• explicit SCOPEWEAVE_DEV=1 mock mode returns ready=true, mode=development_mock, with an action requiring a real provider before production;
• valid production provider configuration returns ready=true, mode=provider;
• invalid provider transport, weak or missing HMAC configuration, or invalid CLEARFOLIO_ARTIFACT_ORIGINS degrades only the Clearfolio capability with a stable reason and safe next action; and
• readiness reuses the runtime provider and artifact-origin validators, so it cannot approve configuration the adapter rejects.

At startup server/server.mjs emits one structured capability.readiness record containing only capability, readiness, mode, stable reason, and fixed remediation text. Secret values, URLs, provider responses, and transport diagnostics are not logged.

Liveness separation

GET /api/health remains liveness-only and returns HTTP 200 with { "ok": true } when optional Clearfolio is unavailable. The regression runs a fresh process per configuration, replaces fetch with a throwing function, and proves readiness evaluation performs no provider traffic while liveness remains healthy.

Current exact-head evidence boundary

All workflow/check/review evidence predating 96f217715783c2e906c916113aad93ab890d9212 is historical and non-authorizing. Fresh exact-head repository and organization workflows are required. Pending, queued, skipped-required, neutral, absent, stale, predecessor, status-only, author-only, or model-only evidence is non-passing.

This PR remains Draft until the unchanged current head has terminal-success applicable checks, exact owned-production coverage evidence, zero valid unresolved findings, and qualifying independent current-head approval under the live policy.

Remaining #489 work

This slice does not complete the Clearfolio production lifecycle. Protected integration, durable provider lifecycle/persistence controls, incident and recovery evidence, release acceptance, and any remaining provider-contract obligations remain separate work.

Merge gate

Do not integrate before #538, #498, #493, and their protected predecessors. After the parent stack reaches protected develop, retarget or reconcile this bounded semantic diff against the resulting protected head, rerun all then-applicable repository and organization gates, and require qualifying independent current-head approval. No predecessor-head, author-only, status-only, synthetic-only, or model-only evidence transfers.

Refs #489

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: e4bac7d2-ac37-424c-9fd3-22bcaaf7acfb

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[cursor]

Review (head fa9a747f2b24857d4ca7df3207434242c9853457)

The seven-file parent→child delta matches the stated contract: clearfolioCapabilityStatus() is configuration-only, /api/health stays {ok:true}, the development mock is named development_mock, and invalid provider/HMAC/artifact-origin configuration degrades only Clearfolio with a secret-free next action. Local tests/unit/clearfolio-capability-readiness.test.mjs is 5/5 on this head after installing runtime dependencies.

No must-fix in the startup-log slice. This review does not approve and does not authorize merge. The PR is still Draft; queued/skipped/pending checks and CodeRabbit's draft skip are non-passing. Do not integrate before #504, #498, and #493. Predecessor-head evidence does not transfer.

Residuals (do not block this slice; they are the buyer gap)

1. Startup logs are not a planner surface. A user who opens 산출물 can still pick a file and only then see a generic 502. Operators without container stdout cannot query the same record. Successor on cursor/bc-7295b3cf-ffc9-426a-b244-d93d50dc6d53-190f adds authenticated GET /api/capabilities, attachment HTTP 503 with the same payload, and a dialog notice that disables upload.
2. HMAC-invalid action was untested on this head. The successor adds that case plus anonymous 401 vs authenticated query.
3. docs/deploy.md still says ::1 while the runtime hostname is [::1]. Fixed in the successor.

Keep #489 open. This slice still does not claim remote reachability, retry/idempotency, or the persisted provider lifecycle.

  

_{Sent by Cursor Automation: Fix Issues}