@ccoalm/ccl-skills 0.1.0

package/dist/assets/marketplace/plugins/ccl-skills/skills/miniapp-product-dev/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: miniapp-product-dev
+description: "小程序 / Taro / 微信小程序 / 支付宝小程序 / 抖音小程序 / 小程序上线审核 → implement, debug, test, and ship mini-program client features: pages, state, API integration, auth, sharing, platform capabilities, review, and device verification. Triggers also include \"重构这个小程序页面/组件(局部)\", \"refactor a mini-program page/component\"."
+---
+
+# Miniapp Product Dev
+
+Use this skill for mini-program client engineering and platform delivery. It covers product-facing miniapp work across WeChat, Alipay, Douyin/TikTok, Baidu, and similar host platforms. It does not own general product strategy, backend service architecture, or visual design rules.
+
+## Framework Scope
+
+Primary framework target: **Taro** (React-based multi-platform mini-program framework). Apply this skill's recipes assuming Taro unless the task states otherwise.
+
+Adjacent frameworks recognized but not the default target:
+
+- **uni-app / Remax / kbone / mpvue**: recipes here usually apply with framework-equivalent substitutions; verify before assuming behavior.
+- **Native WeChat / Alipay / Douyin / Baidu mini-program**: host-platform contracts (config, capabilities, review, release) carry over; framework-specific code mechanics (JSX/hooks vs WXML/WXSS, lifecycle hooks, runtime APIs) require native-platform substitution.
+- **Embedded H5 inside a mini-program webview**: this skill owns the mini-program shell, bridge contract, host capabilities, and review/release evidence; the H5 React/Vue page belongs to `web-react-dev` (or the relevant web skill).
+
+If the team adopts a non-Taro framework as a new primary, the skill scope must be re-declared rather than letting Taro recipes silently apply to mismatched runtimes.
+
+For evaluating whether Taro is the right choice for a given project (vs native, uni-app, Remax/kbone, or splitting per-platform), read `references/framework-choice.md`. Taro is the current default but not a permanent decision — re-evaluate when the project's target-platform set, design-system divergence, or maintenance signals change materially.
+
+## Maturity Baseline
+
+The current rule set is **vendor-spec + framework-canonical**, not `mature confirmed`. It is grounded in: host-platform official guidelines (WeChat/Alipay/Douyin/Baidu), Taro official documentation and examples, and canonical Taro-ecosystem UI component libraries (taroify, NutUI-Taro, tdesign React mapping). It is not yet confirmed against a production-quality miniapp portfolio observed end-to-end. Treat positive rules as defaults to apply, anti-patterns as guardrails, and upgrade rules to `confirmed` only after they pass a real feature delivery without correction.
+
+**On existing team mini-program codebases**: a team already running a Taro (or other) mini-program codebase does NOT automatically supply positive rules. Production use is evidence of distribution, not of quality. Until that codebase has been audited end-to-end against this skill's rules — or piloted through one real feature delivery cycle with retrospect captured via `skill-extraction-workflow` — it carries the `quality-unverified` label from `references/source-evidence-map.md`. Forward work uses this skill from the start; lessons from the existing code flow back through the extraction workflow, not by silently lifting patterns.
+
+## Runtime Compatibility
+
+This skill is shared by OpenCode, Codex, and Claude Code. Keep instructions tool-agnostic: prefer repository-local scripts, platform developer tools, CLI commands, simulator evidence, screenshots, and explicit manual checks over host-specific features. When a tool is unavailable, record the missing evidence and use the closest deterministic check instead of pretending the platform was verified.
+
+## Routing
+
+- Use `product-rd-workflow` first when the work spans product intent, design, service contracts, implementation, test, review, release, and follow-up.
+- Use `product-ui-ux-design` before or alongside coding for visible page structure, interaction model, density, empty/error/loading states, trust copy, accessibility, and launch acceptance.
+- Use `../product-ui-ux-design/references/multi-stack-strategy.md` and `../product-ui-ux-design/references/multi-project-token-consistency.md` when the mini-program is one of several client stacks under one brand (web desktop + H5 + native app + mini-program). Cross-end brand alignment (color tokens, typography, voice/tone, terminology, navigation labels, trust copy) is owned there, not here. This skill enforces the host-platform constraints on top of those tokens. For the **scope** of what must align across web + app + mini-program (beyond just theme and logo — including auth/onboarding copy, error vocabulary, payment confirmations, privacy disclosures, share/QR payload schema, deep-link routes), read `references/cross-stack-alignment.md`.
+- Use `web-react-dev` for the React layer when Taro shares code with a React web project (see Sibling Boundary below).
+- Use backend architecture/dev skills for API contracts, auth services, payment callbacks, subscriptions, persistence, async jobs, and admin/ops surfaces.
+- For backend HTTP integrations, preserve current client wire behavior unless an explicit consumer-migration decision exists. Classify JSON vs protobuf-backed HTTP using `../platform-service-connectivity/references/protobuf-http-contract-signals.md`.
+  - First decide whether the client diff touches the HTTP contract or wire behavior. Wire-unchanged page/component/state work does not need a backend owner round-trip and must not claim backend contract conformance.
+  - For unrelated client work, classify the diff with the canonical gate. If the surface is out of scope, client work may continue without claiming backend contract conformance.
+  - If the canonical gate classifies the diff as in scope, confirm the backend's recorded wire format or route back to the backend contract owner.
+  - Routine JSON/OpenAPI changes use the existing API contract record and do not require backend wire-format confirmation when the canonical reference classifies the surface as out of the protobuf wire-format gate.
+  - Mini-program request wrappers must consume the backend contract's recorded response envelope per `../platform-service-connectivity/references/http-response-envelope-contract.md`: for surfaces on the canonical `code`/`message`/`data` envelope, page/component state reads typed business data from `data`; other shipped or non-JSON envelopes are consumed per their recorded contract. Read only fields present in the recorded contract — do not infer business fields from unrecorded top-level or fallback shapes — and scatter no duplicate envelope parsing across the client.
+  - If backend wire-format evidence is unreachable for an in-scope surface, stop at `pending-contract-owner`, name the backend owner or owning repo, record the attempted lookup, and set the next escalation path. An assumed-wire-format note never unblocks merge. The blocker clears only when a checkable owner record, quoted prior backend record, or explicit migration decision is available; if no owner responds within the team's review SLA, keep the client change blocked or downscope the touched wire-format surface and record the dropped surface as an open owner-routed gap. Do not claim backend contract conformance or completion for the removed slice.
+  - Do not fork IDL or hand-maintain duplicated DTOs in the mini-program repo.
+- Use `testing-strategy` to choose unit, component, integration, miniprogram automation, E2E, manual device, and release verification layers.
+- Use `test-artifact-management` when the ask is about generating structured test cases from a Feishu requirements doc or codebase and tracking them in Feishu Bitable before implementation begins.
+- Use `defect-diagnosis` first for crashes, failed builds, platform review rejection, flaky device behavior, auth/payment/share failures, or production symptoms.
+- Use `feature-risk-router` when the slice touches money, login/identity, user data, permissions, generated/AI content, write finality, platform review policy, or release risk.
+- Use `skill-extraction-workflow` to feed learnings from real mini-program work back into this skill (or a sibling) — corrections, repeated defects, online-practice uptake, pilot retrospectives. New mini-program work runs through this skill from the start. Recorded extraction passes are necessary evidence for upgrading the maturity baseline, but the full upgrade-path criteria (real feature delivery cycle, host-platform review pass, cross-stack alignment confirmation, correction RCA per defect — see `references/source-evidence-map.md` → "Upgrade Path to `mature confirmed`") all apply; implementation hours alone do not move the baseline. Do not silently mine an older, quality-unverified team codebase for positive rules; route observations through the extraction workflow with the right evidence label (see `references/source-evidence-map.md` → "Team-owned mini-program portfolio").
+
+## Lifecycle and Neighboring Skills
+
+How this skill sits inside the broader delivery loop for a mini-program feature. Each stage names its **owning skill** and what this skill receives from / hands off to it.
+
+| Stage | Owner | What flows into this skill | What this skill hands back |
+|---|---|---|---|
+| Risk classification | `feature-risk-router` | Risk tags (money / identity / privacy / write finality / generated content / host capability), required gates | Confirmation that the gate set covers mini-program-specific risks (review policy, host capability, finality across host pay) |
+| Product / cross-stage delivery | `product-rd-workflow` | Product intent, scope, service contract, release plan | Mini-program-specific delivery considerations (multi-target shipping set, host review timeline, gray release lever choice) |
+| Design (visual, interaction, copy, states) | `product-ui-ux-design` | Design source (Figma), tokens, state enumeration, copy / voice, accessibility criteria; cross-stack alignment is owned in `../product-ui-ux-design/references/multi-stack-strategy.md` + `../product-ui-ux-design/references/multi-project-token-consistency.md` | Mini-program platform constraints on top of the design (safe-area, host gesture, capability denial states, host-native affordance), screenshot acceptance per shipped host |
+| Implementation — React layer + pure shared | `web-react-dev` | Component decomposition, hooks, state ownership, effect discipline, pure shared DTOs / validators / mapping | Mini-program contract on co-owned runtime adapters (auth epoch tuple, request cancellation, storage manifest, finality / idempotency, kill-switch, trace propagation) — enforced via the named co-owned-adapter owner + miniapp-contract tests (see "Sibling Boundary With web-react-dev" → shared-runtime-adapter row for the full gate) |
+| Implementation — mini-program runtime | **This skill** | Taro lifecycle, host APIs, platform branching, subpackage, capability adapters, multi-target build, review-safe copy | — |
+| Implementation — backend services | Go / Python service skills + `llm-inference-integration` | API contracts, server idempotency by `(principal, tenant, action, business-key, fingerprint)`, payment reconciliation, share-token issuance, signed capability grants, server-side feature flags | This skill consumes those contracts. If the backend cannot supply a contract that a **specific** mini-program flow needs (server-business-key idempotency / bounded reconciliation / signed grants / fail-closed flag), route the **block-or-downscope** decision through `feature-risk-router` + `product-rd-workflow` with backend owner evidence — the legitimate exits are remove the risky capability, ship a read-only or non-finality subset, record a deferred-gate row with a tracking ticket, or block. Do not strand the work without an owner. |
+| Implementation — native / cross-platform app | `app-cross-platform-dev` | App-side equivalent surfaces (when the same product also ships native); used for cross-stack alignment cross-checks | — (mini-program is a separate host) |
+| Test strategy | `testing-strategy` | Layer choice (unit / component / API contract / mini-program automation / E2E / manual device / release smoke), scenario matrix | Mini-program-specific evidence requirements (one host compile is not multi-host pass; developer-tool compile is structural only; per-shipped-target real-device evidence is blocking) |
+| Debugging / production symptom | `defect-diagnosis` | Reproduction discipline, 5-Why root cause, regression closure | Mini-program-specific repro paths (developer tool, real device, host version matrix, share/scene param) |
+| Release / review submission / rollback | **This skill** (`references/qa-release.md`) | Per-host evidence matrix, server-flag kill-switch runbook, current platform-policy doc URL + date | — |
+| Post-ship learning capture | `skill-extraction-workflow` | RCA framing, source-evidence labels, dual-track review/challenge gates, sibling-skill mini-map | Updates to this skill's rules, `Do Not` list, references; upgrade-path progress toward `mature confirmed`; recurring anti-pattern entries |
+
+Treat the loop as: **risk-route → product/design → develop (this skill + web/backend) → test → release → debug → extract back**. Skipping the extract-back step is how a team accumulates implementation hours without the skill ever maturing.
+
+Repo-local agent contracts (`AGENTS.md` at the repo root and in source directories) are part of the delivery contract: when a change moves a stable boundary, generated surface, workflow, or directory-local rule, update the nearest contract in the same MR and keep coverage in sync per `product-rd-workflow`'s spec / repo-contract sync gate.
+
+When checking a mini-program project against team standards, split conformance into deterministic and agent review evidence. Deterministic checks cover project config, target/platform build commands, subpackage config, generated API/IDL client usage, environment/lane config, TC traceability, CI gates, and required request/trace identifiers in central request wrappers. Agent review checks cover page/component boundaries, host capability contracts, shared adapter safety, finite-value mapping, multi-target release risk, and whether tests/device evidence cover the shipped targets. For the deterministic executor list (ecosystem ESLint/`@typescript-eslint`/dep-cruiser rules + tsconfig flags) and the mini-program-specific ESLint config that enforces the two host-boundary invariants — `no-restricted-imports` banning `react-dom`/`react-dom/*` (the logic layer has no DOM), and a `no-restricted-syntax` selector confining `process.env.TARO_ENV` branching to the adapter/platform layer (use ESLint, which runs on the AST, not a regex source-scan) — see `testing-strategy/references/fitness-functions.md` §4.1.3 (client language-basics; spec 006).
+
+## Sibling Boundary With web-react-dev
+
+Taro is React syntax compiled to mini-program runtime; a Taro project typically shares a substantial portion of code with a React web project in the same monorepo. Without an explicit boundary, ownership of state hooks, API clients, and shared components drifts.
+
+| Layer | Owner | Notes |
+| --- | --- | --- |
+| React component structure, hooks, JSX, TSX types | `web-react-dev` | Component decomposition, state lifting, effect discipline are the same rules. |
+| Pure shared layer (DTOs, types, validators, pure mapping) | `web-react-dev` (monorepo pkg-shared) | No platform branches; no I/O. |
+| Shared runtime adapters consumed by mini-program targets (request client, auth state machine, storage namespace, finality/idempotency wrapper, observability transport) | **Co-owned with a named final-decision owner** (one engineer per adapter, recorded in repo). `web-react-dev` sets browser semantics; this skill's contract — full session-epoch tuple fencing, request cancellation across route switch, storage namespacing + manifest + historical-prefix purge, sensitive-field handling, late-callback fencing, server-business-key idempotency, pending-reconciliation with bounded timeout on cold start / page-show / re-login, support-id propagation, kill-switch dimensions, trace propagation — is a **blocking acceptance gate** before mini-program targets import the adapter. Web may not merge an adapter change that is browser-safe but mini-program-unsafe; the gate's miniapp-contract tests must pass first — the merge record must carry the fixed token `gate: miniapp-product-dev SKILL.md Sibling Boundary → shared runtime adapters row` plus a passing miniapp-contract run recorded on the change under merge. |
+| Shared design tokens / theme | `product-ui-ux-design` + per-stack injection | Tokens flow from the design source; injection mechanics per `multi-project-token-consistency.md`. |
+| Component library choice (Taroify, NutUI-Taro, tdesign-miniprogram) | **Co-owned** with `product-ui-ux-design`: design owns UX / token / accessibility / brand-fit criteria; this skill owns runtime fit (package size, host-platform compatibility, framework version compatibility, build pipeline integration). Both signoffs required. See `references/framework-choice.md` → "What this skill does NOT decide" and `../product-ui-ux-design/references/multi-stack-strategy.md` for the design source of truth check. |
+| Taro lifecycle (`useReady`, `useLoad`, `useDidShow`, `useDidHide`) | This skill | Page lifecycle differs from React DOM lifecycle. |
+| `Taro.*` runtime APIs (`Taro.request`, `Taro.login`, `Taro.navigateTo`, `Taro.getStorage`, etc.) | This skill | Use the repo's existing adapter when one exists; introduce an adapter for shared or high-risk surfaces (request, auth, payment, storage, host capability). Do not call host APIs ad hoc from arbitrary components. |
+| Platform branching (`process.env.TARO_ENV`, conditional compilation, platform-specific files) | This skill | Branching at the adapter/wrapper layer, not sprinkled in render code. |
+| Subpackage config, preloading, package size budget | This skill | Mini-program-only concept. |
+| Host capabilities (login, pay, share, subscribe message, scan, location, file, scope) | This skill | Capability detection, denial/cancel/timeout/recovery states. |
+| Mini-program app/page config files (`app.config.ts`, `page.config.ts`, platform-specific `project.config.json`) | This skill | Versioning, route registration, tab/subpackage layout, permissions declaration. |
+| Build target, `taro build --type weapp/alipay/tt/swan`, CI matrix | This skill | One target compiling does not prove other targets pass. |
+| Host-platform review submission, gray release, real-device evidence | This skill | Not a web concern. |
+| H5 build target inside a Taro multi-target project | `web-react-dev` for the H5 output's React/browser concerns; this skill stays out unless the H5 is embedded back inside a mini-program webview. |
+
+Cross-checking rule: when editing code shared with a React web project, also check the relevant React rule in `web-react-dev` (state ownership, effects, accessibility, observability). When the code is mini-program-only (config, host API, platform branch), this skill is authoritative.
+
+## Core Workflow
+
+Before editing Taro/native mini-program code, page config, host capability adapters, platform project files, styles, assets, or tests, complete enough analysis and planning for the change to be reviewable. Scale the plan to risk: a simple low-risk single-page change can use a short inline plan; multi-target, user-visible, API-visible, host-capability, platform-review/release, bug-fix, branch/MR, unclear-risk, or high-risk work needs explicit task split, design checkpoint, host/target verification matrix, acceptance checks, verification commands, rollback or stop conditions, and named handoffs to design, testing, web/app, backend, release, or diagnosis skills before edits.
+
+1. Resolve the miniapp platform and delivery shape.
+   - Host platform target(s): WeChat, Alipay, Douyin/TikTok, Baidu, or several at once. Multi-target = a separate verification matrix; one target compiling is not proof another target passes.
+   - Framework: confirm Taro as the project's framework (default for this skill). If the repo is native, uni-app, Remax, kbone, or mpvue, apply this skill's recipes with framework-equivalent substitutions and call out the substitution in the change description.
+   - For Taro: confirm Taro major version, React version, build target list (`taro build --type weapp/alipay/tt/swan/h5/rn`), and which targets are actually shipped vs. listed-but-unverified.
+   - Target: new page, tab, component, package/subpackage, plugin, webview bridge, or platform capability.
+   - Release channel: developer tools preview, experience build, gray release, full release, or platform review submission.
+
+2. Analyze the existing client surface before editing.
+   - Locate page ownership, route registration, tab/subpackage config, app/global state, API client, storage wrapper, auth/session owner, analytics wrapper, and tests.
+   - For Taro: locate `app.config.ts` / `app.config.js` (route + tab + subpackage + permission registration), per-page `*.config.ts`, `config/index.ts` (build config), `project.config.json` / `project.private.config.json` (WeChat target), `project.alipay.json` (Alipay target), `project.tt.json` (Douyin target) and similar per-target project config files, and the Taro plugin pipeline. `mini.project.json` is the native-Alipay project config, not the Taro Alipay project config.
+   - For native miniapp: WeChat uses `app.json` + `project.config.json` + `sitemap.json` + `ext.json` (plugin/extension); Alipay uses `app.json` + `mini.project.json`; Douyin/Baidu use their own platform project files. `manifest.json` + `pages.json` is uni-app shape, not native; only include it when the repo is uni-app. Also inspect package config, build scripts, and CI jobs as applicable.
+   - Identify platform-branching code paths: `process.env.TARO_ENV` checks in Taro, conditional compilation blocks, or platform-specific files (`*.weapp.tsx`, `*.alipay.tsx`). Confirm branching lives at the adapter/wrapper layer, not in render code.
+   - Identify whether the change must be shared, forked, or guarded by capability detection.
+   - For visible changes, map the design checkpoint to page states, navigation/back behavior, permission prompts, loading geometry, error recovery, and screenshot acceptance. Also record `product-ui-ux-design`'s implementation-owner checkpoint before the first edit — its field list (design/stack/test owners, entry-rule evidence, rendered/device evidence status) and copy-only path are authoritative there; load the named owner skills rather than only naming them, and treat a completion claim without `captured/verified` rendered evidence as incomplete — an explicitly accepted gap closes the slice only as `pre-runtime-test ready` / handoff, never as complete/done.
+   - For UI/UX redesign slices meeting `product-ui-ux-design`'s page-slice trigger conditions — that gate's trigger list is authoritative and must be checked, not paraphrased, whenever a screen/surface change could be a redesign, restyle, new-style declaration, structural/visual-system change, continuation, or redesigned-surface reference — apply its cross-stack page-slice gate before Taro or host-platform mechanics: RED-first focused assertion, IA regrouping by user intent/consequence, behavior-contract preservation, state matrix, rendered evidence, and the design verdict (`accepted` / `rejected` / `pending`; missing = `pending`, and `design-rejected` blocks complete/MR-ready/normal/draft MR per the **Rejected-surface rule**). Translate Web/App examples into host developer-tool or real-device proof; a browser/H5-only preview does not satisfy mini-program UI/UX evidence.
+
+3. Define the miniapp contract before coding.
+   - Pages, route params, tab ownership, back behavior, deep links, scene/query entry, and share/open-from-chat behavior. Treat every scene/share/QR param as untrusted input: schema-parse it, server-authorize the referenced target against the current identity, and require backend-issued, TTL-bounded, replay-protected share tokens for attribution or unlock flows. Client-side attribution is never the final source of truth.
+   - API request contract, auth/session renewal, request cancellation or de-dupe, error envelope mapping, retry policy, and trace/request id propagation. Auth must run through a single state machine with single-flight token refresh, a session/user-identity epoch, and stale-callback fencing — concurrent pages must not both silently re-login and overwrite each other's session.
+   - Finite-value boundary: generated API enums, backend string codes, scene/share/QR params, storage values, analytics dimensions, and host bridge payload codes should flow through one typed client/domain mapping module. Pages/components should use mapped symbols and label tables instead of scattering raw values such as `"US"`, `"CN"`, `"active"`, or `"default"` across render, storage, routing, or tracking code. If shared client-domain ownership is unclear, keep a local mapper for the slice, mark temporary duplicate/raw uses with `finite-value-debt: <task-ref> <owner> <deadline> <reason>`, and record the consolidation owner. Architecture owns the cross-stack semantic decision when the same value must align across mini-program, web, app, backend, storage, and analytics.
+   - Storage scope: local storage keys, TTL, sensitive data handling, migration, logout/account-delete cleanup, and stale-cache recovery.
+   - Capability contracts: login, user profile, phone number, location, camera, album, file, scan, payment, subscribe message, share, webview, Bluetooth/NFC, clipboard, and open settings.
+   - Analytics: page exposure, entry scene, click/submit, funnel, error, performance, and release version dimensions.
+   - High-risk finality: **server-enforced** idempotency (business-key dedupe on the backend) is the primary defense; UI duplicate-submit lock is secondary, never the only line. Persist pending order/request id **before** invoking the host-platform action (pay, scan, submit). On cold start / page show / re-login, reconcile pending state against the backend **before** enabling a new attempt. Treat local `cancel` as non-final until the backend reconciliation confirms it — async callbacks can flip cancel → success after the user moved on.
+
+4. Implement with platform constraints visible.
+   - Keep page render code thin; isolate data loading, command handling, mapping, validation, and platform adapters.
+   - Keep platform APIs behind local wrappers when the repo already has them. Do not call host APIs (`Taro.request`, `Taro.login`, `Taro.requestPayment`, `wx.*`, `my.*`, etc.) ad hoc from arbitrary components.
+   - For Taro: confine `process.env.TARO_ENV` and conditional-compilation branches to adapter/wrapper modules. Render components should consume capability-flags or platform-specific files (`*.weapp.tsx`, `*.alipay.tsx`), not branch on `TARO_ENV` inline.
+   - For Taro: do not import `react-dom` or call real browser-only APIs (`document.*` mutation, `window.*` mutation, `requestAnimationFrame`, `IntersectionObserver`/`ResizeObserver`/`MutationObserver`, browser layout APIs) into code that compiles to a mini-program target. Use Taro's cross-platform equivalents (`Taro.createSelectorQuery`, `Taro.nextTick`, lifecycle hooks). Taro 3 ships an emulated DOM that tolerates some neutral usage, but treat real-browser-only APIs as H5-only and isolate them behind the `h5` target (`*.h5.tsx`, capability adapter, or `process.env.TARO_ENV === 'h5'` in adapter code).
+   - For Taro: own durable page/component state in the repo's chosen state owner (Zustand, Jotai, MobX, Redux Toolkit, React Context, TanStack Query, or an existing custom store as appropriate) rather than `Taro.eventCenter`. `eventCenter` is fine for navigation handoff payloads and simple lifecycle events between sibling pages; do not use it as the canonical store for durable, multi-page state. Always register listeners with cleanup in `useDidHide` / `useUnload` / effect teardown.
+   - Respect miniapp package limits, subpackage loading, preloading, image/font budgets, cold-start performance, and first-screen loading. For Taro, every subpackage page must be declared in `app.config.ts` `subPackages`; otherwise `Taro.navigateTo` / `Taro.switchTab` to it fails at runtime. Subpackage preload (`preloadRule` / `Taro.preloadSubpackage`) is a performance optimization, not a navigation prerequisite — verify routing works without preload and that the loading/transition state is acceptable, then add preload as needed.
+   - Route-API correctness is a static rule, not a runtime hope: `tabBar.list` pages must live in the main package and only `Taro.switchTab` may target them; subpackage pages are reached via `Taro.navigateTo` / `redirectTo` / `reLaunch`; `switchTab` to a non-tab page or `navigateTo` to a tab page fails silently or at runtime. Wrap routing in a typed helper that knows each page's route class. Model the cold subpackage-download path (network slow / failed): show loading, handle `fail` callback, allow retry and back fallback — do not let the user stare at a frozen tap.
+   - Model permission denial, permanent denial, settings handoff (`Taro.openSetting` / native equivalent), capability unavailable, offline/weak network, background/foreground restore, and host-version incompatibility.
+   - Keep copy and UI states review-safe for platform policy: privacy prompts, user authorization, payments, ads, medical/financial/legal-sensitive wording, generated content, and UGC moderation where relevant.
+   - Treat webview bridges and plugin APIs as security boundaries, not just contracts.
+     - **Initial allowlist is not enough** — once a webview navigates or executes redirect/XSS, an allowed page can still try to invoke capabilities.
+     - The contract: strict HTTPS origin + path allowlist (an allowed domain with an open redirect is not safe — pin path or use signed routes), nonce/handshake **bound to `(webview-instance, current-route, session-epoch)`** and re-issued on every navigation, **origin/path revalidated on every message** (not only at handshake), **per-message capability invocation requires a server-signed capability grant scoped to the full identity + session tuple `(route, action, session-incarnation, user, tenant, bound-account, permission-scope-hash, webview-instance, short-expiry)`** — route-level opt-in alone lets a compromised allowed page reuse the opt-in across actions, and an incomplete identity binding lets a grant survive a permission downgrade or bound-account switch; the signing dependency has an **offline contract** (pre-mint a short-lived bundle for the route's first interaction; on outage additional capabilities fail closed with explicit unavailable UX — never bypass signing because the backend is slow), schema validation on every payload, timeout, and cleanup on `useDidHide` / `useUnload`.
+     - Treat the embedded page as adversarial input even when it is "your own" H5.
+   - Per-page command/async-work ownership: every long-running operation (request, upload, scan, polling, subpackage download, host capability call) is owned by a per-page controller with abort/cancel, a lifecycle epoch (incremented on page unload, route switch, logout/account-switch), and a late-result-ignore rule — callbacks arriving after the epoch advances are dropped, not applied to a destroyed page or the next user's state. For operations that cannot be canceled (server-side payment, irrevocable upload), reconcile final state via backend on next entry instead of mutating UI from a stale callback.
+
+5. Verify in the right environment.
+   - Run repo formatter, typecheck/build, focused tests, and platform compile commands. For Taro, run `taro build --type <target>` for every target the change touches; one target's success is not the others' success.
+   - **TC traceability**: link tests via the `createTcSuite(test, describe)` factory wrapper. Registers at collection time so `.skip` / `.skipIf` / `.todo` still map to Bitable status. Full overloads supported: `.concurrent` / `.each` / `(name, options, fn)`. Helper from `test-artifact-management/references/tc_helpers/tc.ts`, installed under `test/tc.ts`. See `test-artifact-management/references/tc-marker-conventions.md`. Before adding tests, `grep -rn 'tcTest\|tcDescribe' src/ __tests__/` plus the sidecar `test/results/tc-map.jsonl` to check for existing coverage — extend rather than duplicate. When a TC is marked 废弃, grep both source and sidecar; follow deprecation cascade in `testing-strategy`. Tests without any TC link: prompt user only when the underlying code is also removed.
+   - **废弃级联：业务代码是否仍在用** — 小程序栈混合多种引用机制，单一 grep 不够：
+     1. TS/JS 模块：`npx madge --dependents src/<path>` 或 `grep -rEn "from ['\"][./]*<path>"`
+     2. 页面注册：检查 `app.json` / `app.config.ts` 的 `pages` 数组；若页面 path 不在数组里，整个页面文件可删
+     3. 组件/模板：`grep -rn "<custom-tag>" src/`（usingComponents 在父 json 里声明 + wxml 里使用）；`grep -rn "<wxs.*src=\"<wxs-file>" src/`
+     4. 静态资源：图片/字体被 wxml/wxss 引用 → `grep -rn "<filename>" src/`；分包资源 → 查每个分包 `pages` 列表
+     5. 平台条件编译（Taro 多端）：`#ifdef WEAPP / ALIPAY` 内的 import 在另一端不存在；按目标平台跑 build 看 warning
+   - For visible changes, inspect the rendered page in the relevant developer tool (WeChat DevTools, Alipay IDE, Douyin DevTools, Baidu DevTools), simulator, preview build, or real device and capture evidence where feasible.
+   - For systemic UI/UX redesign slices, diff the declared host target list against repo-configured build targets; every configured target must be classified as shipped (needs rendered evidence), product-level permanently excluded (can complete) — valid only when the authoritative build/release target source already stopped shipping that target before this slice; removing or disabling a target within the slice is a separate product/release scope change that routes through its product/risk/release owners and cannot satisfy this gate's evidence for the same slice; explanatory docs or an MR comment alone are temporary-skip authority, never permanent exclusion — or temporary slice-skip for a shipped target (leaves that host `pre-runtime-test ready` / `blocked`), and any unclassified target blocks completion.
+   - For UI/UX redesign evidence, include declared host targets, host developer-tool or real-device channel, loading/empty/error/final states, long text or text-scale behavior where supported, permission/capability prompts, route/share/scene entry when relevant, and screenshot or equivalent host-rendered artifact. Mark each dimension covered or `N/A` with a one-line reason; `N/A` is valid only when the reason names a verifiable structural fact, explains why that fact makes the dimension unreachable or unchanged for this slice, and includes a checkable pointer such as a file path, config key, or commit that resolves at review time. Persist evidence artifacts where reviewers can access them using sanitized/test accounts and redacting tokens, PII, credentials, private paths, and raw personal data; remove temporary smoke files or generated preview helpers before commit unless the repo intentionally owns them.
+   - For mini-program runtime changes, developer-tool or real-device smoke is a completion gate, not optional evidence. This includes changes to `Taro.*` or host APIs, `wx.*`/`my.*` calls, chunked/streaming transport, foreground/background recovery, route/share/scene behavior, storage/session restore, permissions/capabilities, and host-rendered loading/error/final states. If the tool or device is missing, first attempt discovery and normal setup; if still unavailable, stop at `pre-runtime-test ready` or `blocked` and name the owner, attempted commands, residual risk, and next unblock action. `pre-runtime-test ready` is a handoff-only label; it is not merge-ready, release-ready, or complete.
+   - If an automation, remote-control, or screenshot channel reports a blank or stale mini-program surface while a human operator can see the real host page rendering, treat it as an observation-channel conflict before treating it as an app defect. Re-check focus/window/permission state, capture the human-visible state through another channel when possible, label which evidence came from the automation channel versus the human-visible host, and only mark "blank screen" as a product defect after at least one host-visible channel reproduces it.
+   - When a human operator's already-authenticated host client or device is used as the runtime test surface, treat it as a human-assisted host test: record observer role/source class, sanitized account class, host client/device, entry path, actions performed, redacted artifacts, state changes such as login/logout or permission prompts, and restoration outcome in the project evidence. Label it as manual, scenario-scoped evidence; it does not replace required automated assertions or other host checks. If requested logout/account-switch/storage/permission restoration is not confirmed, mark the host test blocked or incomplete until restored or handed off to a named owner. Do not record personal phone numbers, personal operator names, chat/contact handles, tokens, private account names, or reviewer credentials in shared artifacts.
+   - Treat appid, dev-tool login, plugin authorization, service-port availability, and host identity/configuration as part of the runtime verification surface, not as background noise. A generated preview QR or a backend login success does not prove the mini-program runtime path until the correct host/app identity and permissions are exercised in the tool or on device.
+   - Verify route entry, share/deep-link scene params, auth state, storage restore, network error, permission denial, and primary recovery path for affected flows.
+   - For detail pages and deep-link/share/QR entry points, test missing or stale route params, missing local storage/cache payloads, expired auth, and direct cold entry. These states must resolve to an explicit empty/error/recovery state or safe redirect; a permanent loading spinner or blank screen under cold entry or missing-param entry is a blocking defect that must be fixed or explicitly marked `blocked` with a real owner, resolution path, and target follow-up point before the flow can be called complete. For stale storage/cache, include at least one real-device or emulator state test with a prior-version or manually seeded cache payload. Developer-tool-only stale-cache evidence is fallback evidence and must be labeled as a `device-state gap`; a flow with an open `device-state gap` is `blocked` or `pre-runtime-test ready`, not complete.
+   - For payment, subscription, login, phone, camera/media, or write-finality changes, verify sandbox/mock plus one platform-specific happy path. If platform evidence is unavailable after remediation, stop at `pre-runtime-test ready` or `blocked`; do not complete the work by only recording the gap.
+   - For release work, verify app id/env, version, build output, platform review checklist, gray release/rollback path, analytics version tag, and owner handoff. For every **shipped** host platform, compile + developer-tool/real-device evidence is blocking — "recorded as unverified" is only acceptable for targets the release is not actually shipping. Mini-program rollback through host-platform re-review is slow; risky flows must therefore have a **server-side feature flag with safe default + tested kill-switch runbook** in place before submission. Capture the current official platform-policy doc URL + date for every review-sensitive area touched (payment, privacy, AI/generated content, minors, financial/medical/legal copy) — policy text changes faster than skill rules.
+
+## Non-Negotiable Rules
+
+- Do not treat a browser or H5-only preview as proof that a miniapp platform passes. For Taro, `taro build --type h5` passing is not evidence that `weapp`/`alipay`/`tt`/`swan` targets pass.
+- Do not push large or high-frequency `setData` payloads across the logic↔render bridge. `setData` serializes its payload from the logic thread to the render thread on every call, so a multi-hundred-KB payload or a per-scroll-tick / per-keystroke call janks rendering, and the host drops an oversized call (WeChat documents a per-`setData` size limit on the order of 1 MB — confirm the exact current value in the platform docs). Send only the changed fields via data-path keys (e.g. `this.setData({'list[3].done': true})`), not the whole list; throttle/debounce high-frequency updates; and page or virtualize long lists rather than re-pushing the full array. (WeChat 小程序平台性能优化指南：`setData` 数据量与调用频率，以当前官方文档为准；Taro `setState` compiles to `setData`, so the same limit applies.)
+- Do not call multi-platform miniapp work complete because one host platform compiled.
+- Do not add direct platform API calls when the repo has wrappers or adapters.
+- Do not import `react-dom` or use real browser-only APIs (DOM mutation, browser observers, RAF/layout APIs, browser globals) in Taro code that compiles to a mini-program target; isolate that code behind the H5 build target.
+- Do not sprinkle `process.env.TARO_ENV` branches inside render code as a project convention; confine platform branching to adapter/wrapper modules or platform-specific files. (Taro permits inline branching; the guardrail is a maintainability rule, not a framework limitation.)
+- Do not use `Taro.eventCenter` as the canonical owner of durable cross-page state; reserve it for navigation handoff and simple lifecycle events, and clean up listeners on `useDidHide` / `useUnload`.
+- Do not ship a page without verifying route registration, entry scene/share params, tab vs. `navigateTo` vs. `switchTab` vs. `redirectTo` vs. `reLaunch` semantics, and page-stack depth budget. Routing defects are a leading cause of host-platform review rejection.
+- Do not leave async work running across page hide/unload or route switch: every long-running operation lives under a per-page controller with cancel + lifecycle epoch + late-callback ignore. Callbacks arriving after the epoch advances are dropped.
+- Do not let any money / quota / publishing / account-finality mutation rely on a client-side UI lock alone — server-enforced idempotency by business key is the primary defense. Persist pending state before invoking the action; reconcile against backend on cold start / page show / re-login before enabling a retry. Treat local `cancel` as non-final until backend confirms.
+- Do not let logout / account-switch leave in-flight work alive: increment the auth epoch, abort pending requests / uploads / pollers, clear query caches and storage namespaces, and drop any callback whose epoch is stale.
+- Do not store sensitive durable fields (phone, profile, tenant flag, identity proof, payment metadata) in raw mini-program storage by default. If durable storage is required by product, namespace by user + tenant + platform + app-version, bound by TTL, prefer encrypted or server-backed storage, and add a purge test that runs on logout/account-delete.
+- Do not trust scene / share / QR / webview-bridge payloads: schema-parse, server-authorize against current identity, require backend-issued and TTL-bounded share tokens with replay protection, and gate webview bridge by HTTPS origin + path allowlist + per-message capability allowlist + nonce.
+- Do not scatter backend enum/string literals through mini-program pages, scene/share/QR parsing, host bridge payload handling, storage, analytics, or tests. Centralize finite-value parsing, display labels, defaults, and unknown-value behavior at the API/client-domain boundary, and keep raw literals only in clearly named boundary conversion tests that cover every known external value plus unknown/default behavior. Migrate existing non-boundary test raw literals for that value in the same pull request or mark each remaining use with `finite-value-debt: <task-ref> <owner> <deadline> <reason>`, even when the current slice does not introduce a new mapper.
+- Do not ship auth, payment, phone, location, camera, share, subscription, or generated-content flows without explicit denial/error/retry states.
+- Do not ship a host platform without compile + developer-tool/real-device evidence for that platform — "recorded as unverified" is only acceptable for non-shipped targets.
+- Do not claim a mini-program runtime fix is complete when developer-tool or real-device smoke did not run. Build output, unit tests, source-regex checks, and independent code review can make the branch `pre-runtime-test ready`; they cannot make host-runtime behavior complete.
+- Do not submit a risky flow for platform review without a server-side feature flag (safe default + kill-switch runbook); platform-review rollback is too slow to be the only lever. The flag does not stop client-only effects (permission prompts triggered at startup, SDK auto-collection on load, host-platform config already submitted) — the flow's **client-side code path itself must no-op when the flag is off**, the SDK must not load until the flag is on, and any host-config change submitted at review time must be reviewed for "what if we need to disable this without a new submission" before approval.
+- Do not ship review-sensitive surfaces (payment, privacy disclosure, AI/generated content, minors, financial/medical/legal copy, account deletion, SDK data collection) without naming the current platform-policy doc URL + date you read.
+- Do not claim platform review or real-device readiness without current evidence.
+- Do not put private app ids, secrets, tokens, reviewer accounts, or internal product names into this skill or shared references.
+
+## Reference Loading
+
+- For source provenance, current extraction boundary, and keep/merge/discard decisions, read `references/source-evidence-map.md` when auditing or re-extracting this skill.
+- For platform-specific capability and config checks, read `references/platform-capabilities.md`.
+- For product/page acceptance and UI state checklist, read `references/product-page-checklist.md`.
+- For API, auth, storage, analytics, and high-risk finality contracts, read `references/contracts-and-state.md`.
+- For QA, developer-tool, real-device, review submission, release, and rollback checks, read `references/qa-release.md`.
+- For framework choice (Taro vs native vs uni-app vs Remax/kbone vs per-platform split) and decision factors, read `references/framework-choice.md`.
+- For cross-stack alignment scope (what must align across web + app + mini-program beyond theme/logo — auth copy, error vocabulary, payment confirmation, privacy disclosure, share payload schema, deep-link routes), read `references/cross-stack-alignment.md`.
+- For incorporating online best practices (canonical Taro / WeChat / Alipay / Douyin examples, top-tier mini-programs as UX idiom library, vetting weak vs strong online sources) without overclaiming what observation can prove, read `references/online-practice-uptake.md`.
+- For cross-stack brand alignment (web desktop + H5 + native app + mini-program sharing one brand), read `../product-ui-ux-design/references/multi-stack-strategy.md` and `../product-ui-ux-design/references/multi-project-token-consistency.md`.

package/dist/assets/marketplace/plugins/ccl-skills/skills/miniapp-product-dev/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Miniapp Product Dev"
+  short_description: "Build and ship mini-program product features"
+  default_prompt: "Use $miniapp-product-dev to design, implement, test, or release a WeChat, Alipay, Douyin, Baidu, or similar mini-program feature."

package/dist/assets/marketplace/plugins/ccl-skills/skills/miniapp-product-dev/references/contracts-and-state.md

@@ -0,0 +1,62 @@
+# Contracts And State
+
+Use this reference when miniapp work touches API integration, auth, storage, analytics, or finality.
+
+## API Contracts
+
+- Define request params, response envelope, error codes, retryability, idempotency, and trace/request id behavior.
+- Map backend errors to user-facing copy and recovery controls; do not expose raw transport errors.
+- Preserve cancellation semantics for route changes, repeated taps, pull-to-refresh, and background/foreground transitions.
+- For long-running operations, define polling, refresh, timeout, and final-state reconciliation.
+
+## Auth And Identity
+
+- Separate platform login code, app session token, bound account, phone/profile authorization, and backend identity.
+- Centralize auth in one state machine. Token refresh runs as **single-flight** — concurrent expired-token responses share one in-progress `Taro.login` + code-exchange, never two parallel exchanges where the slower one overwrites the newer session.
+- Maintain a **session epoch** that is the tuple `(session-incarnation-uuid, user-id, tenant-id, bound-account-id, permission-scope-hash)`, not a bare monotonic counter. App restart generates a new session-incarnation-uuid so old persisted state cannot validate against a reused counter. Increment / regenerate the epoch on login, logout, account switch, **and on any silent token refresh that returns a different subject / tenant / bound-account / permission scope** — silent refresh is not always same-user, and old callbacks that wrote "under the same counter" can otherwise leak across identities. Every request, upload, poller, host-capability call captures the full epoch tuple at start; callbacks whose tuple does not match drop their write.
+- Model expired session, failed silent login, user-declined authorization, account switch, logout, and account deletion.
+- On logout / account deletion / account switch, the sequence must hold even when each step has implementation subtleties:
+  0. **Before any purge, confirm external-finality pending operations are server-ledgered**: every pending external-finality row (payment via host gateway, third-party upload, etc.) must already exist on the backend under the old `(principal, tenant, business-key, idempotency-key)` with a discoverable support id. Purge deletes only the local mirror, never the source of truth — next login (whether same user or different) reconciles external finality from the server, not from local pending rows. If a host-finality operation is still in-flight when logout is invoked, surface a warning ("a payment/upload is still in progress; logout will keep it running on the server — you can recover it from the receipts page") and let the user confirm; do not silently strand the operation.
+  1. **Capture the old identity + prefix set from the pre-advance auth context** (read `user-id`, `tenant-id`, `bound-account`, the storage manifest's prefixes for this identity, in-flight operation list) — once epoch advances, the old subject may not be reconstructible from in-memory state.
+  2. **Publish the epoch advance and a new-session activation barrier in one atomic step** — new login attempts queue behind the barrier until purge completes.
+  3. Cancel in-flight requests / uploads / pollers / host-capability callbacks captured in step 1.
+  4. Purge the captured namespace prefixes AND any declared **legacy global / unscoped sensitive keys** (keys written by older app versions before user+tenant namespacing existed — declared in the storage manifest as `legacy-global` so the cleanup is explicit, not silent).
+  5. Clear in-memory state, webview state, query cache, and stale route assumptions.
+  6. Release the activation barrier; new sessions may now activate.
+
+  A new login that starts before purge finishes can delete or repopulate the wrong user's data; the activation barrier is what enforces "purge first, then welcome the next user".
+- Avoid collecting profile, phone, location, or media permission before the user action that needs it.
+
+## Storage
+
+- Use repo-local storage wrappers when available.
+- Default-deny durable storage of sensitive fields (phone, profile, identity proof, payment metadata, tenant/role flags, location, raw tokens). If product explicitly requires durability, the field passes through a checklist: namespaced by the **full identity scope needed for restoration** — minimum `user + tenant + bound-account + platform + app-version`, plus `permission-scope-hash` for fields whose validity depends on the user's current permissions, bounded TTL, encrypted at rest or server-backed, and covered by a purge test that runs on logout / account-delete / account-switch.
+- **Canonicalize identity sentinels**: for single-tenant deployments use `tenant=deployment:<deployment-id>`, never raw `null` / omitted; for products without a bound-account concept use `bound-account=user:<user-id>` so the namespace key is well-defined. Never let `null` / `undefined` / missing become a valid identity component — different "no value" representations collide into the same namespace and cross-leak between users on shared-device or family-account flows.
+- Maintain a **storage manifest** that lists every namespace prefix the app uses (including historical app-version prefixes from upgrades) AND any **declared `legacy-global` keys** — unscoped sensitive keys written by older app versions before user+tenant namespacing existed. Purge / migration on logout / account-delete / account-switch consults the manifest and clears **all** historical prefixes for the user PLUS the `legacy-global` set. Old-app-version sensitive keys and pre-namespacing global keys must not survive an identity change; the manifest is the audited registry of "what could possibly hold sensitive state".
+- Define key owner, namespace, TTL, migration, invalidation, and cleanup for every key.
+- Mini-program storage is **device-scoped**, not user-scoped. On shared devices the next user inherits whatever the prior user left behind unless the namespace and purge discipline above is enforced.
+- Validate restored state against the full session epoch tuple (incarnation + user + tenant + bound-account + permission-scope), current route params, host platform, and app version. Stale restored state must be discarded, not silently applied.
+
+## Analytics
+
+Track enough to debug and evaluate product behavior:
+
+- Page exposure and unload.
+- Entry scene/source, route params class, campaign or share source where allowed.
+- Click/submit, validation failure, permission denial, retry, cancel, success, and final failure.
+- API duration, error class, and request id in redacted form.
+- Release version, platform, host version, and feature flag dimensions.
+- **Error / crash reporting field set** (whether the project uses platform-native error reporting, Aegis / Sentry / Bugly equivalent, or a custom backend pipeline): each report MUST carry release version, host platform + host-client version, scene value, route + route params (sanitized), request id, sanitized error class (no PII / token / raw payload), session-incarnation, and the same identity-tuple fields used for tracing. Without these, an error report is unjoinable to back-end logs. SDK auto-capture (page crash, network failure, JS error) is subject to the privacy disclosure rules in `platform-capabilities.md` Review Policy Awareness — auto-capture without inventory declaration is a review-rejection risk. Field whitelisting at the reporter, not field-redaction-in-pipeline, is the safer default for PII.
+
+## High-Risk Finality
+
+Use this checklist for payment, quota, order, publishing, generated content, account, permission, or irreversible writes:
+
+- **Server-enforced idempotency** by client-generated **idempotency key**, generated and persisted on the client **before any backend mutation call** (before order-create, before submit, before pay-invoke). The backend stores `{principal-user-id, tenant-id, action-class, business-key, idempotency-key, request-payload-fingerprint}` immutably and **rejects a second call whose principal / tenant / action / payload-fingerprint does not match the first call's record under the same key** — a bare client-generated key replayed across users, tenants, actions, or with a different payload must not collide into the first call's effect. Even if the server processed the create but the client never saw the response, the next launch finds the persisted key and reconciles by key, not by order id.
+- UI duplicate-submit lock and visible pending state — **secondary** only. A UI lock that disappears on refresh, route switch, app kill, or second-device attempt is not a safety property; the server idempotency above is.
+- **Persist pending state before the action**: the pending row carries `{idempotency-key, business-key, action-class, timestamp, session-epoch-tuple}` and is written *before* calling `Taro.requestPayment` / `Taro.uploadFile` / submit. If the app is killed at any point, the next launch sees the pending row.
+- **Cold-start / page-show / re-login reconciliation has a bounded timeout and a 'state uncertain' recovery path**. On every entry point that could create a new high-risk action, look up pending state, reconcile against the backend (final / still-pending / canceled), with a bounded timeout (e.g. 5–10 s). On timeout or backend outage, do NOT deadlock the user: surface "state uncertain", expose support id + idempotency key, and offer recovery. **Recovery scope depends on whether the action is server-owned or externally final**: server-owned reversible actions (draft submit, server-side queue work) MAY use a server-authorized abandon path (server marks the key abandoned, new attempt allowed). External finality actions (payment via host pay gateway, third-party uploads, anything where an external provider can still report success after our timeout) **must NOT abandon until the external provider's ledger is reconciled** — abandon-then-retry would let the old provider callback succeed in parallel with a new attempt. For these, the recovery path is "wait + retry reconcile" or "open support case", not "abandon and try again". Without bounded recovery, one corrupt pending row blocks the user; without the abandon-scope rule, abandon causes double-finality bugs.
+- **Cancel is not final.** Local cancel (`requestPayment` fail/cancel, user backs out, network error) does not mean the backend operation didn't succeed. Show "checking final state" until backend reconciliation confirms. Async callbacks routinely flip a locally-canceled payment to success.
+- Callback/reconciliation path for payment or async work, with order/request id matched on both sides.
+- Support-visible order/request id surfaced to the user; without it, support cannot disambiguate "I paid but app says canceled".
+- Safe retry and user explanation for uncertain final state — never present "succeeded" or "failed" when reconciliation has not run.

package/dist/assets/marketplace/plugins/ccl-skills/skills/miniapp-product-dev/references/cross-stack-alignment.md

@@ -0,0 +1,94 @@
+# Cross-Stack Alignment
+
+Use this reference when the mini-program is one of several client stacks (web desktop, H5, native app, mini-program) sharing one product/brand. It enumerates the **scope** of what must align across stacks — beyond color tokens and the logo — so the mini-program implementation can call out misalignment instead of silently diverging.
+
+This reference owns the **enumeration of alignment surfaces** the mini-program must check. The actual design rules (token system, voice/tone, brand assets) are owned by `product-ui-ux-design/references/multi-stack-strategy.md` and `multi-project-token-consistency.md`. This file maps what mini-program-side implementation has to verify against those design sources.
+
+## Alignment surfaces
+
+### Visual / brand layer (design source of truth)
+
+Owned upstream by `product-ui-ux-design`; verified here that the mini-program implementation reflects the source faithfully.
+
+| Surface | Aligned across stacks | Mini-program-side check |
+|---|---|---|
+| Color tokens | Primary, neutral, semantic (success/warning/error/info), surface tiers | Are mini-program theme variables sourced from the same token set, not redrawn locally? Inspect ALL of the host-platform theme entry points before concluding: (1) global theme slot (`app.json` `themeLocation` + `theme.json` for WeChat, equivalent for Alipay/Douyin/Baidu/QQ); (2) subpackage-local theme files when subpackages override; (3) generated WXSS / CSS-variable token injection (Taro / uni-app / native build-time token transform); (4) cross-framework token imports (`@import "tokens.scss"`, Taro `App.scss` token modules); (5) rendered primary on a real page in the host devtools or device. An empty / absent global `themeLocation` is a **detection signal that triggers the deeper inspection**, not a standalone verdict — a compliant mini-program may legitimately inject tokens through (2)–(4) without using the global slot. Fail only when all five layers fail to deliver the brand token; that case is the mini-program equivalent of the "empty framework-wrapper theme config" cross-stack anti-pattern in `product-ui-ux-design/references/multi-project-token-consistency.md`. |
+| Typography scale | Font family per language, size scale, weight scale, line-height scale | Verify mini-program text sizes map to the same scale even when host renders `rpx` differently. |
+| Spacing scale | 4/8 (or project's chosen) grid; standard component padding/margin tokens | Check that mini-program component padding matches the token, not the framework default. |
+| Iconography | Source set, sizes, stroke weight, on-brand exceptions | Verify the mini-program's icon font/SVG set is the canonical set, not a host-specific replacement. |
+| Logo / wordmark / app icon | Per-host packaging (square/round, light/dark, sizes) | Verify the mini-program app icon and within-app brand mark match the brand asset library. |
+| Imagery / illustration | Brand style, photography vs illustration boundaries | Verify hero / empty / error illustrations match the cross-stack set. |
+| Motion / transition | Duration scale, easing, when motion is used vs suppressed | Verify mini-program transitions match the cross-stack pattern; do not adopt host-default-only animations. |
+
+### Voice / copy / vocabulary layer
+
+Subtle, high-leakage misalignment surface. The product feels "off" when the same action has different copy across stacks.
+
+| Surface | What aligns | Mini-program-side check |
+|---|---|---|
+| Action verbs | "保存 / 提交 / 确认 / 完成" — pick one verb per action class | Mini-program does not use a different verb for the same action than web/app. |
+| Error vocabulary | "未登录 / 登录失效 / 无权限 / 网络异常 / 服务器繁忙" — fixed strings | Mini-program error toast/dialog copy comes from the same string library. |
+| Empty-state copy | "暂无数据 / 还没有内容 / 即将开始" — chosen tone | Mini-program empty states match the cross-stack tone, not a generic host default. |
+| Trust / safety copy | Payment confirmations, account-delete, data-collection consent, share-attribution copy | Identical or controlled paraphrase across stacks; legal review confirms every variant. |
+| Privacy disclosure | Phrasing of what is collected, why, how to revoke, data-deletion path | Same language across stacks (legal liability is shared). |
+| Brand voice | First-person vs second-person, formality, English/Chinese mixing rules | Mini-program follows the cross-stack guide. |
+| Terminology / domain nouns | One canonical name per domain object (e.g. "工单" vs "任务" vs "事项") | Mini-program uses the same noun the web/app uses; no host-specific synonyms. |
+
+### Interaction / navigation layer
+
+Each host has its own primitives; alignment is about **mental model**, not pixel-identical UI.
+
+| Surface | What aligns across stacks | Mini-program adaptation |
+|---|---|---|
+| Primary navigation labels | Tab/menu labels and order across stacks where the product surfaces are equivalent | Mini-program tab labels match web/app top-level concepts; reorder only when host UX strongly favors a different order, and document the divergence. |
+| Auth / onboarding flow | Identity model (phone / wechat / email), bound-account semantics, first-login setup steps | Mini-program login path produces the same `user_id` + permissions as web/app login; one user, one identity across stacks. |
+| Account / profile structure | Account settings hierarchy, privacy controls, security actions, account deletion | Mini-program "我的"/profile surfaces match the cross-stack list; do not silently omit privacy/legal/about routes. |
+| Payment / order flow | Steps (review → pay → result), pending/cancel/success copy, support-id surfacing | Mini-program payment screens follow the same step model; the receipt looks like the same brand's receipt across stacks. |
+| Share / deep-link payload | **Opaque token** issued by backend, bound to `(audience, platform, route, action, target, target-tenant, issuer-user, issuer-tenant, redeemer-permission-scope, expiry)` — the issuer principal + tenant must be recorded so the redeemer's permissions are checked against the issuer's authorization at redeem time, not just at issue time; multi-tenant target IDs may collide across tenants, so target-tenant is part of the binding; `issuer-vs-redeemer` semantics are explicit (e.g. invite tokens are issued by one user for another to redeem; capability tokens are issued for the same user to consume on a different channel). The backend exchanges the opaque token for the resolved target after verifying redemption-context channel + redeemer eligibility + issuer permission still valid. | Mini-program redeems share tokens through the backend; rejects tokens whose channel / target-tenant / issuer-permission no longer matches; does not assume issuer-user == redeemer-user. |
+| Notification / push contract | Topic/template names, channel mapping, opt-in/opt-out model | Mini-program subscribe-message templates map to the same notification topics web/app use. |
+| Error / recovery paths | "What did the user see when X failed and what do they do next" | Mini-program error screens offer the cross-stack-equivalent recovery (retry / refresh / re-login / contact support). |
+
+### Data / contract layer
+
+Below the visible UI, alignment means same backend identity, same business semantics, same audit trail.
+
+| Surface | What aligns | Mini-program-side check |
+|---|---|---|
+| User identity | Same `user_id` + tenant resolution rules across stacks | Mini-program session resolves to the identical user/tenant; no host-specific identity. |
+| Permissions model | Same scope/role/feature-flag dimensions | Mini-program reads from the same permission service; no client-side permission table. |
+| Tracking event names | Same event name per action across stacks; platform dimension is a tag, not a different event | Mini-program analytics emits `<event>` with `platform=miniapp/<host>`, not a renamed event. |
+| Error class taxonomy | Same error codes / classes mapped across stacks | Mini-program maps host errors into the cross-stack class set. |
+| Locale / i18n | Same locale set, same translation keys, same fallback chain | Mini-program reads from the same i18n source. |
+| Time / formatting / currency | Same date/time/number/currency formats per locale | Mini-program formatters use the shared utilities, not host defaults. |
+
+### Compliance / legal layer
+
+Cross-stack alignment here is not aesthetic; misalignment is a regulatory risk.
+
+| Surface | What aligns | Mini-program-side check |
+|---|---|---|
+| Privacy policy text | **Canonical base policy** (the cross-stack truth) **plus per-platform annex** (host-specific SDKs, host-specific permission disclosures, host-specific data-collection requirements that the canonical base does not name), each annex versioned. | Mini-program review matrix checks both the base policy version AND the platform-specific annex; the per-platform annex covers what the host platform's review will ask about. |
+| User agreement / ToS | Same document, same versioning | Mini-program accept-flow records same version. |
+| Data-collection consent | Same matrix of fields × purposes × opt-in mechanism | Mini-program collects only what the cross-stack matrix permits. |
+| Account deletion / data export | Same path, same SLA, same evidence | Mini-program account deletion produces the same data lifecycle as web/app. |
+| Minors handling | Same age gate / parental consent flow | Mini-program implements the same gate; do not relax it because the host happens not to enforce. |
+| Region / regulatory carve-outs | Per-region rules (PIPL / GDPR / CCPA / India DPDP / etc.) | Mini-program respects region-specific behavior the cross-stack policy declares. |
+
+## Alignment check ritual (mini-program-side)
+
+Run this before declaring a mini-program release ready when it shares a brand with another stack:
+
+1. List the alignment surfaces this release touches.
+2. For each, name the **cross-stack source of truth** (Figma project, design tokens repo, copy library, i18n keys, privacy doc URL, analytics event registry, identity service).
+3. **Run the design-source health check before consuming a design source**: see `product-ui-ux-design/references/multi-project-token-consistency.md` → "Design-Source Health Check (Pre-Consumption Gate)". The check covers five failure classes — undeclared third-party mirror / vendor-derived source, drift inside one source, unresolved placeholder values in a shipped semantic tier, no source provenance, no versioned snapshot. If the design source fails the gate, **scope the block to the affected token classes the mini-program release would consume** (an unrelated unresolved-semantic-tier finding does not block a release that consumes none of the broken roles); copying a broken source into the mini-program just propagates the brokenness and will surface as findings during cross-end review. The escape valve described in that reference (time-boxed provisional consumption with design owner + risk owner approval, pinned source version, "not fully aligned" label, expiry date) applies here too.
+4. For each, confirm the mini-program implementation reads from / matches that source. "Reads from" does not require runtime fetch on cold start — generated versioned snapshots (built at release time, shipped in the package, validated by source hash + drift check in CI) are acceptable. The discipline is **no silent drift**, not "must call the source at runtime".
+5. Capture screenshots / sample copy / event sample for each touched surface; compare against web/app equivalent.
+6. Record any **intentional divergence** with rationale ("this is the host-platform convention; we adopt it for X reason"); the cross-stack design owner approves the divergence.
+7. Land cross-stack alignment as a release checklist item, not as an afterthought QA pass.
+
+## What this skill does NOT decide
+
+- The token system, voice guide, or brand asset library — owned by `product-ui-ux-design`.
+- The backend identity / permission / event taxonomy — owned by backend skills.
+- The product strategy of which stacks to ship — owned by `product-rd-workflow`.
+- Per-stack design language deviation — that's a design judgment; this file just makes the deviation explicit so it isn't accidental.

package/dist/assets/marketplace/plugins/ccl-skills/skills/miniapp-product-dev/references/framework-choice.md

@@ -0,0 +1,76 @@
+# Framework Choice
+
+Use this reference when deciding whether **Taro** is the right framework for a new mini-program project, or whether to migrate an existing project to a different framework. The skill's default is Taro; this file documents how to test that default against a specific project.
+
+## When to re-evaluate
+
+Re-evaluate framework choice when any of the following changes:
+
+- Target host platforms expand or contract (e.g. dropping WeChat or adding Douyin/Baidu changes the multi-target gain).
+- Design system diverges per host beyond what tokens can absorb (each host needs distinct interaction idioms).
+- The shared monorepo's web/React + mini-program code coupling becomes painful (drift, branching, runtime bugs).
+- Build-time, package-size, or cold-start budgets become release-blockers.
+- The team's React/TypeScript expertise no longer matches the runtime (e.g. team migrated to Vue, or the React layer is mostly read-only).
+- Taro / underlying framework has a material breaking change (Taro 3 → Taro 4 class of event) and migration cost is non-trivial.
+- Host platform releases a substantial native feature (e.g. WeChat Skyline) that the multi-platform framework lags on.
+
+A framework decision is not permanent. Annual or release-train review is healthier than waiting for a forcing event.
+
+## Decision factors
+
+Compare candidates along the dimensions below. No single dimension wins; the **combination** does. Score each candidate `strong / acceptable / weak / blocking` against the project's actual needs (not against the abstract framework).
+
+| Dimension | What it asks |
+|---|---|
+| Target-platform set | How many hosts must this project ship? One host = native often simpler; 2+ = multi-platform framework usually pays. |
+| Shared-code gain | What fraction of code (component, state, business logic) realistically reuses across web/app/mini-program? If the shared layer is small, multi-platform framework cost > gain. |
+| Team stack fit | React/TypeScript (Taro, Remax) vs Vue (uni-app) vs none (native). Hiring/replacing matters more than founder preference. |
+| Component-library maturity per target | Does the candidate's UI-kit family (taroify, NutUI-Taro, tdesign-miniprogram, uni-app uView, etc.) actually look like the design needs, or will every component be wrapped/overridden? |
+| Host-feature lag | When WeChat / Alipay / Douyin ships a new capability, how quickly does the framework expose it? Multi-platform frameworks usually trail native by weeks to months on novel features (Skyline, new pay flows, new permission models). |
+| Build / package-size cost | Multi-platform frameworks add runtime weight; native does not. Tight package-size budgets favor native. |
+| Cold-start performance | Native is usually fastest; Taro's emulated runtime adds startup work that matters on low-end devices. |
+| Debugging / runtime opacity | Multi-platform frameworks add a layer between your code and the host runtime. Bugs that fail at the framework boundary are harder to diagnose than native bugs. |
+| Migration / exit cost | If the team has to leave this framework in 2-3 years, how painful? Native code is more portable than framework-bound code. |
+| Ecosystem and maintenance signal | Is the framework actively maintained? Release cadence, issue-response time, contributor depth, last major release date. A stale framework is a hidden cost. |
+
+## Candidate sketches (decision context, not endorsement)
+
+These are framework facts the team should re-verify against current docs and project needs before deciding. Do not adopt them as conclusions.
+
+- **Taro**: React/TypeScript, broad multi-target (WeChat / Alipay / Douyin / Baidu / QQ / H5 / RN). Strongest fit when (a) a React web project shares substantial business logic with the mini-program, (b) the team is React-first, (c) two or more host platforms must ship, and (d) the design system is consistent across hosts. Weakest fit when target is single-host with tight package-size budget, or when novel host capabilities (new pay flows, Skyline) are on the critical path.
+- **uni-app**: Vue-based, broad multi-target including native app via uni-native. Strong fit for Vue-first teams or when a unified web + mini-program + native app codebase is required. Weak fit for React-first teams.
+- **Native (WeChat / Alipay / Douyin / Baidu)**: simplest runtime, smallest package, fastest host-feature uptake, no framework abstraction tax. Strong fit when target is single-host or the project is small. Weak fit when 2+ hosts must ship and shared code matters.
+- **Remax / kbone**: React syntax compiled to native templates (Remax) or browser-runtime emulation (kbone). Niche; verify project activity before adopting.
+- **mpvue**: Vue-based, smaller scope than uni-app. Verify maintenance state.
+- **Per-platform split (native per host)**: best feature uptake and runtime fit per host, worst shared-code story. Strong fit when each host's product diverges materially or when the team can staff per-host owners.
+
+## Skyline (or any host-new-renderer) opt-in
+
+WeChat Skyline (worklet-driven, GPU-composited renderer for single-thread interaction) and similar host-new-renderer paths are **opt-in for specific surfaces, not a project-wide default**. Skyline is WeChat-only and the multi-platform frameworks (e.g. Taro 4.0.8+ exposes worklet) trail native host releases. Adopt only when (a) high-frequency scroll / complex gesture / immersive animation / low-end-device interaction performance is a release-blocker proven by measurement, (b) the surface can be re-implemented in Skyline-compatible component subset (some legacy components and behaviors are unsupported), and (c) the team accepts the dual-renderer maintenance cost during transition. CRUD pages, financial / data forms, content-list / settings flows default to WebView renderer — migrating them yields no user-visible win.
+
+## HarmonyOS target (Taro 4 / uni-app x) is a distinct runtime, not another mini-program build
+
+The multi-platform frameworks added a HarmonyOS build target. As of framework docs reviewed 2026-05, Taro 4 compiles toward HarmonyOS via a C-API native-rendering path with Vite-based compilation (documented around the React DSL), and uni-app x compiles Vue + UTS toward HarmonyOS native ArkTS / ArkUI. Verify the current build command, supported DSLs (Vue parity on Taro's C-API path is not assumed), and component/API coverage against the framework docs before planning a Harmony target. Two consequences for this skill:
+
+- **Verification matrix**: a HarmonyOS target is a separate row, not folded into "the Taro build passes". `taro build --type weapp` passing is not evidence the harmony target builds or renders — the harmony output runs on a native rendering engine, not the mini-program WebView/Skyline runtime, so supported components, lifecycle, and host-capability shapes differ. Prove it independently like any other shipped target.
+- **Ownership boundary**: the HarmonyOS output is a native OS application (a Harmony app, or a separately-confirmed atomic-service), not a host mini-program. Native-app delivery concerns — Harmony app review, signing, native real-device evidence, OS-level permission model, and any separately-confirmed atomic-service packaging/review path — coordinate with `app-cross-platform-dev`; this skill stays authoritative for the shared cross-target code layer and the mini-program targets only. When one Taro codebase ships both mini-program and harmony targets, name the per-layer final-decision owner the same way the web/mini-program shared-adapter boundary is named in the SKILL.
+
+## Decision evidence the team must collect
+
+Before changing framework, record:
+
+- Current code's actual shared-code ratio (lines / modules genuinely shared between web and mini-program, vs platform-branched).
+- Three real defects from the past quarter that the current framework caused or hid; estimate of what each would cost on the candidate framework.
+- Three real wins from the past quarter that the current framework enabled; estimate of what each would cost on the candidate framework.
+- A 2-week spike on the candidate framework rebuilding one production page, including: cold-start time, package size delta, real-device test pass/fail, design-token fidelity. **Expedited path** for emergencies (host capability deprecation deadline, critical security advisory, framework end-of-life with no patch): skip the 2-week spike at risk-owner signoff, ship behind a server-side flag with a tested rollback, and run the spike post-release to validate the bet. Do not waive the spike for non-emergencies.
+- Migration cost estimate (engineering weeks) with a 1.5× buffer; framework migrations always run long.
+- An "exit cost" clause: if the candidate fails, what's the rollback path and timeline?
+
+A framework switch decided on opinion or vendor demo, without these rows, is a high-risk move.
+
+## What this skill does NOT decide
+
+- Whether the team should use a mini-program at all vs. a web app or native app — that's a product / distribution / GTM question owned by product-rd-workflow.
+- Whether to ship multiple hosts simultaneously or sequence them — that's a release-strategy question owned by product-rd-workflow.
+- UI-kit choice within a given framework — **co-owned**: `product-ui-ux-design` owns the UX, token, accessibility, and brand-fit criteria; this skill owns runtime fit (package size, host-platform compatibility, framework version compatibility, build pipeline integration). A UI-kit decision requires both owners' sign-off, not either alone.
+- Cross-stack alignment scope — owned by `cross-stack-alignment.md`.

package/dist/assets/marketplace/plugins/ccl-skills/skills/miniapp-product-dev/references/online-practice-uptake.md

@@ -0,0 +1,56 @@
+# Online Practice Uptake
+
+Use this reference when incorporating publicly available best practices into mini-program work — Taro official docs, WeChat/Alipay/Douyin/Baidu developer blogs, top-tier mini-programs observed as a user, OSS UI-kit reference implementations, and conference talks / engineering blogs from large-scale teams.
+
+The aim is to **steal good ideas honestly**: absorb the pattern, do not absorb claims you cannot verify. Online practice has the same maturity gradient as in-codebase practice; not every published pattern deserves to land in this skill.
+
+## Source classes and what they ground
+
+| Source class | What it can ground | What it cannot ground |
+|---|---|---|
+| Host-platform official docs (WeChat / Alipay / Douyin / Baidu) | API contracts, config shapes, review policy at publication date, capability availability, version constraints | Whether the pattern is appropriate for your product; whether the doc is current (always re-check date and version) |
+| Framework official docs (Taro, uni-app, Remax) | Framework facts (lifecycle, build, target resolution, syntax), canonical examples | Whether the canonical example is the best architecture for a specific product; whether the example is current |
+| Framework GitHub `examples/` directory + project templates | Default architectural recipes the framework's authors consider idiomatic | Whether the example reflects production-grade concerns (auth epoch, payment finality, observability) |
+| Canonical UI-kit source (taroify, NutUI-Taro, tdesign-miniprogram, uni-app uView) | Component-level mechanics: design-token wiring, accessibility defaults, interaction primitives, gesture/animation patterns | Whole-app architecture; cross-page state ownership; backend contract decisions |
+| Top-tier mini-program portfolios observed as a user (large-scale finance / e-commerce / education / utility apps) | Pattern / idiom library: how a screen is laid out, what states are shown, what copy is used, what interaction model is chosen | Internal architecture; backend contract; A/B test results; business constraints that drove the visible UX; quality of the underlying code |
+| Engineering blogs / conference talks from large-scale teams | Reasoning about tradeoffs; war-story anti-patterns; capacity numbers | Direct applicability without verifying scale / stack / constraint fit |
+| OSS demo projects, tutorial blogs, screencasts | Quick orientation; syntax examples | Production-grade patterns; security; finality; observability |
+| Weak / abandoned online sources (stale demos, outdated framework versions, low-engagement repos) | Rejection signals only (what NOT to copy) | Positive guidance |
+
+## Uptake discipline
+
+Before landing a pattern from online practice as a rule in this skill:
+
+1. **Classify the source** using the table above. Record the class explicitly when proposing the rule.
+2. **Verify the freshness**: what's the publication date? What framework / host version was current then? Has anything material changed (Taro 3 → 4, WeChat capability deprecations, payment policy updates)?
+3. **Separate observation from claim**: a top-tier mini-program *showing* a pattern is evidence the pattern exists in the wild, not evidence the pattern is correct. The team may have made the same mistake at scale. Frame as "we observe X; testing whether it generalizes" — not "industry does X, therefore X is right".
+4. **Hunt for the failure mode**: every published pattern has a context. What constraint produced it? What does it cost? When does it break? If you cannot describe the cost, you don't understand the pattern well enough to extract it as a rule.
+5. **Cross-check at least two independent sources** before landing a rule from observation alone. A single blog / single mini-program is not industry consensus.
+6. **Run it through the skill's own gates**: does the proposed rule pass the dual-track review + adversarial challenge in this skill's extraction workflow? A pattern that survives one popular blog but fails the production-safety challenge does not belong here.
+7. **Provenance, not claim**: when the rule lands, the **source class + evidence label** (`pattern-observation` / `industry-canonical-with-cross-check`) goes into the shared source-evidence-map row. The **specific URLs, dated screenshots, observed app names, and re-extraction logs** live in the maintainer's private archive (see source-evidence-map.md → "Where The Specific Provenance Lives"), not in the shared skill tree. The rule itself in SKILL.md or reference files stays source-neutral.
+
+## Anti-patterns when borrowing from online practice
+
+- **"Big-name app does X, so X is right."** Big-name apps ship bad UX too. Observed pattern is evidence the pattern exists, not that it works.
+- **Copying without context.** A payment flow from a top-tier e-commerce app may rely on backend infrastructure your product does not have. Lifting the UI without the supporting contract creates a half-broken pattern.
+- **Stacking idioms from incompatible sources.** Mixing a layout idiom from one mini-program with copy tone from another and a navigation pattern from a third produces a Frankenstein UX that feels wrong even if each piece is individually fine.
+- **Treating a tutorial as production guidance.** Tutorials optimize for clarity / shortness. Production code optimizes for failure modes. The two diverge.
+- **Quoting a conference talk number as if your team has the same constraints.** A pattern that works at a 100M-DAU scale may not be optimal at 10K-DAU; the inverse is also true.
+- **Stale-doc adoption.** Mini-program platform policy changes faster than community blogs. The blog from 18 months ago that solved your problem may now be the reason your release is rejected.
+
+## What to take from online sources, what to leave
+
+| Take | Leave |
+|---|---|
+| Pattern observation: how a screen handles long content / empty / error / weak network | Specific copy, brand color, brand name |
+| Interaction idiom: pull-to-refresh placement, swipe gestures, sticky headers | Pixel-exact layout |
+| State enumeration: what states a screen models | The team's chosen visual treatment of those states |
+| Anti-patterns the source identifies and avoids | The source's praise of what worked (the team may have moved on) |
+| Framework-canonical syntax and architecture from official examples | Whole-app architecture from any single example app |
+| Capability contract from host-platform official docs (with date + URL recorded) | Cross-reading the docs from memory |
+
+## Integration with this skill
+
+- New rule candidates from online practice flow through the same dual-track review + adversarial challenge as in-codebase observations (see `skill-extraction-workflow/references/dual-track-review-gate.md`).
+- The rule's source provenance is recorded in `source-evidence-map.md` with an explicit evidence label; the rule's wording in SKILL.md / references is source-neutral and capability-named.
+- A rule lifted from a single online source without cross-check is recorded as **hypothesis** in the extraction ledger, not as observed evidence. It stays a hypothesis until a real feature delivery cycle or a second independent source confirms it.