Skip to content

Docs: AI-oriented additions to FE compliance checklist#6

Merged
AndrewKirkovski merged 2 commits into
masterfrom
feature/fe-checklist-ai-playbook
May 21, 2026
Merged

Docs: AI-oriented additions to FE compliance checklist#6
AndrewKirkovski merged 2 commits into
masterfrom
feature/fe-checklist-ai-playbook

Conversation

@AndrewKirkovski
Copy link
Copy Markdown
Contributor

@AndrewKirkovski AndrewKirkovski commented May 20, 2026

Summary

Make frontend/docs/fe-compliance-checklist.md consumable for AI auditors out of the box, without disrupting human readers.

Inline (skippable): 7 <details> callouts labeled "Additional guide for AI — click to expand" on the heavy sections:

  • §0 isolation paradigm
  • §1 decision tree (entry-point pointer to Appendix D)
  • §3 page apps (4 sub-agent swarm split)
  • §4 web components (3 sub-agent swarm split)
  • §5 theming (3 sub-agent swarm split)
  • §10 verification recipes (canonical commands — no inventing)
  • §14 gold-standard validation (gold pinned by app type)

Humans can collapse them; agents reading mid-doc get section-local phase + swarm hints.

New Appendix D — AI Audit Playbook (~175 lines, all inside one outer <details>):

  • D.1 trigger conditions + read-only sub-agent contract
  • D.2 4-phase taxonomy (P1 Structural → P2 Build → P3 Runtime, P4 Cross-cutting parallel) with stop-on-fail rule
  • D.3 swarm decision matrix + restated heavy-section cut-lists
  • D.4 paste-ready sub-agent prompt template
  • D.5 moderator role with required YAML output schema (REJECT/ACCEPT, §11-keyed fix list, mandatory conflicts: block)
  • D.6 tool mapping per phase (bg-manager sync_run/bg_run, playwright, jq, grep, git diff --no-index)
  • D.7 common AI failure modes (invented commands, evidence-less PASS, silent conflicts, wrong gold standard, over-rejection on SHOULD)
  • D.8 context budget rules (one section per sub-agent, never the full 30K-word doc)
  • D.9 output expectations for the orchestrator

Neighbour-doc pointers:

  • frontend/docs/README.md — index entry for fe-compliance-checklist.md mentioning Appendix D for AI auditors
  • frontend/docs/app-checklist.md — top-of-doc pointer routing AI auditors at the new playbook
  • CLAUDE.md (project root, gitignored — not in this PR) — pointer added locally for the active session

This is pass 1 — covers heavy sections. Pass 2 (after dogfooding the playbook on a real audit) will add callouts to §2/§6/§7/§8/§9/§11/§13 and populate D.7 with concrete anti-patterns observed in practice.

Test plan

  • GitHub render check — open the PR diff and confirm <details> blocks render as collapsible (closed by default).
  • grep -n "Additional guide for AI" frontend/docs/fe-compliance-checklist.md returns 7 hits (one per heavy section + §1 pointer).
  • Skim the doc as a human — confirm the callouts are visually skippable and don't break the existing checklist flow.
  • Dogfood: pick one module (e.g. frontend/web-components/mermaid), spawn the §4 swarm per D.3, run the moderator with the D.5 schema, verify (a) sub-agents emit the table format and (b) moderator produces the YAML schema (REJECT/ACCEPT + fix_list). Surface any gaps as pass-2 TODOs.
  • Read Appendix D end-to-end as if you were an AI auditor with no prior context — confirm the phase order, swarm matrix, and prompt templates are self-contained.

🤖 Generated with Claude Code

@AndrewKirkovski
Docs: AI-oriented additions to FE compliance checklist
11c8080 
Add skippable `<details>` "Additional guide for AI" callouts on the heavy
sections (§0, §1 pointer, §3, §4, §5, §10, §14) plus a new Appendix D —
AI Audit Playbook. Appendix D defines:

- 4-phase taxonomy (P1 Structural → P2 Build → P3 Runtime, P4 Cross-cutting parallel)
- Swarm decision matrix with §3/§4/§5 sub-agent cut-lists
- Read-only sub-agent role + paste-ready prompt template
- Moderator role with required YAML output schema (REJECT/ACCEPT + §11-keyed fix list)
- Tool mapping per phase (bg-manager, playwright, jq, grep, git diff)
- Common AI failure modes & anti-patterns
- Context budget rules (one section per sub-agent, never full doc)

Cross-references added to frontend/docs/README.md index and a top-of-doc
pointer in app-checklist.md routing AI auditors at Appendix D.

This is pass 1 — covers heavy sections; §2/§6/§7/§8/§9/§11/§13 callouts
and concrete failure-mode anti-patterns from real dogfooding land in pass 2.
@AndrewKirkovski
Bump FE to @wippy-fe/* 0.0.32 + adopt vite-plugin contract + dev tools
3fcc892 
FE bumps + plugin wiring:
- All 9 frontend packages (2 apps + 7 web components) bumped
  @wippy-fe/* dependencies from ^0.0.26 to ^0.0.32.
- All 9 packages now declare @wippy-fe/vite-plugin@^0.0.32 in
  devDependencies and add wippyPagePlugin() / wippyComponentPlugin()
  to their vite.config.ts. Build now emits dist/wippy-meta.json
  per the wippy-component-1.0 spec for wippy/views >= 0.5.0.
- iframe-demo: customCSS moved to a sibling
  `custom-css.do-not-link.css` file referenced via `file://` from
  package.json wippy.configOverrides.customization.customCSS. The
  vite-plugin resolves the reference at build time and the
  *.do-not-link.<ext> name is the AI-readable directive that stops
  agents from <link>-ing it directly in app.html (proxy injects it
  at runtime instead).

Agent catalog wiring:
- New app.agents:build_artifacts_catalog (build_func_id wired into
  wippy_artifacts_trait) reads the live view.component registry +
  bundled meta and appends a Markdown catalog to the wippy agent's
  compiled system prompt. Filters announced + auto_register + NOT
  secure so privileged components don't leak into the LLM context
  for every actor.
- New app.agents:debug_agent_prompt HTTP endpoint at
  /api/public/debug/agent-prompt — compiles an agent and returns
  its final system prompt + tool list, for verifying build_func
  contributions without burning LLM tokens.

Windows build scripts:
- make.ps1 mirrors the Makefile targets (build / clean-build /
  lint / build-<module>) for environments without GNU make. The
  `clean-build` target now also deletes package-lock.json, which
  was the root cause of an ERESOLVE peer-conflict on the
  @wippy-fe/* major-version bump (stale lock pinned 0.0.26).
- make.bat is a thin cmd wrapper around make.ps1.

Docs cascade (frontend/docs/):
- host-spec.md, host-less-mode.md, app-checklist.md, fe-compliance-
  checklist.md updated for the 0.0.32 plugin: bumped version pins,
  added the "wippy-meta.json contract is MANDATORY", documented
  the *.do-not-link.<ext> naming convention with the blind-test
  rationale, added the wippy/views ↔ vite-plugin version
  correlation table.

Lockfile + no replacements:
- wippy.lock dropped the `replacements: wippy/views -> local` block
  and refreshed against the hub: wippy/views 0.4.31 -> 0.5.0,
  wippy/facade 0.6.4 -> 0.6.6, plus dependency-graph follow-ups
  (userspace/users, userspace/uploads, wippy/dataflow,
  wippy/migration, wippy/session). Verified end-to-end via
  Playwright — login, Components page renders all 7 WCs
  (reaction-bar, counter-persist, websocket-log, chart-circle,
  mermaid, markdown, model-gallery) with full bundled-meta
  projection.
@AndrewKirkovski AndrewKirkovski merged commit 3fcc892 into master May 21, 2026
@AndrewKirkovski
Copy link
Copy Markdown
Contributor Author

AndrewKirkovski commented May 21, 2026

Dogfood pass complete — 41 edits applied (commit 5570e5a)

Ran the §D playbook on the checklist itself:

  • Phase A (6 read agents) surfaced 42 questions (17 blocker / 22 clarification / 3 nit).
  • Phase B/C (6 answer agents) produced 42 proposed edits with evidence.
  • Phase D (user review) → 32 applied as-proposed, 7 reworded per user, 2 skipped, 2 sent back for deeper research.
  • Two extra research agents answered the deferred items:
    • #9 (icons registration): found that gold was reading the wrong field — config.customization?.icons is a silent no-op; canonical path is addIcons(addCollection) from @wippy-fe/proxy, which iterates theming.global.iconSets. Fixed both doc + gold app.ts.
    • #19 (hostCssKeys): found a doc bug — preflightCssUrl is NOT in the HostCssKey union (TS-rejected and runtime no-op). Replaced with concrete archetype decision rule + corrected union membership.

What's in this commit

Doc updates across §0, §1, §2, §3, §4, §5 (including new §5.0a Capture-before-refactor protocol — screenshots + computed-style inventories before any styling refactor), §6, §7, §8, §9, §10, §11, §12, §13, §14, and Appendix D.

Gold code fixes (downstream of doc rules):

  • frontend/applications/main/src/app.ts — broken icon registration → addIcons(addCollection)
  • frontend/applications/main/app.html — commit CDN form of dev-proxy.js
  • frontend/applications/iframe-demo/app.html — same

Deferred (separate decisions)

  1. Missing gold:make.bat / make.ps1 — referenced from §8.2 but don't exist in repo. Need to either ship them, weaken §8.2 to SHOULD, or drop the gold citations.
  2. Draft: bump to @wippy-fe/* 0.0.26 + CDN 1.0.26 — needs wippy-framework publish #4 (announced/secure/auto_register MUST+Default) — user removed from review; can re-open in pass 2.
  3. #12 (§3.5 factory-vs-handrolled rule list) — user wasn't sold on the wording; needs clearer reformulation.

Full review file at .local/2026-05-21-fe-checklist-review.md (gitignored).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@AndrewKirkovski