[Product Completion] Establish the Clearfolio GA closure program and consolidate the live PR queue #484

Purpose

This is the coordination and closure authority for taking Clearfolio from its current MVP/buyer-demo state to a commercially releasable document-viewer product. It does not duplicate the implementation issues listed below. It defines the order, evidence, queue discipline, and release boundary needed to finish them.

The canonical repository baseline will live at:

docs/product-technical-gap-baseline.md

Exact live snapshot

Observed at 2026-08-20 22:00 KST against protected main@06633a25109c62e24a7015ae04fb9f6e0a246f7e:

• 85 open pull requests;
• 25 draft pull requests;
• 76 pull requests targeting main;
• 9 stacked or non-main-base pull requests;
• 18 open issues before this coordination issue;
• no existing docs/product-technical-gap-baseline.md on protected main.

This inventory is evidence of substantial engineering activity, but it is also a release blocker: multiple parallel PRs cover the same authority boundary, many PRs explicitly ship value types only, several child PRs depend on unmerged parents, and current-head review/approval cannot converge while equivalent replacements remain open.

Current shipped truth

Protected main still describes and behaves as an MVP rather than a GA product:

• README.md calls the repository an MVP backend;
• / is a buyer-demo shell with static demo data and screenshot/diligence evidence;
• production OIDC/JWT verification is not shipped; tenant headers/HMAC remain a scaffold;
• conversion jobs are process-local by default and are lost on restart;
• artifact and analytics continuity use single-process append-only files rather than a durable multi-instance store;
• PDF.js is the only currently qualified renderer metadata; Office support is not production-qualified;
• stated SLOs are targets, not yet release evidence from a representative deployment;
• tagged release acceptance, reproducible provenance, supported-format fidelity, backup/restore, DR, and a complete operator/customer workspace are not yet jointly proven.

Release-blocking workstreams

P0 — Queue and governance convergence

1. Classify every open PR as exactly one of:
   • MERGE_CANDIDATE_CURRENT_MAIN;
   • STACKED_DEPENDENT;
   • SUPERSEDED_OR_DUPLICATE;
   • BLOCKED_EXTERNAL_REVIEW;
   • REQUIRES_RECONSTRUCTION.
2. Keep one canonical writer for each semantic/path boundary.
3. Close redundant generated PRs after preserving any unique tested behavior.
4. Do not treat predecessor-head checks or automated/model comments as current-head independent approval.
5. Resolve the independent reviewer route in [Governance Gap] Establish an observable independent-review and CODEOWNERS route #321 and orphaned workflow identities in [Fleet incident] Disable orphaned one-shot and PR-specific workflow identities #423/test(automation): detect orphaned workflow registry identities #424.
6. Prefer buyer-complete vertical slices over additional disconnected value-type PRs.

Immediate duplicate/convergence groups requiring explicit disposition include:

• runtime secret/configtree migration: 🛡️ Sentinel: [security improvement] Remove environment variable fallbacks #463, 🛡️ Sentinel: [HIGH] Fix environment variable secrets loading #470, 🛡️ Sentinel: [security improvement] 환경 변수 폴백 매핑 제거 #479, 🛡️ Sentinel: [CRITICAL] 환경 변수 기반 시크릿 주입 취약점 제거 #482, 🛡️ Sentinel: [security improvement] 런타임 시크릿 설정 방식 안전화 (configtree 적용) #483, plus the ordered registry stack [Security Gap] Move runtime HMAC secrets behind a KV credential registry #319/feat(security): define provider-neutral credential registry contract #344/feat(security): add standalone directory credential registry #354/fix(security): consume tenant-claim signing key through credential registry #433;
• AdminController authorization/tenant isolation: fix(security): rebuild tenant-scoped admin authority on current main #455, 🛡️ Sentinel: [CRITICAL] Fix missing authentication on admin endpoint #469, 🛡️ Sentinel: [CRITICAL/HIGH] Fix cross-tenant metadata leakage in AdminController #475, 🛡️ Sentinel: [CRITICAL] Fix AdminController missing authorization #478, 🛡️ Sentinel: [CRITICAL] Fix AdminController Missing Authorization and Tenant Isolation #480;
• speculative token parser rewrites: ⚡ Bolt: [성능 개선] #462, ⚡ Bolt: [성능 개선] ArtifactLinkService 토큰 파싱 로직 최적화 #468, ⚡ Bolt: [performance improvement] 토큰 파싱 성능 최적화 및 String.split 제거 #474 versus benchmark-first issue [Performance] Benchmark and bound security-critical token parsing before optimization #444;
• tenant-scoped analytics: fix(security): reconcile tenant-scoped analytics query on current main #432 and fix(security): rebuild tenant-scoped analytics query on current main #456;
• current-main reconstruction/replacement chains documented in the individual PR bodies.

P1 — Production product authority

• Replace the buyer-demo shell and synthetic authority with a tenant-aware production workspace under [Product Gap] Remove buyer-demo shell and hard-coded demo authority from production UI #317.
• Preserve demo fixtures only in an isolated demo/test profile; never ship them as production authority.
• Establish executable Figma–Storybook component/state authority under [Product Gap] Establish executable Figma–Storybook design-system authority #476, with runtime token parity, interaction tests, WCAG 2.2 AA evidence, and no customer content/secrets in fixtures.
• Provide complete customer and operator journeys: upload, progress, preview, retry, cancellation, download, deletion, audit evidence, and actionable recovery copy.

P1 — Production identity, tenancy, and credentials

• Complete provider-neutral OIDC/JWT federation under [Product Gap] Add production OIDC/JWT identity federation with tenant-scoped authorization #314, not only verifier/value primitives.
• Validate issuer, audience, signature algorithm, key generation/rotation, expiry, revocation, tenant/role mapping, and failure semantics according to OpenID Connect Core, OAuth 2.0 Security BCP (RFC 9700), and JWT BCP (RFC 8725).
• Complete [Security Gap] Move runtime HMAC secrets behind a KV credential registry #319 with KV/KMS-backed runtime credential authority, compatibility-window rotation, restart/replica behavior, least privilege, and no raw-secret telemetry.
• Enforce storage-level tenant isolation for jobs, artifacts, analytics, audit, and administration; application-only filtering is insufficient for GA.

P1 — Durable execution and lifecycle

Complete #312 and #263 as integrated runtime behavior rather than a collection of disconnected records:

• PostgreSQL-backed 3NF job/attempt/lease/retry/dead-letter/outbox/inbox/idempotency state;
• transactional acceptance and dispatch;
• generation-fenced worker publication;
• bounded admission/backpressure with explicit retry guidance;
• durable cancellation and cancellation-versus-completion race semantics;
• restart, duplicate-delivery, stale-worker, and multi-instance tests;
• object-store artifact metadata, checksums, retention, tombstones, deletion receipts, retryable cleanup, and tenant-safe recovery;
• hot-partition-resistant key/partition strategy;
• backup, restore, point-in-time recovery, and disaster-recovery rehearsal.

All new database object names must use two-or-more-word snake_case names and preserve third normal form.

P1 — Conversion security and fidelity

Complete #5 / #306 before advertising Office support:

• sandboxed sidecar or authenticated remote converter outside the API process trust boundary;
• strict MIME/signature/package/active-content/embedded-object/external-resource limits;
• no macro execution or external fetch;
• CPU, RAM, file, page, process, queue, and wall-clock budgets;
• malware/quarantine and controlled CDR policy where applicable;
• immutable converter/runtime version, license, SBOM, provenance, and policy identity;
• authorized Korean/English DOCX/XLSX/PPTX fidelity corpus with layout, fonts, tables, charts, pagination, accessibility, and failure taxonomy;
• source-to-PDF evidence, deterministic regression thresholds, and clear unsupported-format behavior.

PDF output and viewer behavior must be assessed against WCAG 2.2 / ISO/IEC 40500:2025 and, where an accessible-PDF claim is made, ISO 14289-2:2024 (PDF/UA-2). Passing conversion or process exit alone is not fidelity or accessibility evidence.

P2 — Viewer correctness and accessibility

• Complete PDF.js generation ownership, active cancellation/destruction, rapid multi-generation/error-state coverage, focus ownership, and unhandled-rejection proof under [Product Gap] Make PDF viewer rendering generation-safe under retry and navigation #322/fix(viewer): suppress stale PDF render publication #323/fix(viewer): actively cancel superseded PDF.js work on current parent #445.
• Complete focus and keyboard contracts under [Accessibility Gap] Make keyboard focus indicator robust to background contrast #324/fix(accessibility): reconcile robust focus appearance after #270 #334 and related current-main accessibility successors.
• Provide exact textual alternatives and deterministic tests for every loading, ready, failed, not-found, invalid-document, network-error, blocked, retry, cancellation, and deletion state.
• Validate desktop, tablet, phone, reduced-motion, forced-colors, keyboard-only, and representative screen-reader journeys.

P2 — Versioned API and CWL ecosystem integration

Complete #315 as a release contract, not isolated checks:

• one canonical OpenAPI document and route/DTO/error/security parity;
• stable unique operationId values, explicit version negotiation, compatibility/breaking-change gate, and schema provenance;
• generated and tested JavaScript/TypeScript, Python, and/or Java clients where consumers require them;
• standalone deployment and naruon-module compatibility through versioned APIs/events rather than direct database coupling;
• idempotency, pagination, rate-limit, retry, and error semantics documented and exercised;
• upgrade/deprecation policy bound to tagged releases.

Use the latest published OpenAPI Specification (3.2.0 at this snapshot) unless an implementation-tooling compatibility ADR deliberately pins an earlier revision.

P2 — Observability, SLOs, and operations

• Turn telemetry value objects into real privacy-safe OpenTelemetry traces, metrics, logs, and exemplars.
• Measure request latency, submit-to-first-frame latency, queue depth, worker lag, conversion duration by qualified format, saturation, retry/DLQ, artifact delivery, storage failures, and tenant-safe audit outcomes.
• Define and prove SLI/SLO/error-budget semantics in a representative multi-instance deployment.
• Add startup/readiness dependencies, capacity signals, graceful shutdown, rolling-upgrade, incident response, runbooks, and restore drills.
• Do not place tenant IDs, subject IDs, filenames, document content, tokens, or uncontrolled exception text into telemetry.

P2 — Release, supply chain, and commercial operations

• Complete tagged release acceptance under test(release): require tagged acceptance on current main #427 and bind exact source, OpenAPI bytes, dependency graph, SBOM, provenance, checksums, and release artifact.
• Produce SPDX 3.0.1/CycloneDX-compatible SBOM evidence and SLSA 1.2 provenance/attestation where the toolchain supports it.
• Rehearse clean install, upgrade, rollback, backup/restore, and dependency/license policy.
• Publish a versioned CHANGELOG and support matrix; do not represent Unreleased or buyer-demo evidence as GA.
• Define supported deployment profiles, SLA/support boundaries, vulnerability response, retention/deletion policy, data residency, SOC 2/CSAP control evidence, and customer onboarding/migration.

Canonical evidence states

Every item in the baseline must use one of these states:

SHIPPED_ON_MAIN
ACTIVE_PR
OPEN_GAP
EXTERNAL_BLOCKER
SUPERSEDED
NOT_APPLICABLE

A document, issue, PR body, generated value object, or passing predecessor build is not SHIPPED_ON_MAIN until the corresponding behavior and current exact-head evidence are on protected main.

GA exit criteria

Clearfolio is not GA until all of the following are true on one tagged source revision:

• open PR queue has no duplicate/superseded candidates and every remaining stack has an explicit dependency order;
• required exact-head CI, Security Scan, SAST, fuzz, coverage, Javadoc, review, and branch-protection gates are terminal-success;
• production OIDC/JWT, KV/KMS credential authority, and storage-level tenant isolation are operational;
• accepted jobs, outbox/inbox, worker leases, retries, cancellation, artifacts, audit, analytics, and deletion survive restart and multi-instance races;
• every advertised file type has sandbox, security, fidelity, performance, accessibility, licensing, and provenance evidence;
• PDF viewer behavior is generation-safe and WCAG 2.2 AA evidence is complete;
• API, generated-client, standalone, and naruon integration contracts pass compatibility tests;
• OpenTelemetry-backed SLO evidence, capacity tests, backup/restore, rollback, and DR rehearsal pass;
• versioned release artifact, SBOM, provenance, checksums, CHANGELOG, deployment guide, support matrix, and security response policy are published;
• README/PRD/TRD/ADR/architecture/operability documents describe shipped truth rather than active-PR intent;
• docs/product-technical-gap-baseline.md contains no unresolved P0/P1 release blocker.

Standards and primary references

• OpenAPI Initiative. (2025). OpenAPI Specification 3.2.0. https://spec.openapis.org/oas/v3.2.0.html
• OpenID Foundation. (2023). OpenID Connect Core 1.0 incorporating errata set 2. https://openid.net/specs/openid-connect-core-1_0.html
• Lodderstedt, T., Bradley, J., Labunets, A., & Fett, D. (2025). Best current practice for OAuth 2.0 security (RFC 9700). IETF. https://www.rfc-editor.org/rfc/rfc9700.html
• Sheffer, Y., Hardt, D., & Jones, M. (2020). JSON Web Token best current practices (RFC 8725). IETF. https://www.rfc-editor.org/rfc/rfc8725.html
• World Wide Web Consortium. (2024). Web Content Accessibility Guidelines (WCAG) 2.2. https://www.w3.org/TR/WCAG22/
• International Organization for Standardization. (2024). ISO 14289-2:2024: PDF/UA-2. https://www.iso.org/standard/82278.html
• OpenTelemetry Authors. (2026). OpenTelemetry Specification 1.59.0. https://opentelemetry.io/docs/specs/otel/
• SLSA Community. (2025). SLSA Specification 1.2. https://slsa.dev/spec/v1.2/
• SPDX Workgroup. (2024). SPDX Specification 3.0.1. https://spdx.github.io/spdx-spec/
• OWASP Foundation. (n.d.). File Upload Cheat Sheet. https://cheatsheetseries.owasp.org/cheatsheets/File_Upload_Cheat_Sheet.html

Customer next action

Review completion by workstream, not by raw PR count. The next operational action is to classify and collapse the live PR queue, land the production authority/durability/identity foundations in dependency order, and then qualify file-format fidelity and the tagged release on the same integrated revision.