A passing build does not mean the site is finished: each check has its own scope

“The build passed” is a necessary status report, but it does not mean “the site is finished.”

A build can tell you whether the current code can produce output. It cannot check that every public URL is correct, drafts stay private, buttons serve their intended purpose, or the reading order feels comfortable on a phone. Nor can it choose the visual direction for the site owner. The main judgment is this: a handoff needs several layers of evidence, and each tool should support only the claims it actually checked.

Separate the questions behind “finished”

A content site has several distinct completion criteria:

Question	Evidence needed
Can Astro understand the code?	Type checks and Astro diagnostics
Does the code violate style or other rules?	Lint
Can the site produce static output?	Build
Are the generated fixed pages and metadata correct?	Static output checks
Do drafts, dates, and article routes follow the content contract?	Notes tests and notes output verification
Can users actually operate the site?	Browser interaction, keyboard checks, and error-path checks
Does this version provide the intended reading experience?	The site owner’s visual and content acceptance
Can it be made public?	Explicit publication authorization and frontmatter state

These questions are related, but no single command can answer the others. Reducing them all to “npm run build succeeded” merely hides what is still unknown.

check starts with types and Astro files

npm run check uses Astro’s checking workflow to read Content Collections, generate types, and run diagnostics on Astro files.

It can help answer:

• Whether component props match the current types.
• Whether Content Collection frontmatter passes the schema.
• Whether Astro templates and TypeScript contain errors that diagnostics can detect.
• Whether the types connect correctly across routes, layouts, and data access.

It cannot answer:

• Whether readers understand the article.
• Whether a link belongs in the main navigation.
• Whether users like the paragraph width on mobile.
• Whether a component that passes type checking is actually used by a page.

Type checking is a gate for connecting content and code. It is not a substitute for content quality or product direction.

lint checks rules, not intent

npm run lint runs ESLint. It can catch violations covered by the current configuration, such as unused variables, certain syntax problems, or patterns the project explicitly prohibits.

Passing lint means the code follows that set of rules. It does not mean those rules cover every usability issue. A button can pass lint and still be in the wrong place. Copy can be grammatically correct yet describe a draft as a completed feature.

Report the result as “rule checks passed,” without extending it to “the feature is correct” or “the user experience is finished.”

build checks whether the site can be generated

Astro build generates static files from the current routes, Content Collections, and components. It confirms that the build process can finish and can surface errors when routes or content data are invalid.

Its scope is still limited:

• It does not provide evidence that an unreferenced component is used.
• It does not evaluate animation timing for the site owner.
• It does not automatically decide whether the sitemap contains URLs that should remain private.
• It does not prove that every interaction works with a keyboard or in error states.
• It does not prove how rewrites, 404 responses, or caching behave on the production host.

A build is a necessary gate in the output pipeline, not acceptance of the entire site.

Static output checks need to read the actual HTML

The static output checks described in the original note do more than inspect the build’s exit code. They read files in dist/ and check fixed pages, compatibility routes, and the 404 page individually.

They check conditions such as:

• Every fixed page has the correct lang.
• Each page has exactly one h1.
• Canonical links, descriptions, Open Graph metadata, and hreflang appear on the expected pages.
• Public pages are not empty SPA shells and do not contain unexpected hydrated-framework markers.
• The old /work route remains a readable entry point, but its canonical points to /about/work.
• The 404 page is noindex and does not identify itself as the home page.
• Local resources referenced by HTML and CSS actually exist.

These checks move the evidence from “the source component looks reasonable” to “the built document meets the contract.” They are still not browser acceptance, but they at least inspect the files readers actually receive.

Notes output checks need to inspect the published collection

An article system has another set of questions: which articles may enter production output, and which must stay in preview?

The notes output checks described in the original note read all Markdown files, parse frontmatter against the schema, and calculate the published article collection. They check that:

• Published articles have their own public pages.
• Published articles have canonical and sitemap links.
• Drafts, articles without publication dates, and articles with future publication dates do not appear in production HTML, the sitemap, or home-page cards.
• If English or Japanese has no published articles, its list and home page show a genuine empty state. This describes a conditional check, not a claim that those locales are still empty now that translations exist.
• The home page and the full article list use the same publication data.

This differs from a general build. A build may generate the site successfully, but checking the article data and reading back dist/ is what confirms that content states have not crossed the public boundary.

Keep browser checks and subjective acceptance

Correct static files do not mean every browser interaction is complete. You still need to check:

• Whether language switching actually leads to the corresponding page.
• Whether the article table of contents and in-page anchors work.
• Whether Escape closes the avatar dialog and returns focus to the trigger button.
• Whether background animation stops or cleans up as required in a hidden tab, with reduced-motion enabled, and when leaving the page.
• Whether articles, work, and main links remain readable when JavaScript fails.
• Whether mobile reading order, button wrapping, tables, and long titles need adjustments.

Browser tools can help with some of these checks. Others still require the site owner to look at the page. Judgments such as “is this the right order?”, “does this spacing feel comfortable?”, and “is the visual emphasis in the wrong place?” cannot be delegated to a build.

Publication is a separate decision

Passing engineering checks does not itself authorize an article to be made public. In the general draft workflow, a draft retains:

publishedAt: ''
draft: true

Only after the article’s content, public scope, and visual reading experience have been accepted should it receive a real publication date and be marked as published. “Written,” “integrated into the site,” “passed engineering checks,” and “authorized for publication” are four different events. The YAML above is a workflow example, not this translation’s frontmatter.

If a handoff says only “everything is finished,” readers and collaborators cannot tell which decisions still need a person. A more reliable report separates these layers:

Changed: the content and code that actually changed
Verified: the commands and artifact checks that passed
Awaiting acceptance: visual, interaction, or content judgments that still need human review
Unpublished: whether the content is still a draft or lacks authorization to become public

Match the wording to the result

You can say:

• “npm run check reported no diagnostic errors.”
• “Static output checks confirmed that fixed pages have canonical links and actual HTML.”
• “Notes output checks confirmed that drafts did not leak into production output.”
• “The article is still a draft and has not received publication authorization.”

Those results do not, by themselves, justify saying:

• “Users will definitely like it.”
• “Every device works without issues.”
• “SEO will definitely improve.”
• “Production deployment will behave exactly like the local site.”

This is not caution for its own sake. The strength of a conclusion should match the scope of its evidence. Tools already do a lot, but the report must also include what they did not check.

Make your own completion checklist

For a task that changes pages, content, and interactions, use this sequence:

1. Confirm the boundaries of the data and requirements.
2. Run type checks and lint, and resolve code-level issues.
3. Run the build and confirm that it produces output.
4. Read back production HTML, the sitemap, and content collections to check the public boundary.
5. Use a browser to exercise real links, keyboard interactions, and error paths.
6. Have the site owner confirm visuals, reading order, and public scope.
7. Only then decide whether to move a draft into published status.

This does not turn every change into a large process. It assigns different risks to suitable checks, rather than letting one passing build cover up everything still unknown.

Scope of this record

This article summarizes the commands, output checks, and content-publication boundaries of the Astro static site documented in the original note. It explains which conclusions each verification layer supports. It does not claim that these commands have proved performance, search rankings, business results, user research findings, or production-host behavior.