Skip to content
purlshq projects

scaffolder | features | documentation | TESTING

scaffolder | features | documentation | TESTING

Section titled “scaffolder | features | documentation | TESTING”
project:     scaffolder
feature:     documentation
doc-type:    TESTING
status:      accepted
version:     0.1
updated:     2026-03-22
depends-on:  scaffolder | features | documentation | SPEC,
             scaffolder | features | documentation | TASKS

Test strategy

Section titled “Test strategy”

This feature has no application code — it’s infrastructure (folder restructure, config files, a static site, and a deployment). Testing is verification-based: confirm each piece exists, works, and connects correctly to the others.

Tests are grouped by the SPEC’s acceptance criteria sections. Each test has a method (how to verify) and an expected result.

Config system tests

Section titled “Config system tests”

T1 — Workspace config exists and is valid

Section titled “T1 — Workspace config exists and is valid”

Method: Read D:\purlshq-dev\workspace.json, parse as JSON Expected: Valid JSON with keys: workspace_root, engine_root, docs_site_root, backups_root, github_org, domain, projects Who: Harley

T2 — Project config exists and is valid

Section titled “T2 — Project config exists and is valid”

Method: Read {docs_site_root}/src/content/docs/scaffolder/project.json, parse as JSON Expected: Valid JSON with keys: project, github_repo, scale_tier, engine_project_path, linear_project, version Who: Harley

T3 — Joker can read workspace config via MCP

Section titled “T3 — Joker can read workspace config via MCP”

Method: Joker reads D:\purlshq-dev\workspace.json via filesystem MCP Expected: File contents returned, all keys present Who: Joker (next session start)

T4 — Joker can read project config via MCP

Section titled “T4 — Joker can read project config via MCP”

Method: Joker reads project.json via path resolved from workspace config Expected: File contents returned, all keys present Who: Joker (next session start)

T5 — No hardcoded paths in reference files

Section titled “T5 — No hardcoded paths in reference files”

Method: Search CHAT-REFERENCE.md, PROJECT-INSTRUCTIONS.md, CLAUDE.md, and STANDARDS.md for literal D:\scaffolder-engine or D:\purlshq-dev\scaffolder-engine or any other absolute path that should be config-resolved Expected: Zero matches. All paths use {config_key} notation. Who: Harley (grep -r across reference files)

Folder restructure tests

Section titled “Folder restructure tests”

T6 — Engine at new location

Section titled “T6 — Engine at new location”

Method: ls /mnt/d/purlshq-dev/scaffolder-engine/package.json Expected: File exists Who: Harley

T7 — Old location gone

Section titled “T7 — Old location gone”

Method: ls /mnt/d/scaffolder-engine/ Expected: No such directory Who: Harley

T8 — Git remotes intact

Section titled “T8 — Git remotes intact”

Method: cd /mnt/d/purlshq-dev/scaffolder-engine && git remote -v Expected: origin points to github.com/purlshq/scaffolder Who: Harley

T9 — sc CLI works from new location

Section titled “T9 — sc CLI works from new location”

Method: cd /mnt/d/purlshq-dev/scaffolder-engine && sc create --dry-run "test-verify" Expected: Dry run completes without errors Who: Harley

T10 — Harley alias works

Section titled “T10 — Harley alias works”

Method: Run harley from any directory Expected: Claude Code launches, points at correct project Who: Operator

T11 — Backups directory exists

Section titled “T11 — Backups directory exists”

Method: ls /mnt/d/purlshq-dev/backups/ Expected: Directory exists (may be empty) Who: Harley

Doc and session migration tests

Section titled “Doc and session migration tests”

T12 — Docs present in doc site repo

Section titled “T12 — Docs present in doc site repo”

Method: find /mnt/d/purlshq-dev/projects-purlshq-com/src/content/docs/scaffolder/docs/ -name "*.md" | wc -l Expected: Count matches the number of doc files that existed before migration Who: Harley

T13 — Docs removed from engine

Section titled “T13 — Docs removed from engine”

Method: ls /mnt/d/purlshq-dev/scaffolder-engine/projects/scaffolder/docs/ Expected: No such directory Who: Harley

T14 — Session files present in doc site repo

Section titled “T14 — Session files present in doc site repo”

Method: Verify existence of:

  • src/content/docs/scaffolder/ai-sessions/CURRENT-CHAT.md
  • src/content/docs/scaffolder/ai-sessions/CURRENT-CODE.md
  • src/content/docs/scaffolder/ai-sessions/logs/ (with contents) Expected: All files present, content intact Who: Harley

T15 — Session files removed from engine

Section titled “T15 — Session files removed from engine”

Method: ls /mnt/d/purlshq-dev/scaffolder-engine/projects/scaffolder/ai-sessions/ Expected: No such directory Who: Harley

T16 — No content loss

Section titled “T16 — No content loss”

Method: Diff file lists before and after migration (capture “before” list during Task 5 execution) Expected: Every file that existed before exists after, same content Who: Harley

Starlight frontmatter tests

Section titled “Starlight frontmatter tests”

T17 — All markdown files have frontmatter

Section titled “T17 — All markdown files have frontmatter”

Method: For each .md file under src/content/docs/scaffolder/, check that the first line is --- and a title: field exists Expected: Every .md file has YAML frontmatter with title Who: Harley (script or grep)

T18 — Existing content unchanged

Section titled “T18 — Existing content unchanged”

Method: Compare content below frontmatter block with original files (captured before frontmatter was added) Expected: Identical content — only the frontmatter block was prepended Who: Harley

Doc site tests

Section titled “Doc site tests”

T19 — Build succeeds

Section titled “T19 — Build succeeds”

Method: cd /mnt/d/purlshq-dev/projects-purlshq-com && npm run build Expected: Clean build, no errors, no warnings about missing titles Who: Harley

T20 — Sidebar shows scaffolder docs

Section titled “T20 — Sidebar shows scaffolder docs”

Method: npm run dev, open localhost in browser, inspect sidebar Expected: Scaffolder project appears with nested docs and ai-sessions Who: Operator (visual inspection)

T21 — Breadcrumbs work

Section titled “T21 — Breadcrumbs work”

Method: Navigate to a deeply nested doc (e.g., a decision page) Expected: Breadcrumbs show full hierarchy: scaffolder > docs > features > documentation > decisions > [page] Who: Operator (visual inspection)

T22 — Right-side page nav works

Section titled “T22 — Right-side page nav works”

Method: Open a long doc (e.g., SPEC.md or ARCHITECTURE.md) Expected: “On this page” nav on the right side lists section headings Who: Operator (visual inspection)

T23 — Search works

Section titled “T23 — Search works”

Method: Use the built-in search, search for a known term Expected: Results returned, clicking leads to correct page Who: Operator (visual inspection)

T24 — Light/dark toggle works

Section titled “T24 — Light/dark toggle works”

Method: Click the theme toggle Expected: Site switches between light and dark themes Who: Operator (visual inspection)

Cloudflare deployment tests

Section titled “Cloudflare deployment tests”

T25 — Auto-deploy on push

Section titled “T25 — Auto-deploy on push”

Method: Push a trivial change to main, check Cloudflare Pages dashboard Expected: Build triggered, completes successfully, site updated Who: Operator

T26 — Site accessible at custom domain

Section titled “T26 — Site accessible at custom domain”

Method: Visit https://projects.purlshq.com Expected: Cloudflare Access login screen appears (not a DNS error) Who: Operator

T27 — Access blocks unauthenticated visitors

Section titled “T27 — Access blocks unauthenticated visitors”

Method: Visit site in incognito without authenticating Expected: Cloudflare Access login required, no site content visible Who: Operator

T28 — Operator can authenticate

Section titled “T28 — Operator can authenticate”

Method: Enter operator email, receive OTP, enter code Expected: Access granted, site content visible Who: Operator

Path resolution tests

Section titled “Path resolution tests”

T29 — Joker session start with config

Section titled “T29 — Joker session start with config”

Method: Start a new Joker session. Joker reads workspace.json, resolves project paths, reads CURRENT-CHAT.md and CURRENT-CODE.md Expected: Joker successfully reads all files using config-resolved paths, presents session summary Who: Joker (next session)

T30 — Harley session start with config

Section titled “T30 — Harley session start with config”

Method: Start Harley. Harley reads workspace.json, resolves paths, reads CURRENT-CODE.md and relevant docs Expected: Harley successfully reads all files using config-resolved paths, ready to work Who: Harley (next session)

T31 — Harley session end writes to correct location

Section titled “T31 — Harley session end writes to correct location”

Method: End a Harley session, check that CURRENT-CODE.md and session log are written to the doc site repo path Expected: Files written to {docs_site_root}/src/content/docs/scaffolder/ai-sessions/ Who: Harley

Test execution order

Section titled “Test execution order”
  1. T1-T5 (config) — after Tasks 1, 8
  2. T6-T11 (folder restructure) — after Task 2
  3. T12-T16 (migration) — after Tasks 5, 6
  4. T17-T18 (frontmatter) — after Task 7
  5. T19-T24 (doc site) — after Task 7, local dev server
  6. T25-T28 (Cloudflare) — after Tasks 10, 11
  7. T29-T31 (path resolution) — after Task 9, next Joker/Harley session

TESTING — accepted.