Docs: Vercel 廃止に合わせて開発文書と RTM を現状に揃える - #321
Open
jasonhnd wants to merge 4 commits into
Open
Conversation
promote: 日英の公開文書に揃える (v2026.08.20-2)
…output GitHub Pages is already the live production deployment: finwiki.zksc.io is a CNAME to jasonhnd.github.io on the Pages A records, and the live response header is server: GitHub.com. Vercel was a parallel shadow build that served no production traffic. assertPinnedBun() read and validated vercel.json as step 0 of the verification pipeline, so the config deletion and the runner change have to land together or every gate breaks at startup. The .bun-version and packageManager pin checks are unchanged. Collapsing the default --out from _vercel_public to _site also makes pull request verification and the Pages deploy assemble into the same target; required-verification.yml runs bare `bun run verify` while deploy.yml passes --out _site explicitly. The tests keep _vercel_public only as negative assertions proving the name is now rejected. Co-authored-by: Jason@HND <jasonhnd@users.noreply.github.com>
.vercel and _vercel_public can no longer be produced by this repository, so the shared corpus walk exclusions, the JSON sweep, the opinion audit walk and .gitignore no longer need to skip them. _site stays excluded because it is still the assembly target. provenance_completeness_audit.ts keeps its defensive prefix check but points it at _site, which is the directory that can now appear in a worktree. Anyone holding a stale _vercel_public/ or .vercel/ directory should remove it; a leftover copy would now be walked, and index:counts, wiki:audit and release:check would fail loudly rather than pass silently. Co-authored-by: Jason@HND <jasonhnd@users.noreply.github.com>
… boundary The Vercel shadow build is retired, so eleven active documents no longer describe a real system. Correct the deployment runbook targets table, the release-gate spec, ARD, the Astro site architecture, the AI discovery architecture and surface specs, the toolchain reference, the incident runbook, the QA checklist, NFR-001, and RTM rows NFR-001 and NFR-014. _site is now the default as well as the only approved output, so passages that presented `--out _site` as a separate Pages-parity invocation now say the bare canonical command already produces the Pages artifact. Historical records keep their Vercel mentions: the code/doc alignment audit, the existing drift-audit rows, the 2026-06 development plan, and the archived site development plan. The drift audit gains a row for this boundary change and an allowed-historical example. active_doc_stale_scan.ts gains a vercel-deploy-path pattern so `_vercel_public`, `vercel:build` and `vercel.json` cannot silently return to an active document, with reviewed allowlist entries for the three historical docs that legitimately name them. The archive directory was already allowlisted wholesale. Co-authored-by: Jason@HND <jasonhnd@users.noreply.github.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
jasonhnd
marked this pull request as ready for review
September 1, 2026 06:07
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.
Documentation-sync half of the Vercel decommission. Stacked on #320 — until that merges into
pre, this PR's diff also shows the two tooling commits. Merge #320 first, then this diff reduces to docs plus the stale-scan guard.Goal
Bring active developer documentation in line with the post-Vercel reality: GitHub Pages is the only deployment target and
_sitethe only approved assembly output.Why this is a real problem and not cosmetics
Neither
docs:auditnordocs:stalefailed on this drift. No document links tovercel.jsonas a file, andSTALE_PATTERNShad no Vercel rule. Eleven active documents would have gone on describing a build path that no longer exists, silently, which is precisely the drift class the repository's stale-scan mechanism exists to prevent. So this PR both fixes the text and closes the hole that let it stay invisible.Corrected active documents
08-operations/deployment-runbook.md_site05-functional-specs/release-gate.md_siteis the only valid output directory; the Vercelbunx bun@<version>bullet became a plain runner-startup pin statement; unsafe-output guidance names only_site04-architecture/ard.md_site04-architecture/astro-site-architecture.md_siteis accepted; the verification wrapper is no longer labelled "Vercel/GitHub Pages"04-architecture/ai-discovery-architecture.md_sitetree05-functional-specs/ai-discovery-surface.mdtxt_route_audit.tsvalidates against_site06-implementation/toolchain.md_site08-operations/incident-runbook.md07-quality/qa-checklist.md_site03-requirements/nfr.md03-requirements/rtm.mdTwo further corrections beyond the eleven:
04-architecture/astro-5-to-7-upgrade-plan.mdstated "Vercel runs rootbun run vercel:build" and cited Vercel's Node version as evidence for the Astro v6 floor. Both are now false, so the build-path row and the Node-floor row were corrected in place. The rest of the upgrade reference is still valid, so it was not archived.05-functional-specs/ai-surface-consumability-design.mddescribed static JSON as working on "GitHub Pages / Vercel static hosting". Generalised to "GitHub Pages and any other static host", which is both accurate and more useful than naming a host we no longer use.Since
_siteis now the default as well as the only approved output, passages that presentedbun run verify --out _siteas a separate Pages-parity invocation now state that the bare canonical command already produces the Pages artifact, and thatdeploy.ymlpasses the flag explicitly for the same result.Regression guard
tools/active_doc_stale_scan.tsgains avercel-deploy-pathpattern matching_vercel_public,vercel:build, andvercel.json, so the claim cannot silently return to an active document. Three reviewed allowlist entries cover the historical documents that legitimately name those tokens;docs/99-archivewas already allowlisted wholesale.The pattern deliberately targets those three concrete artifacts rather than the bare word "Vercel". A broad
/vercel/iwould fire on legitimate prose — including the corrected upgrade-plan sentence in this very PR, and the wiki body entries that discuss Vercel as an x402 / edge-payment company. The tradeoff is that a future sentence like "Vercel builds the site", written without any of the three tokens, would not be caught.tools/active_doc_stale_scan.test.tsextends both existing cases: the negative fixture now includes a Vercel build claim and expectsvercel-deploy-pathin the finding set, and the archive fixture includes Vercel history to prove the allowlist still exempts it.Historical records deliberately left alone
07-quality/code-doc-alignment-audit.md, the existing rows in07-quality/documentation-drift-audit.md,01-strategy/next-development-plan.md, and99-archive/site-development-plan.mdkeep their Vercel mentions. They are dated evidence of past state, which the repository's active-vs-historical rule permits.07-quality/documentation-drift-audit.mdgains one appended row recording this deployment-boundary change, plus an allowed-historical example for retired Vercel references.Validation
All run locally on Bun 1.3.14 matching
.bun-version.bun run docs:auditbun run docs:stalebun test tools/active_doc_stale_scan.test.tsbun run release:docsfiles_checked=46 release_notes_checked=44 problems=0bun run verify(all 22 gates)git diff --checkverify)Out of scope, flagged for a separate fix
docs/05-functional-specs/release-gate.mdstill contains a pre-existing failure-handling line telling the reader to "restore exact Japanese -> English -> Chinese order". That contradicts the line a few paragraphs above it, which correctly states the locale contract is ja/en with no Chinese reading surface. It is leftover drift from the #316 Chinese removal and has nothing to do with Vercel, so it was left untouched rather than smuggled into this scope.Release-note impact
CHANGELOG.mdand a release note are required when this reachesmain, handled in the promotion step. No README change: README does not mention Vercel or deployment targets. No discovery-surface regeneration: corpus content and counts are unchanged.