docs(merge): Tier-1 merge readiness audit (17 PRs, #338-#355)#356
Open
ctol3r wants to merge 2 commits into
Open
docs(merge): Tier-1 merge readiness audit (17 PRs, #338-#355)#356ctol3r wants to merge 2 commits into
ctol3r wants to merge 2 commits into
Conversation
Doc-only PR. Comprehensive audit of the institutional convergence
stack ahead of the Tier-1 merge train.
Sections:
1. Audit-set integrity flag — calls out that the operator-supplied
14-PR list omits 3 stack-base PRs (#342, #344, #345) that the
audit set depends on; effective set is 17 PRs
2. Merge state — every PR confirmed CLEAN + MERGEABLE
3. Dependency graph — topological tiers A/B/C/D
4. File-collision matrix — 2 files touched by multiple PRs but
all on the SAME linear stack (rebase, not conflict)
5. Risk audit — the seven concrete checks the brief named:
route collisions / schema conflicts / replay contract drift /
well-known path conflicts / auth boundary regressions /
build-order failures / runtime namespace collisions.
Verdict on each: zero or MEDIUM with named mitigation.
6. Blocker matrix — Codex SAFE per PR (CRITICAL); isPublicRoute()
allowlist (MEDIUM); #339 cache flush (MEDIUM); #348 actorId
semantics change (MEDIUM); #344 CI nudge (LOW); rebase
mechanics (LOW)
7. Safe merge order — Tier A independent (8), Tier B/C/D
stacked (4/3/2)
8. Risky merge points — per-PR watch items
9. Deploy sequencing plan — exact codex exec + gh pr merge +
cache-flush SQL commands for each phase
10. Operator pre-merge checklist
11. Success condition — 17 PRs merged, production verifier
surfaces respond 200, cross-surface convergence verifier
returns exit 0
12. Out of scope
The doc is the operator runbook for the merge train; combine with
docs/ops/production-promotion-protocol.md (#338) for promotion to
production.
After auditing apps/web/lib/auth/roles.ts on origin/main against the new verifier-continuity surfaces in #349, #345, #355: - .well-known/* surfaces ✅ already covered by /^\/\.well-known(\/.*)?$/ - /api/receipt/* ✅ covered by /^\/api(\/.*)?$/ - /verify ✅ covered by /^\/verify(\/.*)?$/ - /trust⚠️ falls through (no pattern matches, no required role) — reachable but implicit This PR resolves the lone gap by adding an explicit /^\/trust(\/.*)?$/ pattern to PUBLIC_ROUTE_PATTERNS so the verifier-continuity intent is documented in the allowlist rather than relying on the middleware's neither-public-nor-protected fall-through. Eight new rows in middleware.test.ts pin the public status of every verifier-continuity surface so a future allowlist regression fails CI. MERGE_READINESS.md updated: - §5.5 verdict downgraded MEDIUM → LOW (was: blocker; now: resolved) - §6 blocker matrix row crossed out (resolved in this PR) Files: apps/web/lib/auth/roles.ts +1 line (one regex) apps/web/__tests__/middleware.test.ts +8 rows (test matrix) MERGE_READINESS.md §5.5 + §6 updates Validation: pnpm exec vitest run __tests__/middleware.test.ts → 44/44 pnpm turbo run build --filter @vitalcv/web → 13/13 tasks
ctol3r
pushed a commit
that referenced
this pull request
May 13, 2026
Two new forensics docs answering the operator's deployment-topology
questions in one place:
APEX_DEPLOYMENT_FORENSICS.md
- Proves apex (vitalcv.com) deploys apps/web (not apps/marketing)
via live probe of /api/health returning service: "web"
- Identifies the two Vercel projects (apex web vs separate
marketing) and their per-app vercel.json overrides
- Critical operational finding: apex /api/health reports
clerk.enabled: false / mode: "none" — the production Vercel
project is missing NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY +
CLERK_SECRET_KEY env vars. /sign-in 500s as a result.
- Independent of the 20-PR merge queue: this Clerk env gap is
operator-side configuration, not code
- 10 sections + recommendations
ROUTE_OWNERSHIP_MAP.md
- Proves every named verifier route lives in apps/web (not
apps/marketing) by filesystem inspection
- /verify exists in both apps but they own different concepts:
apps/web/app/verify/page.tsx = institutional inspector (#345),
apps/marketing/app/verify/[shareId]/page.tsx = share-link
viewer (different domain, different concern)
- Eight of nine institutional routes are exclusive to apps/web
- Confirms: when the merge train lands, every new route deploys
automatically to apex — no project-rebinding, no domain
reconfig, no migration required
- 9 sections + summary table
Together with the existing BUILD_ARTIFACT_VERIFICATION.md
(physical build output) and MERGE_READINESS.md (#356, merge-train
sequencing), this PR is now the complete operator-facing answer
to: "what does apex serve, what's the build output, what's the
merge order, and what's the deployment risk?"
No code changes. Three doc files at repo root.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Doc-only PR. Operator runbook for the Tier-1 merge train covering the 14 PRs the brief enumerated plus 3 stack-base PRs (#342, #344, #345) the audit list omitted but the dependency chain requires.
Effective merge set: 17 PRs. All CLEAN + MERGEABLE at audit time.
Twelve sections
codex exec+gh pr merge+ cache-flush SQLCritical findings
isPublicRoute()allowlist may not cover new verifier surfacesmetadata.actorIdsemantics (org → person)Scope
MERGE_READINESS.md(456 lines)Validation
origin/mainSHA9eb5cdeegh pr view --json filesper PR