> 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/phase04-session08-media-validation-and-documentation-closeout/spec.md). # Session Specification **Session ID**: `phase04-session08-media-validation-and-documentation-closeout` **Phase**: 04 - Media Catalog and Audio/Visual Pipeline **Status**: Not Started **Created**: 2026-05-29 **Package**: cross-cutting **Package Stack**: Node 20 npm workspace, TypeScript packages, React 18 app, static public demo, repository media gates, Playwright, Vitest, Biome *** ## 1. Session Overview This session closes Phase 04 by validating the media catalog, generated-draft provenance, promotion tooling, browser audio behavior, public demo media parity, accessibility, privacy, and performance gates end to end. It is a cross-cutting closeout session because the acceptance evidence spans repository scripts, app and public-demo browser checks, stable documentation, spec workflow records, and future-phase handoff notes. The work matters because Phase 04 added the rules that prevent media drift: typed catalog records, non-runtime generated draft manifests, explicit visual promotion configs, opt-in synthetic browser audio, public-demo media parity, and a root media release gate. Session 08 proves those gates still agree and updates the stable docs so the project can move into Phase 05 without implying that conditional media, hosted collaboration, analytics, public sharing, or trusted erasure are already shipped. This session does not add new media or start Phase 05 implementation. If validation exposes a blocking defect, the session may fix the smallest necessary issue and record the evidence, but late feature scope should stay out of the closeout path. *** ## 2. Objectives 1. Validate all Phase 04 media gates, browser smoke checks, quality gates, and documentation gates from the repository root. 2. Capture clear closeout evidence for catalog status, draft provenance, media budgets, metadata cleanup, app media behavior, public-demo offline behavior, accessibility, privacy, and failure paths. 3. Update product, UX, architecture, media, privacy, release, deployment, development, README, package README, phase PRD, and spec workflow docs so shipped Phase 04 behavior is accurate. 4. Record security/compliance posture and carryforward notes for Phase 05 War Room integration, Phase 06 collaboration/mobile, Phase 07 hosted services and analytics, and Phase 08 release cleanup. *** ## 3. Prerequisites ### Required Sessions * [x] `phase04-session01-media-requirements-and-provenance-baseline` - provides the source-backed media matrix, taxonomy, risk model, and quarantine rules. * [x] `phase04-session02-typed-media-catalog-contracts` - provides typed media catalog records, fixtures, validators, and app-facing helpers. * [x] `phase04-session03-draft-asset-generation-and-source-capture` - provides redacted draft briefs, non-runtime generation manifest records, provider provenance, cost notes, and blockers. * [x] `phase04-session04-visual-promotion-tooling-and-budgets` - provides visual promotion checks, metadata policy, byte budgets, docs checks, and app/demo parity tooling. * [x] `phase04-session05-browser-audio-runtime-and-controls` - provides opt-in synthetic browser audio behavior, settings integration, captions, and cleanup-safe failure handling. * [x] `phase04-session06-public-demo-media-parity-and-offline-loading` - provides public-demo media inventory, cache policy, lazy music behavior, and offline validation. * [x] `phase04-session07-media-accessibility-privacy-and-performance-gates` - provides the root `media:gates:check` release gate, browser evidence helpers, privacy checks, and performance blockers. ### Required Tools/Knowledge * Node 20+ and npm workspace scripts. * Repository media gate commands: `media:gates:check`, `media:check`, `media:visual:check`, `media:demo:check`, `media:drafts:check`, and `battlefield:check`. * Root quality commands: `format:check`, `lint`, `typecheck --workspaces --if-present`, `test`, `build`, `security:secrets`, and `git diff --check`. * Playwright desktop/mobile projects for the app and public demo. * Stable docs under `docs/`, root and package README files, Phase 04 PRD files, `CONSIDERATIONS.md`, and `SECURITY-COMPLIANCE.md`. ### Environment Requirements * Run validation from the repository root. * No provider credentials, hosted account, analytics service, War Room federation, public replay hosting, or remote media storage is required. * Browser validation may use local dev and static demo servers only. * `EXAMPLES/` remains quarantined reference-only intake and must not be copied, transformed, imported, cached, or used as generation input. *** ## 4. Scope ### In Scope (MVP) * Maintainers can validate Phase 04 media readiness - run and record the media gate suite for catalog records, generated drafts, visual promotion, public demo media, battlefield parity, release blockers, and docs references. * Maintainers can validate browser media behavior - record app and public demo desktop/mobile checks for failed media, optional audio visible equivalents, reduced motion, public-demo offline reload, and privacy-safe browser errors. * Maintainers can validate repository quality - run format, lint, typecheck, tests, build where applicable, security secret scan, whitespace checks, and ASCII/LF checks. * Maintainers can trust stable docs as the current contract - update product, UX, architecture, media, privacy, release, deployment, development, README, package README, scripts, public-demo, and phase PRD docs as needed. * Future-phase owners can act on clear handoffs - record Phase 05, Phase 06, Phase 07, and Phase 08 carryforward items without starting those phases. ### Out of Scope (Deferred) * Starting Phase 05 War Room web-to-Worker integration - *Reason: this session only prepares the handoff.* * Adding late new media or approving conditional media by default - *Reason: new promotion requires source, rights, attribution, metadata, fallback, accessibility, privacy, and budget evidence.* * Final deletion of `EXAMPLES/`, `docs/PROGRESS.md`, or other historical inputs - *Reason: Phase 08 owns decommission gates.* * Implementing trusted erasure across local state, archives, logs, backups, browser state, and future hosted data - *Reason: Phase 08 owns unified erasure.* * Hosted auth, hosted storage, hosted analytics, public replay hosting, public media hosting, inbound chat commands, remote execution, Docker isolation, or collaboration identity - *Reason: later phases require separate consent, authorization, retention, and validation design.* *** ## 5. Technical Approach ### Architecture Use the existing repository gates as the source of validation evidence instead of introducing new runtime architecture. The session should run the explicit media gate stack first, then run browser smoke checks and repository quality commands. Results should be recorded in the session artifacts with command, outcome, important counts, and any documented non-release deferrals. Documentation updates should follow the current source-of-truth hierarchy: `.spec_system/PRD/PRD.md` and `.spec_system/PRD/PRD_UX.md` own product and UX status; `.spec_system/PRD/phase_04/PRD_phase_04.md` owns Phase 04 progress; stable docs under `docs/` describe current shipped behavior; package README files describe local package boundaries; `CONSIDERATIONS.md` and `SECURITY-COMPLIANCE.md` capture institutional memory and compliance posture. Closeout artifacts should avoid broad raw command dumps. Record meaningful counts, pass/fail state, command names, cache versions, media gate summaries, browser evidence locations when available, and sanitized issue descriptions. Keep prompts, provider prompts, tokens, command bodies, broad local paths, raw request bodies, and long historical excerpts out of tracked docs. ### Design Patterns * Script-backed state: use `analyze-project.sh --json` for workflow state and root npm scripts for validation evidence. * Evidence over aspiration: document only validated behavior as shipped and keep future work explicitly deferred. * Conditional media remains conditional: blocked records retain blockers until a later reviewed promotion closes them. * Stable docs as contract: update current docs and package READMEs, not historical reports, as the user-facing truth. * Redacted closeout: summarize command evidence without exposing secrets, broad local paths, provider payloads, or `EXAMPLES/` excerpts. ### Technology Stack * Node 20 npm workspace scripts. * TypeScript protocol, server, web, adapters, and Worker packages. * JavaScript CLI and hooks packages. * React 18, Vite, Zustand, Tailwind, Web Audio API, and static public demo. * Vitest, Playwright, Biome, repository media scripts, and secret scanning. *** ## 6. Deliverables ### Files to Create | File | Purpose | Est. Lines | | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- | ---------- | | `.spec_system/specs/phase04-session08-media-validation-and-documentation-closeout/implementation-notes.md` | Task-by-task evidence log, command summaries, documentation audit notes, and blocker decisions. | \~220 | | `.spec_system/specs/phase04-session08-media-validation-and-documentation-closeout/security-compliance.md` | Phase 04 media closeout security, privacy, GDPR, provider, quarantine, and release-risk review. | \~120 | | `.spec_system/specs/phase04-session08-media-validation-and-documentation-closeout/validation.md` | Final validation report covering tasks, deliverables, commands, browser evidence, docs, quality gates, and residual risk. | \~180 | | `.spec_system/specs/phase04-session08-media-validation-and-documentation-closeout/IMPLEMENTATION_SUMMARY.md` | Human-readable closeout summary for Phase 04 and the Phase 05 handoff. | \~100 | ### Files to Modify | File | Changes | Est. Lines | | ------------------------------------------- | ------------------------------------------------------------------------------------------------------- | ---------- | | `.spec_system/PRD/phase_04/PRD_phase_04.md` | Mark Session 08 evidence and close Phase 04 status when validation passes. | \~40 | | `.spec_system/PRD/PRD.md` | Update Phase 04 status map and shipped media behavior, keeping Phase 05-08 deferred. | \~40 | | `.spec_system/PRD/PRD_UX.md` | Update media/audio/visual UX validation status and future UX boundaries. | \~40 | | `.spec_system/CONSIDERATIONS.md` | Add Phase 04 lessons, active media handoffs, and future-phase carryforward items. | \~60 | | `.spec_system/SECURITY-COMPLIANCE.md` | Update Phase 04 security/GDPR posture, media privacy gate status, and open release risks. | \~80 | | `README.md` | Align project overview and current shipped capabilities with Phase 04 closeout. | \~40 | | `docs/ARCHITECTURE.md` | Update current media architecture and remaining gaps after validation. | \~50 | | `docs/media-assets.md` | Add Phase 04 closeout status, validated gates, approved records, and conditional blockers. | \~80 | | `docs/privacy-and-security.md` | Update media privacy closeout, external-transfer boundaries, and release risks. | \~60 | | `docs/release.md` | Align release gates, media blockers, public-demo cache policy, and Phase 04 closeout wording. | \~50 | | `docs/deployment.md` | Confirm demo and Worker deployment docs distinguish current media/demo scope from Phase 05 integration. | \~40 | | `docs/development.md` | Update validation command guidance and media gate workflow if needed. | \~40 | | `scripts/README_scripts.md` | Confirm media gate ordering and closeout command references. | \~30 | | `apps/web/README_web.md` | Update app media boundary and validation evidence after closeout. | \~40 | | `public-demo/README_public-demo.md` | Update demo media/offline validation state and cache version references if needed. | \~40 | *** ## 7. Success Criteria ### Functional Requirements * [ ] Phase 04 media gate suite passes or every failure has a documented non-release deferral approved by the session scope. * [ ] App and public-demo browser evidence covers desktop/mobile media failure paths, optional audio visible equivalents, reduced motion, offline reload, and privacy-safe browser errors. * [ ] Stable docs distinguish approved battlefield runtime media from conditional, planned, prototype-only, rejected, unknown, and deferred media. * [ ] Stable docs accurately distinguish shipped Phase 04 behavior from Phase 05 War Room integration, Phase 06 collaboration/mobile, Phase 07 hosted services/analytics, and Phase 08 release cleanup. * [ ] Phase 04 PRD, master PRD, UX PRD, security/compliance posture, and carryforward notes are synchronized with validation evidence. ### Testing Requirements * [ ] Media gates recorded: `npm run media:gates:check`, `npm run media:check`, `npm run media:visual:check`, `npm run media:demo:check`, `npm run media:drafts:check`, and `npm run battlefield:check`. * [ ] Repository quality recorded: `npm run format:check`, `npm run lint`, `npm run typecheck --workspaces --if-present`, `npm test`, `npm run build --workspaces --if-present`, `npm run security:secrets`, and `git diff --check`. * [ ] Browser validation recorded for app and public-demo desktop/mobile projects. * [ ] ASCII/LF validation completed for changed files. ### Non-Functional Requirements * [ ] No tracked closeout artifact includes secrets, provider credential values, raw provider payloads, broad local paths, raw request bodies, raw prompts, command bodies, or long `EXAMPLES/` excerpts. * [ ] Closeout docs preserve local-first behavior and do not imply hosted services, analytics, public replay hosting, or War Room federation are required. * [ ] Conditional media blockers remain visible and are not converted into release-ready claims without evidence. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code and docs follow project conventions. * [ ] No unrelated refactors or historical artifact deletion. *** ## 8. Implementation Notes ### Key Considerations * Use the analysis script output as workflow state authority. * Treat `docs/` and directory README files as the first stable context source. * Keep command evidence concise: command name, status, important counts, and actionable failures are enough. * If validation reveals a small blocking defect, fix only the defect needed to preserve Phase 04 closeout and document the reason. * Avoid updating state as completed before the validate and updateprd workflow steps run. ### Potential Challenges * Long validation runtime: run focused media and browser gates first, then the broader repo quality sweep. * Browser server readiness: use existing Playwright webServer setup and record the exact project names that pass. * Documentation drift: update master PRD, UX PRD, phase PRD, stable docs, and package READMEs together so status vocabulary stays consistent. * Conditional media ambiguity: preserve explicit blockers for public-demo speech/music, portraits, brand, showcase, draft, planned, rejected, and unknown media. * Privacy leak risk in evidence: sanitize or summarize command output instead of copying raw logs into tracked docs. ### Relevant Considerations * \[P03] **Stable docs are the current contract**: closeout must update README files, `docs/`, architecture, privacy, deployment, and legacy boundaries as current truth. * \[P03] **Redaction is boundary-specific**: validation notes, media catalogs, release gates, browser errors, replay/export adjacency, and future hosted paths need explicit minimization. * \[P00] **Asset provenance gate**: no image, audio, model, texture, or bundled chunk should ship from quarantined historical artifacts without source, rights, attribution, optimization, metadata, and size-budget review. * \[P04] **Provider generation is non-runtime by default**: generated drafts remain non-runtime until promotion gates approve them. * \[P02-apps/web] **Responsive and accessibility debt**: closeout browser checks need mobile, reduced motion, focus, visible equivalents, readable labels, and no overlap regressions. * \[P03] **Phase complete is not release complete**: Phase 04 closeout does not complete War Room federation, collaboration, hosted services, analytics, mobile certification, trusted erasure, or decommission gates. *** ## 9. Testing Strategy ### Unit Tests * Run `npm test` and record total pass/fail/skip counts. * Confirm existing media release gate and catalog tests remain green. ### Integration Tests * Run `npm run media:gates:check`, `npm run media:check`, `npm run media:visual:check`, `npm run media:demo:check`, `npm run media:drafts:check`, and `npm run battlefield:check`. * Run `npm run typecheck --workspaces --if-present`. * Run `npm run build --workspaces --if-present` unless an existing documented environment limitation blocks it. ### Browser Tests * Run app desktop/mobile Playwright evidence: `npm run test:e2e -- --project=app-desktop --project=app-mobile tests/e2e/app.e2e.ts`. * Run public-demo desktop/mobile Playwright evidence: `npm run test:e2e -- --project=public-demo-desktop --project=public-demo-mobile tests/e2e/public-demo.e2e.ts`. ### Manual Testing * Review stable docs and package README diffs for incorrect shipped claims, missing deferrals, cache version mismatches, and stale Phase 04 wording. * Verify the session artifacts summarize command outcomes without raw secrets, broad local paths, raw prompts, command bodies, or long historical excerpts. ### Edge Cases * A media gate fails only because a conditional record remains blocked: document it as non-release only if the release gate treats it as expected. * Browser validation cannot start a server: record the exact server readiness failure and do not mark browser evidence complete. * Public-demo service worker cache version differs from docs: fix the stale doc or cache reference before closeout. * Secret scan or ASCII/LF checks catch generated evidence: remove or sanitize the offending content before validation. *** ## 10. Dependencies ### External Libraries * None new. ### Other Sessions * **Depends on**: `phase04-session01-media-requirements-and-provenance-baseline`, `phase04-session02-typed-media-catalog-contracts`, `phase04-session03-draft-asset-generation-and-source-capture`, `phase04-session04-visual-promotion-tooling-and-budgets`, `phase04-session05-browser-audio-runtime-and-controls`, `phase04-session06-public-demo-media-parity-and-offline-loading`, `phase04-session07-media-accessibility-privacy-and-performance-gates` * **Depended by**: Phase 05 War Room Worker Integration planning, Phase 06 collaboration/mobile planning, Phase 07 hosted services/analytics planning, and Phase 08 release cleanup planning. *** ## 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/phase04-session08-media-validation-and-documentation-closeout/spec.md?ask=&goal= ``` `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.