[medium] Release 0.5.0: evidence, onboarding, and frontend contracts

[ytvee]

Problem Or Failure Mode

The kit needs reliable first-use and upgrade guidance, durable project facts, and reproducible behavior evidence. Real-project documentation exposed stale capability claims, ambiguous build/type-check coverage, and project-specific conventions that must survive adaptation. Existing frontend workflows also need explicit component compatibility and naming rules.

Closes #66.
Closes #67.

This release candidate prepares v0.5.0 and includes both open issues, including the two additional requirements in #66's comments. No merge, tag, or GitHub Release publication is performed by this PR.

Scope And Changes

• Preserve the original seven improvements from [medium] Proposal: 0.5.0 evidence-driven frontend workflows #67: experimental disposable prototypes, fresh-context review, demonstrable feature slices and dependencies, optional domain glossary, functional outcome verification, assumption analysis, and opt-in live evaluation.
• Add shared first-run checks and upgrade/rollback guidance, linked from all five client installation guides. Validate VS Code aliases against the canonical target manifest.
• Support explicitly authorized root-instruction migration: full-file inventory, reachable local host rules, verbatim backup, coverage map, corrected relative links, minimal pointer, and repeat-run no-op. Ordinary adaptation preserves existing instructions until replacement is authorized.
• Add purpose-specific project-owned names instead of bare Item/Items, while preserving externally mandated API fields and avoiding unrelated renames.
• Add installed design-system reuse and Liskov-style component substitution guidance: props, callbacks, disabled states, focus, native semantics, and lifecycle ownership. Remove the conflicting “only Open-Closed” restriction.
• Record project fact provenance, command expansion/coverage, freshness, and actual results. Discovered commands remain not-run; historical browser availability does not prove current verification.
• Fix native Claude onboarding/context paths: host overlays stay outside the plugin; absent shared-policy files cannot receive dangling pointers. Cursor live fixtures now place native rules at the host root, matching release archives.
• Expand the harness to 19 public scenarios, including screenshot spec/review, onboarding preservation, instruction migration, stale profiles, Windows log classification, naming, and component substitution. Capture client version, shell, reported capabilities, runner OS, source dirty state, traces, and file hashes.
• Strengthen archive validation with Windows path rejection, duplicate/case collisions, unexpected roots and unsafe types. Extraction fixtures preserve host instructions, local plans, and unrelated Cursor rules.
• Expand issue forms and publish sanitized field observations plus contributor reproduction guidance. Update roadmap, changelog, and release checklist.

Design Intake And Product Decisions

• Supplied Figma links now trigger read-only MCP inspection, with browser/computer-use fallback for missing, failing, or incomplete MCP. Screenshot-only inputs still work without a live provider.
• Intake records component/state coverage and attributes exact properties to the selected layer, parent, variant, and mode. Truncated reads, mixed selections, inaccessible panels, and image estimates remain explicit.
• Product review asks evidence-based questions about unresolved navigation, form opening/dismissal, draft persistence, feedback, responsive behavior, and motion. Recommendations remain proposals; unanswered decisions block dependent implementation while confirmed independent scope can proceed.
• Capability policy, design/intelligence/implementation handoffs, templates, release notes, and 13 additional trigger/capability/output fixtures are aligned. Skill names and version 0.5.0 remain stable.
• Source research: OpenAI Figma implementation skill, Anthropic frontend design, Anthropic design critique, and official Figma tool contracts. Source notes and adaptations are retained in the design references.

At commit 859c82a, the full local validation suite, generated release notes, archive reproducibility, and all three GitHub CI checks pass. Local Prettier could not run because the tool was not installed; required Markdown/YAML/Python CI lint passed. The new fixtures specify expected behavior and are validated statically; no live Figma/browser agent execution is claimed.

Diff-Based Kit Updates

• Add the instruction-only webdev-kit-updater, bringing the inventory to 21 skills. It is scoped to existing installations, not ordinary code work or source authoring.
• Inspect pinned old/new upstream endpoint diffs and reconcile pristine old, local installed, and pristine new client packages. Release notes are supplementary, not the update specification.
• Preserve local project facts, custom skills, instructions, caches, and concurrent changes; gate semantic conflicts and host-policy migrations. Record upstream hashes separately from local adaptations and retain rollback evidence.
• Add public bootstrap instructions in docs/install/upgrade.md for releases that lack the updater. Guide revision and installed release revision remain distinct.
• Local full validation passed for commit e5ddcf4 (about 27 seconds), including all generated targets and existing synthetic checks. No real installation was upgraded and no live agent upgrade behavior is claimed.

Evidence And Routing

Two maintainer-supplied React/Vite project documentation snapshots informed the changes. They are configuration/convention evidence, not live agent transcripts or cross-client compatibility passes. Private source material and project identifiers are not included.

Public cases and instructions:

• Reproducible workflows
• Field evidence and contributor reports
• First-run checks
• Upgrade and rollback

New static cases cover authorized instruction migration, context-refresh near misses, domain naming, component substitution, installed design-system APIs, and stale-session tool claims. Existing schemas, context budgets, test-authoring boundaries, and deterministic eval gates remain intact.

No new React/Next.js skill is introduced from two configuration snapshots. The prototype skill remains experimental pending independent real-client evidence.

Verification

Passed on the submitted source tree:

• python scripts/validate_skill_pack.py: source/schema/policy checks, all six generated targets, 48 cross-client planning smoke cases, target parity, archive validation, and synthetic runner validation.
• 57 scenario preparations: 19 cases across Codex, Claude Code, and Cursor; checks include local-context placement, Cursor discovery roots, screenshot-reference isolation, and unsafe fixture-path rejection.
• Synthetic adapter checks: retained changes, trace success, missing trace, timeout, missing executable, metadata preservation, and refusal to overwrite an existing run.
• All source skill packages pass validate_agent_skill.py through the full source validation.
• Ruff lint and format, YAML lint, Markdown lint, link validation, and git diff --check.
• Two independent release builds: all 10 archives and SHA256SUMS are byte-identical.
• Release archive directory validation and release-note generation with --require-content.

These checks do not execute an AI model. Windows cases are synthetic log replays and path-validation fixtures, not real Windows sandbox runs. Screenshot examples provide a reproducible reference page; operators must capture and attach actual PNGs for live runs.

Risks And Remaining Evidence

• Actual client first-install, upgrade/rollback, and behavior runs remain evidence-collection work. Installation, discovery, adaptation, and successful task execution are separate claims.
• Fresh-context review needs a separate session; self-review is labeled honestly. Blocked runtime checks remain blocked.
• Adapters use the client's normal permissions and sandbox. A fixture directory is not a sandbox. No mandatory provider, credential provisioning, dependency, or automatic paid run is added. Existing optional design-read providers are used only for supplied design sources.
• Existing README files remain unchanged under the explicit-edit policy. The root README's old 19-skill count needs a separately requested documentation edit; the canonical manifest and release notes identify 21.
• Repository-wide Prettier cleanup is outside this change; required CI linters are the validation gate.

Checklist

• Roadmap scope and all open issues reviewed, including comments.
• [Proposal]: AGENTS.md в корне #66 and [medium] Proposal: 0.5.0 evidence-driven frontend workflows #67 implemented and linked for closure on merge.
• Static, synthetic, configuration, and real-run evidence distinguished.
• Permission, test-authoring, lightweight routing, and goal-intake question limits preserved; design-specific review continues in small rounds until its dependent product decisions are resolved.
• Graph links, versions, aliases, and generated contracts validated.
• CHANGELOG and 0.5.0 release checklist updated.
• No private project data, generated dist artifacts, or credentials committed.