ktg-plugin-marketplace/shared/PLAYGROUND-MAINTENANCE.md

# Playground Maintenance

Procedure for updating plugin playground HTML files (single-file decision-builders + report viewers shipped under `plugins/<name>/playground/`) when a plugin is extended or upgraded.

Six plugins currently consume the shared design system: `ms-ai-architect`, `okr`, `llm-security`, `ultraplan-local`, `config-audit`, `voyage`. The procedure is identical for all of them — substitute the plugin name where indicated.

## Architecture in 30 seconds

```
marketplace-rot/
├── shared/
│   ├── playground-design-system/        ← Canonical source (where DS work happens)
│   │   ├── tokens.css, base.css, components*.css, fonts/
│   │   ├── CHANGELOG.md
│   │   └── README.md
│   └── playground-examples/             ← Reference scenarios + showcase landing
│
└── plugins/<name>/
    └── playground/
        ├── <name>-playground.html        ← Loads CSS from `vendor/...`
        └── vendor/playground-design-system/  ← Vendored snapshot (synced from shared/)
            └── MANIFEST.json             ← SHA-256 per file + source_commit + sync_date
```

**Standalone guarantee:** plugin HTML loads `vendor/...`, never `shared/...`. After sync, `vendor/` is self-sufficient — forkers who clip out `plugins/<name>/` get everything.

## Four update tracks

Pick the track(s) that match what you are changing. Multiple tracks can apply in one release.

### Track A — Plugin HTML change (parser, renderer, surface, action)

When: you are adding/modifying parsers, renderers, surfaces, action handlers, or fixtures inside the plugin's playground HTML. No DS change.

1. Edit `plugins/<name>/playground/<name>-playground.html` directly.
2. If fixture format changes, update `plugins/<name>/playground/test-fixtures/<archetype>.md` and re-run parser tests.
3. Run plugin's playground test suite:
   ```bash
   cd plugins/<name>
   bash tests/run-e2e.sh --playground
   bash tests/test-playground-migrations.sh   # if migrations exist
   ```
4. If demo state references fixtures, regenerate the inline JSON block:
   ```bash
   node scripts/build-demo-state.mjs   # idempotent — replaces existing block
   ```

No DS sync is needed for Track A.

### Track B — Shared design-system change

When: you are adding new tokens, components, or modifying generic CSS that all consuming playgrounds should benefit from.

1. Edit `shared/playground-design-system/<file>.css` at marketplace root.
2. Bump version in `shared/playground-design-system/CHANGELOG.md` (Keep a Changelog format).
3. Sync vendored copy in each consuming plugin:
   ```bash
   node scripts/sync-design-system.mjs <plugin-name> [--force]
   ```
   - **Drift detection:** the script refuses overwrite if `vendor/` files have been modified locally (SHA-256 mismatch). `--force` overrides.
   - `MANIFEST.json` is updated with new `source_commit` + `sync_date` per file.
   - Repeat for every consuming plugin (current consumers listed in repo-root `CLAUDE.md`).
4. Verify each plugin's playground tests still pass (Track A step 3).
5. Each consuming plugin must adopt the new selectors in its HTML to actually use them — DS bumps are additive, never breaking.

**Adoption is optional.** Plugins not yet using a DS feature stay green without re-syncing. New DS hoists never break existing consumers as long as the bump is purely additive.

### Track C — Visual verification (always before release)

When: any visual-affecting change has landed (Track A, B, or both).

1. Regenerate screenshots:
   ```bash
   cd plugins/<name>/tests/screenshot
   npm install   # one-time, gitignored node_modules
   npx playwright install chromium   # one-time, ~150MB
   node run.mjs
   ```
   - Output: `plugins/<name>/playground/screenshots/<version>/`
   - Bump `OUT_DIR` in `tests/screenshot/run.mjs` when the plugin version changes (e.g. v1.10.0 → v1.11.0).
   - Decide whether to keep older screenshot folders as historical reference, or delete them — they live under git history regardless.
2. Manual visual QA in Chrome:
   - Open the plugin playground HTML from `file://`.
   - Compare against `shared/playground-examples/scenarios/<reference>.html` (e.g. `ros-lier-kommune.html` is the showcase anchor for ms-ai-architect renderers).
   - Check: eyebrow labels visible, severity-coded borders rendering, app-header breadcrumb correct, AI Act pyramid not clipping text, light/dark theme toggle working.

### Track D — Release (version bump + docs)

When: shipping a new version, regardless of which other tracks ran.

Mandatory files to update in the release commit (or immediately after):

1. `plugins/<name>/.claude-plugin/plugin.json` — bump `"version"`.
2. `plugins/<name>/README.md` — version badge, Version History entry, new detailed section under Playground describing the change.
3. `plugins/<name>/CLAUDE.md` — Playground heading version, architecture notes, status of any deferred work.
4. `plugins/<name>/CHANGELOG.md` — new `[X.Y.Z]` entry at the top (Keep a Changelog format) with Added/Changed/Notes subsections.
5. Marketplace-root `README.md` — bump version reference in the plugin's block.

Conventional commit:
```
feat(<plugin-name>): release vX.Y.Z — <one-line summary>
```

Do not use `[skip-docs]` on release commits — release commits are exactly when docs ship. Intermediate session commits within a multi-session release may use `[skip-docs]` if docs are bundled with the final commit.

Push to Forgejo `main` is pre-authorized (see global `~/.claude/CLAUDE.md`).

## Three-doc rule (from marketplace-root CLAUDE.md)

> Enhver feature-endring som pusher til Forgejo MÅ oppdatere alle tre doc-nivåer i SAMME commit eller umiddelbart etter:
> 1. Plugin `README.md` — detailed change documentation
> 2. Plugin `CLAUDE.md` — architecture/overview
> 3. Marketplace-root `README.md` — marketplace landing page

This rule applies to every release that consumers see. Internal refactors that do not change the user-visible contract may use `[skip-docs]`, but the next release commit must catch up the docs.

## Common pitfalls

- **Editing `vendor/` directly.** Never. Edit `shared/` and re-sync. Direct vendor edits trigger drift detection on next sync (which is the safety mechanism, but you have lost authorial intent).
- **`replace_all` in Edit tool with a string that appears in multiple contexts.** When migrating CSS class names, verify scope after each `replace_all` — e.g. `<article class="card">` may appear in both project-sub-card and catalog-card with different surrounding markup.
- **Sync without testing.** Running `sync-design-system.mjs` then committing without running the plugin's test suite is how silent breakage ships. Always Track A step 3 after Track B step 3.
- **Forgetting to regenerate demo state.** If you change fixture formats but skip `build-demo-state.mjs`, the inline JSON block becomes stale and the "Last inn demo-data" button loads obsolete data.
- **Screenshot folder version mismatch.** Bumping `plugin.json` version without updating `OUT_DIR` in `tests/screenshot/run.mjs` produces screenshots in the wrong folder. Bump both.
- **Background orchestrators.** The harness does not expose Agent tool to sub-agents launched in background. Default to foreground for any orchestration involving sub-agents.

## When to consider hoisting

Inline CSS in a plugin's playground HTML is a candidate for hoisting to `shared/playground-design-system/components-tier3-supplement.css` when:

- The selector represents a generic visual pattern (not domain-specific semantics).
- At least two playgrounds would benefit (or one playground plus the showcase under `playground-examples/`).
- The pattern is structurally identical, not just visually similar (different ARIA semantics or DOM shapes are usually a sign to keep it plugin-local).

Components that should stay plugin-local include:
- Domain-specific verdict semantics (e.g. ms-ai-architect's `.verdict-pill` for go/block contrasts with DS `.verdict-pill-lg` for severity bands).
- Status modifiers that don't generalize (e.g. `.scenario-card[data-status="met/partial/missing"]` vs DS `data-status="winner"`).
- Components with structurally different ARIA patterns (e.g. native `<details>` vs JS-toggled `aria-expanded`).
- Surface-specific layouts (`.onboarding-*`, `.home-*`, `.project-*`, `.modal*`, `.command-form*`).

## References

- Marketplace-root `CLAUDE.md` — conventions and three-doc rule
- `shared/playground-design-system/CHANGELOG.md` — DS version history
- `shared/playground-design-system/README.md` — DS API surface and token reference
- `shared/playground-examples/` — reference scenarios serving as visual anchors
- Each plugin's `CLAUDE.md` Playground section — plugin-specific architecture and validation counts