> For the complete documentation index, see [llms.txt](https://faction-os.gitbook.io/faction-os-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/sessions/phase16-session03-automated-checks-and-build-gates/spec.md).

# Session Specification

**Session ID**: `phase16-session03-automated-checks-and-build-gates` **Phase**: 16 - Quality, Deployment, And Launch Handoff **Status**: Complete **Created**: 2026-06-02 **Completed**: 2026-06-02 **Package**: public-website **Package Stack**: Astro/TypeScript

***

## 1. Session Overview

This session continues Phase 16 by making the static public website launch checks reliable from a clean root install, root workspace commands, and package-scoped commands. Sessions 01 and 02 have already hardened responsive, accessibility, performance, image, font, and static-boundary behavior. The next launch risk is drift between those validated website guarantees and the commands that operators, CI, and later launch handoff work will rely on.

The current `public-website` workspace is an Astro static site with package scripts for typecheck, build, preview, and deterministic built-site checking. The repository root already has workspace-aware `typecheck` and `build` scripts plus Biome format and lint commands that include `public-website`. This session should verify those assumptions from the root, adjust scripts only where evidence shows a gap, and extend static output checks for draft exclusion, RSS, sitemap, robots, metadata, approved links, and the absence of analytics or tracking behavior.

Implementation stays within the launch-checking surface and evidence files. It must not add deployment automation, Cloudflare credentials, browser automation suites, analytics, hosted forms, server rendering, auth, CMS behavior, or runtime personalization. The output of this session is a trustworthy command matrix and static-output gate that Phase 16 Session 04 can use before the Cloudflare Pages deployment path.

***

## 2. Objectives

1. Verify root and package command coverage for install, format, lint, typecheck, build, and website static-output checks.
2. Extend deterministic website checks to cover draft exclusion, RSS, sitemap, robots, canonical metadata, approved destinations, and no tracking code in built output.
3. Document any intentional root/package command delegation so launch handoff does not confuse package-scoped website gates with missing root coverage.
4. Record validation notes for all required commands, static privacy checks, and remaining deployment handoff constraints.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase16-session01-responsive-and-accessibility-hardening` - completed responsive, keyboard, focus, semantic, reduced-motion, and viewport hardening for the first-release static website.
* [x] `phase16-session02-performance-and-image-optimization` - completed image, CSS, font, static output, and no-telemetry performance hardening.
* [x] `phase15-session06-cross-linking-and-copy-consistency-pass` - established the deterministic built-site checker and route/CTA/legal marker contract.

### Required Tools/Knowledge

* npm workspaces from the repository root.
* Root scripts in `package.json` for `format:check`, `lint`, `typecheck`, and `build`.
* Package scripts in `public-website/package.json` for Astro typecheck, build, preview, and static checks.
* Existing built-site checker in `scripts/check-public-website-links.mjs`.
* Astro RSS, sitemap, static output, and content collection draft behavior.
* Static website privacy rules from `.spec_system/CONSIDERATIONS.md` and `.spec_system/SECURITY-COMPLIANCE.md`.

### Environment Requirements

* Node.js 26.2.0 or newer.
* npm 11.16.0 or compatible workspace support.
* Network access available for `npm install` if dependencies are not already present.
* Local shell access to inspect `public-website/dist` after builds.

***

## 4. Scope

### In Scope (MVP)

* Operators can run `npm install` from the repository root and get a usable workspace dependency state.
* Operators can run root `npm run format:check` and know it covers `public-website` files.
* Operators can run root `npm run lint` and know it covers website files where Biome applies.
* Operators can run root `npm run typecheck` and know it includes `@factionos/public-website` through workspace scripts or is explicitly documented if package-scoped execution is required.
* Operators can run root `npm run build` and know it includes the website build through workspace scripts or is explicitly documented if package-scoped execution is required.
* Operators can run package-scoped website typecheck and build commands.
* Operators can run a deterministic website static-output checker after build.
* Launch handoff evidence verifies production build draft exclusion, RSS output, sitemap output, robots sitemap reference, canonical metadata, approved links, and no analytics or tracking code in built output.
* Root/package script changes are made only when evidence shows a real command coverage gap.

### Out of Scope (Deferred)

* Cloudflare Pages deployment configuration - *Reason: Phase 16 Session 04 owns deployment path setup and validation.*
* Browser automation beyond lightweight local preview checks - *Reason: this session is command and static-output gate focused.*
* Large Playwright suites - *Reason: the session stub excludes them unless regressions justify the cost.*
* New product pages, content, CTAs, or visual redesign - *Reason: Phase 16 is launch hardening only.*
* Analytics, RUM, tracking, hosted forms, cookies, or browser storage writes - *Reason: the first release has no analytics or data collection by default.*
* Server rendering or `@astrojs/cloudflare` - *Reason: the first launch remains a fully static Astro build.*

***

## 5. Technical Approach

### Architecture

Use the existing npm workspace layout as the command boundary. Root `format:check` and `lint` should continue to include `public-website` paths directly, while root `typecheck` and `build` should rely on workspace scripts with `--workspaces --if-present`. Package-scoped website commands remain the authoritative focused checks for Astro type generation and static output.

Extend the existing deterministic built-site checker instead of introducing a parallel validation stack. The checker already knows the public website root, dist output, fixed routes, content routes, approved destinations, guarded copy patterns, legal markers, and script privacy boundary. Add static output checks for draft exclusion, RSS XML, sitemap XML, robots sitemap reference, metadata presence, and tracking-code absence in all built text assets. Keep file collection deterministic, extensions explicit, and error output sanitized to relative paths and compact issue descriptions.

Record command evidence in the session implementation notes. Every command result should be marked pass, fail, fixed, blocked, unavailable, or delegated with enough detail for Session 04 and launch handoff. If a root command already includes website coverage, record that fact instead of adding redundant scripts.

### Design Patterns

* Deterministic static checker: Validate built artifacts locally and fail with compact, actionable messages.
* Workspace command delegation: Prefer root workspace scripts for broad gates and package scripts for focused Astro gates.
* Evidence-led script changes: Modify root or package scripts only after command output proves a coverage gap.
* Static privacy boundary: Treat analytics, trackers, hosted forms, browser storage, beacons, and runtime network APIs as build-gate failures.
* Claim-scoped launch evidence: Record local static checks without implying production-hosted validation.

### Technology Stack

* Node.js 26.2.0 or newer.
* npm 11.16.0 workspaces.
* Astro 6.4.2 static output.
* TypeScript 5.9.3.
* Biome 2.4.16 for root format and lint.
* Existing `scripts/check-public-website-links.mjs` Node checker.

***

## 6. Deliverables

### Files to Create

| File                                                                                            | Purpose                                                                                                       | Est. Lines |
| ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ---------- |
| `.spec_system/specs/phase16-session03-automated-checks-and-build-gates/implementation-notes.md` | Command matrix, script coverage evidence, static-output check notes, fixes, deferrals, and validation results | \~180      |

### Files to Modify

| File                                      | Changes                                                                                                                 | Est. Lines |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ---------- |
| `scripts/check-public-website-links.mjs`  | Add draft, RSS, sitemap, robots, metadata, and broader tracker/static-output gates while keeping deterministic failures | \~160      |
| `public-website/package.json`             | Review or adjust package-scoped check scripts if a launch gate needs a clearer package command                          | \~10       |
| `package.json`                            | Review or adjust root workspace scripts only if command evidence shows website coverage is missing                      | \~10       |
| `public-website/README_public-website.md` | Document launch check commands, root/package delegation, and static-output gate expectations                            | \~50       |
| `docs/development.md`                     | Sync command guidance if root or package website check commands change                                                  | \~40       |
| `docs/release.md`                         | Sync release gate guidance for public website static checks and no-claim hosted boundaries                              | \~40       |

***

## 7. Success Criteria

### Functional Requirements

* [ ] `npm install` from the repository root succeeds or any environment blocker is documented with exact remediation.
* [ ] Root `npm run format:check` includes website files.
* [ ] Root `npm run lint` includes website files where Biome applies.
* [ ] Root `npm run typecheck` includes the website workspace typecheck or the explicit package-scoped delegation is documented.
* [ ] Package `npm --workspace @factionos/public-website run typecheck` passes.
* [ ] Package `npm --workspace @factionos/public-website run build` passes.
* [ ] Root `npm run build` includes the website workspace build or the explicit package-scoped delegation is documented.
* [ ] Production build excludes draft blog and news content.
* [ ] Built RSS output exists and is valid enough for launch handoff.
* [ ] Built sitemap output exists and includes public routes while excluding drafts.
* [ ] Built robots file references the sitemap.
* [ ] Built pages include title, canonical, description, Open Graph, and Twitter metadata where indexable.
* [ ] Built output contains no analytics, tracker, beacon, hosted form, browser storage, or runtime network code.

### Testing Requirements

* [ ] `npm run format:check` passes.
* [ ] `npm run lint` passes.
* [ ] `npm run typecheck` passes.
* [ ] `npm --workspace @factionos/public-website run typecheck` passes.
* [ ] `npm --workspace @factionos/public-website run build` passes.
* [ ] `npm --workspace @factionos/public-website run check:links` or its updated equivalent passes.
* [ ] `npm run build` passes or documented delegation is accepted by the spec.
* [ ] Manual static output spot checks are recorded for RSS, sitemap, robots, metadata, draft exclusion, and no tracking code.

### Non-Functional Requirements

* [ ] Static website remains fully prerendered Astro output.
* [ ] No new production dependency is added unless command evidence requires it.
* [ ] Checker output uses relative paths and compact messages without leaking local home paths, tokens, request bodies, prompts, or raw environment values.
* [ ] Website release evidence does not claim production-hosted validation.

### Quality Gates

* [ ] All files ASCII-encoded.
* [ ] Unix LF line endings.
* [ ] Code follows project conventions.
* [ ] Root and package scripts remain understandable from `package.json` and docs.

***

## 8. Implementation Notes

### Key Considerations

* Run the required analysis and command evidence from the repository root so workspace behavior is tested exactly as launch handoff will use it.
* Prefer enhancing the existing static checker over adding another launch gate script with overlapping route and metadata knowledge.
* Treat missing RSS, sitemap, robots, draft filtering, or metadata as build gate failures, not launch handoff comments.
* Keep no-tracking checks broad enough to catch common analytics strings in built HTML, JavaScript, XML, and text outputs without flagging allowed negated policy copy.
* Use implementation notes to distinguish pass, fixed, delegated, blocked, and no-claim outcomes.

### Potential Challenges

* Root `npm install` may depend on network availability: Record a precise blocked or unavailable status if the environment cannot fetch packages.
* Root `npm run build` may run every workspace build: Fix website-specific failures in this session, but do not expand into unrelated package work.
* Static tracker detection can produce false positives from policy copy: Account for negated or no-analytics wording while still failing executable tracking snippets.
* Draft exclusion can be hidden by stale `dist` output: Ensure checks run after a fresh website build or clean enough output for reliable evidence.

### Relevant Considerations

* \[P15-public-website] **Route contract drift is a launch risk**: Static checks must keep route constants, navigation, content, metadata, and approved destinations aligned.
* \[P16-public-website] **Launch hardening is still ahead**: This session turns completed responsive/performance work into repeatable build gates.
* \[P13-public-website] **Static Astro boundary is intentional**: No server adapter, React, Tailwind, CMS, auth, hosted forms, or analytics by default.
* \[P15-public-website] **Deterministic built-site checks catch drift early**: Extend the existing built-output checker rather than relying on source string checks alone.
* \[P13-public-website] **Public website external links are explicit**: Demo and GitBook docs are approved; new third-party destinations require review.

### Behavioral Quality Focus

Checklist active: Yes

Top behavioral risks for this session:

* Static checker false negatives let drafts, metadata regressions, or tracker snippets ship in built output.
* Root and package commands diverge, causing operators or CI to skip website checks by accident.
* Checker failures become noisy or environment-specific because file discovery, route ordering, or output paths are not deterministic.

***

## 9. Testing Strategy

### Unit Tests

* No separate unit test suite is expected unless the checker logic becomes complex enough to justify extracted helpers. Prefer deterministic command execution against built `public-website/dist` for this session.

### Integration Tests

* `npm run format:check`
* `npm run lint`
* `npm run typecheck`
* `npm --workspace @factionos/public-website run typecheck`
* `npm --workspace @factionos/public-website run build`
* `npm --workspace @factionos/public-website run check:links` or updated equivalent
* `npm run build`

### Manual Testing

* Inspect built RSS, sitemap, robots, and representative page metadata from `public-website/dist`.
* Confirm draft content files do not produce public routes, sitemap entries, or RSS items.
* Spot check built output for common tracker and analytics strings.

### Edge Cases

* Draft content in both blog and news collections.
* Trailing slash and root route canonical URLs.
* Robots sitemap URL must use the production `https://faction-os.com` origin.
* XML checks should fail cleanly when RSS or sitemap files are missing.
* Static checker must ignore non-JavaScript JSON-LD scripts while still scanning executable scripts for network, storage, and tracker APIs.

***

## 10. Dependencies

### External Libraries

* Astro: 6.4.2.
* `@astrojs/rss`: 4.0.18.
* `@astrojs/sitemap`: 3.7.3.
* TypeScript: 5.9.3.
* Biome: 2.4.16.

### Internal Dependencies

* `public-website/src/content.config.ts` for blog/news collection schema and draft semantics.
* `public-website/src/lib/content.ts` for public content filtering helpers.
* `public-website/src/lib/metadata.ts` and `public-website/src/data/site.ts` for metadata and canonical URL behavior.
* `public-website/public/robots.txt` for sitemap reference.
* `scripts/check-public-website-links.mjs` for deterministic built-site checks.

### Other Sessions

* **Depends on**: `phase16-session01-responsive-and-accessibility-hardening`, `phase16-session02-performance-and-image-optimization`.
* **Depended by**: `phase16-session04-cloudflare-pages-deployment-path`, `phase16-session05-launch-review-and-documentation-handoff`.

***

## Next Steps

Run the implement workflow step to begin AI-led implementation.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/sessions/phase16-session03-automated-checks-and-build-gates/spec.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.