@ccoalm/ccl-skills 0.7.0 → 0.8.0

package/dist/assets/marketplace/plugins/ccl-skills/skills/code-review/scripts/update_review_plan_intent.py

@@ -0,0 +1,513 @@
+#!/usr/bin/env python3
+"""Append or compact bounded intent without lossy truncation.
+
+The caller owns writer serialization and provides a trusted, stable parent
+directory. ``--expected-sha256`` rejects input that was already stale when
+opened; it is not a lock against concurrent writers.
+"""
+
+from __future__ import annotations
+
+import argparse
+import base64
+import hashlib
+import json
+import os
+import re
+import stat
+import sys
+import tempfile
+from pathlib import Path
+from typing import NoReturn
+
+
+MIN_INTENT_CHARS = 8
+MAX_INTENT_CHARS = 4000
+MAX_PLAN_BYTES = 32_000
+PLAN_FIELDS = {"intent", "acceptance", "self_review", "evidence"}
+SHA256_RE = re.compile(r"[0-9a-f]{64}")
+STABLE_CORE_EVIDENCE_ID = "review-plan-intent-stable-core-v1"
+STABLE_CORE_RESULT_RE = re.compile(r"chars=([1-9][0-9]{0,3});sha256=([0-9a-f]{64})")
+HISTORY_EVIDENCE_PREFIX = "review-plan-intent-history-v1"
+HISTORY_BASE64_CHUNK_CHARS = 1800
+MAX_EVIDENCE_ROWS = 50
+
+
+class UpdateError(Exception):
+    def __init__(self, reason: str, detail: str) -> None:
+        super().__init__(detail)
+        self.reason = reason
+        self.detail = detail
+
+
+class DuplicateKeyError(ValueError):
+    pass
+
+
+def reject_duplicate_keys(pairs: list[tuple[str, object]]) -> dict[str, object]:
+    result: dict[str, object] = {}
+    for key, value in pairs:
+        if key in result:
+            raise DuplicateKeyError
+        result[key] = value
+    return result
+
+
+def fail(reason: str, detail: str) -> NoReturn:
+    raise UpdateError(reason, detail)
+
+
+def read_regular(path: Path, *, label: str, max_bytes: int) -> tuple[bytes, int]:
+    if not hasattr(os, "O_NOFOLLOW") or not hasattr(os, "O_NONBLOCK"):
+        fail(
+            f"{label}_unsupported",
+            "this platform cannot safely open files without following links or blocking on special files",
+        )
+    flags = os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK | getattr(os, "O_CLOEXEC", 0)
+    fd = -1
+    try:
+        fd = os.open(path, flags)
+    except OSError as exc:
+        fail(f"{label}_unreadable", str(exc))
+    try:
+        info = os.fstat(fd)
+        if not stat.S_ISREG(info.st_mode):
+            fail(f"{label}_not_regular", "expected a regular, non-symlink file")
+        if info.st_nlink != 1:
+            fail(f"{label}_hardlinked", "refusing a multiply-linked file")
+        if label == "plan" and hasattr(os, "geteuid") and info.st_uid != os.geteuid():
+            fail("plan_not_owned", "the plan must be owned by the current user")
+        if info.st_size > max_bytes:
+            fail(f"{label}_too_large", f"maximum is {max_bytes} bytes")
+        with os.fdopen(fd, "rb") as handle:
+            fd = -1
+            chunks: list[bytes] = []
+            remaining = max_bytes + 1
+            while remaining:
+                chunk = handle.read(min(65_536, remaining))
+                if not chunk:
+                    break
+                chunks.append(chunk)
+                remaining -= len(chunk)
+            data = b"".join(chunks)
+    except OSError as exc:
+        fail(f"{label}_unreadable", str(exc))
+    finally:
+        if fd >= 0:
+            os.close(fd)
+    if len(data) > max_bytes:
+        fail(f"{label}_too_large", f"maximum is {max_bytes} bytes")
+    return data, stat.S_IMODE(info.st_mode)
+
+
+def decode_utf8(data: bytes, *, label: str) -> str:
+    try:
+        return data.decode("utf-8")
+    except UnicodeDecodeError as exc:
+        fail(f"{label}_invalid_utf8", f"invalid UTF-8 at byte {exc.start}")
+
+
+def digest(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def normalized_intent(
+    value: object, *, reason_prefix: str, minimum: int = MIN_INTENT_CHARS
+) -> str:
+    if not isinstance(value, str):
+        fail(f"{reason_prefix}_not_string", "intent must be a string")
+    stripped = value.strip()
+    if value != stripped:
+        fail(f"{reason_prefix}_not_normalized", "intent must not have outer whitespace")
+    if len(value) < minimum:
+        fail(f"{reason_prefix}_too_short", f"minimum is {minimum} characters")
+    return value
+
+
+def remove_file_line_ending(value: str) -> str:
+    """Remove only the one line ending used as a text-file delimiter."""
+    if value.endswith("\r\n"):
+        return value[:-2]
+    if value.endswith(("\n", "\r")):
+        return value[:-1]
+    return value
+
+
+def render_plan(plan: dict[str, object]) -> bytes:
+    try:
+        encoded = (json.dumps(plan, ensure_ascii=False, indent=2) + "\n").encode(
+            "utf-8"
+        )
+    except UnicodeEncodeError as exc:
+        fail("updated_plan_invalid_unicode", f"cannot encode UTF-8 at character {exc.start}")
+    if len(encoded) > MAX_PLAN_BYTES:
+        fail("updated_plan_too_large", f"maximum is {MAX_PLAN_BYTES} bytes")
+    return encoded
+
+
+def stable_core_identity(plan: dict[str, object]) -> tuple[int, str]:
+    evidence = plan.get("evidence")
+    if not isinstance(evidence, list):
+        fail("intent_core_identity_missing", "plan evidence has no stable-core identity")
+    records = [
+        item
+        for item in evidence
+        if isinstance(item, dict) and item.get("id") == STABLE_CORE_EVIDENCE_ID
+    ]
+    if not records:
+        fail("intent_core_identity_missing", "plan evidence has no stable-core identity")
+    if len(records) != 1:
+        fail("intent_core_identity_invalid", "plan must contain exactly one stable-core identity")
+    record = records[0]
+    if set(record) != {"id", "result"} or not isinstance(record.get("result"), str):
+        fail("intent_core_identity_invalid", "stable-core identity has an invalid schema")
+    match = STABLE_CORE_RESULT_RE.fullmatch(record["result"])
+    if match is None:
+        fail("intent_core_identity_invalid", "stable-core identity has an invalid encoding")
+    core_chars = int(match.group(1))
+    if not MIN_INTENT_CHARS <= core_chars <= MAX_INTENT_CHARS:
+        fail(
+            "intent_core_identity_invalid",
+            f"stable-core character length must be between {MIN_INTENT_CHARS} and {MAX_INTENT_CHARS}",
+        )
+    return core_chars, match.group(2)
+
+
+def text_digest(value: str, *, reason: str, label: str) -> str:
+    try:
+        return digest(value.encode("utf-8"))
+    except UnicodeEncodeError as exc:
+        fail(reason, f"{label} cannot encode as UTF-8 at character {exc.start}")
+
+
+def archive_discarded_intent(
+    plan: dict[str, object], *, old_intent: str, core: str
+) -> None:
+    """Retain the exact old intent bytes before compacting its visible field."""
+    suffix = old_intent[len(core) :]
+    if not suffix:
+        return
+    evidence = plan.get("evidence")
+    if not isinstance(evidence, list):
+        fail("intent_history_invalid", "plan evidence must be an array")
+    used_ids = {
+        item.get("id")
+        for item in evidence
+        if isinstance(item, dict) and isinstance(item.get("id"), str)
+    }
+    group = None
+    for group_number in range(1, MAX_EVIDENCE_ROWS + 1):
+        candidate_group = f"{group_number:04d}"
+        candidate_prefix = f"{HISTORY_EVIDENCE_PREFIX}-{candidate_group}"
+        if not any(
+            evidence_id == f"{candidate_prefix}-manifest"
+            or evidence_id.startswith(f"{candidate_prefix}-part-")
+            for evidence_id in used_ids
+        ):
+            group = candidate_group
+            break
+    if group is None:
+        fail("intent_history_full", "no unique intent-history evidence group remains")
+    try:
+        old_bytes = old_intent.encode("utf-8")
+        suffix_bytes = suffix.encode("utf-8")
+    except UnicodeEncodeError as exc:
+        fail(
+            "intent_history_invalid_unicode",
+            f"old intent cannot encode as UTF-8 at character {exc.start}",
+        )
+    encoded_suffix = base64.b64encode(suffix_bytes).decode("ascii")
+    chunks = [
+        encoded_suffix[index : index + HISTORY_BASE64_CHUNK_CHARS]
+        for index in range(0, len(encoded_suffix), HISTORY_BASE64_CHUNK_CHARS)
+    ]
+    prefix = f"{HISTORY_EVIDENCE_PREFIX}-{group}"
+    rows: list[dict[str, str]] = [
+        {
+            "id": f"{prefix}-manifest",
+            "result": (
+                f"format={HISTORY_EVIDENCE_PREFIX};"
+                f"old_chars={len(old_intent)};"
+                f"old_sha256={hashlib.sha256(old_bytes).hexdigest()};"
+                f"core_chars={len(core)};"
+                f"suffix_bytes={len(suffix_bytes)};"
+                f"suffix_sha256={hashlib.sha256(suffix_bytes).hexdigest()};"
+                f"encoding=base64-utf8;parts={len(chunks)}"
+            ),
+        }
+    ]
+    rows.extend(
+        {
+            "id": f"{prefix}-part-{part_number:04d}",
+            "result": (
+                f"format={HISTORY_EVIDENCE_PREFIX};group={group};"
+                f"part={part_number}/{len(chunks)};data={chunk}"
+            ),
+        }
+        for part_number, chunk in enumerate(chunks, start=1)
+    )
+    if len(evidence) + len(rows) > MAX_EVIDENCE_ROWS:
+        fail(
+            "intent_history_evidence_overflow",
+            f"zero-loss compaction needs {len(rows)} history rows but the plan "
+            f"would exceed {MAX_EVIDENCE_ROWS} evidence rows",
+        )
+    plan["evidence"] = [*evidence, *rows]
+
+
+def atomic_replace(path: Path, data: bytes, mode: int) -> None:
+    fd = -1
+    temp_path: Path | None = None
+    try:
+        try:
+            fd, raw_temp = tempfile.mkstemp(prefix=f".{path.name}.", dir=path.parent)
+            temp_path = Path(raw_temp)
+            with os.fdopen(fd, "wb") as handle:
+                fd = -1
+                handle.write(data)
+                handle.flush()
+                os.fchmod(handle.fileno(), mode)
+                os.fsync(handle.fileno())
+        except OSError as exc:
+            fail("plan_write_failed", str(exc))
+        try:
+            os.replace(temp_path, path)
+            temp_path = None
+        except OSError as exc:
+            fail("plan_write_failed", str(exc))
+        try:
+            directory_flags = (
+                os.O_RDONLY
+                | getattr(os, "O_DIRECTORY", 0)
+                | getattr(os, "O_CLOEXEC", 0)
+            )
+            directory_fd = os.open(path.parent, directory_flags)
+            try:
+                os.fsync(directory_fd)
+            finally:
+                os.close(directory_fd)
+        except OSError as exc:
+            fail(
+                "plan_committed_durability_unknown",
+                f"the target was replaced with sha256={digest(data)} but directory sync failed ({exc}); re-read the plan and do not retry blindly",
+            )
+    finally:
+        cleanup_errors: list[str] = []
+        if fd >= 0:
+            try:
+                os.close(fd)
+            except OSError as exc:
+                cleanup_errors.append(f"close failed: {exc}")
+        if temp_path is not None:
+            try:
+                temp_path.unlink()
+            except FileNotFoundError:
+                pass
+            except OSError as exc:
+                cleanup_errors.append(f"temporary-file removal failed: {exc}")
+        if cleanup_errors:
+            active_error = sys.exc_info()[1]
+            detail = "; ".join(cleanup_errors)
+            if isinstance(active_error, UpdateError):
+                detail = (
+                    f"{detail}; original failure was {active_error.reason}: "
+                    f"{active_error.detail}"
+                )
+            raise UpdateError("plan_cleanup_failed", detail)
+
+
+def parse_args(argv: list[str]) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description=(
+            "Update a review plan intent without lossy truncation. Overflow is "
+            "an error and leaves the plan unchanged."
+        )
+    )
+    parser.add_argument("--plan", required=True, type=Path)
+    parser.add_argument("--append-intent-file", type=Path)
+    parser.add_argument("--compact-core-intent-file", type=Path)
+    parser.add_argument("--latest-intent-file", type=Path)
+    parser.add_argument(
+        "--expected-sha256",
+        help="optional stale-input guard for the current plan bytes",
+    )
+    return parser.parse_args(argv)
+
+
+def run(argv: list[str]) -> int:
+    args = parse_args(argv)
+    append_mode = args.append_intent_file is not None
+    compact_mode = (
+        args.compact_core_intent_file is not None or args.latest_intent_file is not None
+    )
+    if append_mode == compact_mode or (
+        compact_mode
+        and (
+            args.compact_core_intent_file is None
+            or args.latest_intent_file is None
+        )
+    ):
+        fail(
+            "intent_update_mode_invalid",
+            "choose append, or supply both compact core and latest intent files",
+        )
+    plan_bytes, plan_mode = read_regular(
+        args.plan, label="plan", max_bytes=MAX_PLAN_BYTES
+    )
+    if plan_mode & 0o7000:
+        fail("plan_mode_unsupported", "setuid, setgid, and sticky plan modes are unsupported")
+    plan_mode &= 0o777
+    current_digest = digest(plan_bytes)
+    if args.expected_sha256 is not None:
+        expected = args.expected_sha256.lower()
+        if SHA256_RE.fullmatch(expected) is None:
+            fail("expected_sha256_invalid", "expected exactly 64 hexadecimal characters")
+        if expected != current_digest:
+            fail("plan_digest_mismatch", "the plan changed after the caller read it")
+
+    try:
+        plan = json.loads(
+            decode_utf8(plan_bytes, label="plan"),
+            object_pairs_hook=reject_duplicate_keys,
+        )
+    except DuplicateKeyError:
+        fail("plan_duplicate_key", "duplicate JSON object keys are unsupported")
+    except json.JSONDecodeError as exc:
+        fail("plan_invalid_json", f"JSON parse failed at line {exc.lineno} column {exc.colno}")
+    if not isinstance(plan, dict) or set(plan) != PLAN_FIELDS:
+        fail("plan_schema_invalid", "top-level fields must be intent, acceptance, self_review, evidence")
+    old_intent = normalized_intent(plan["intent"], reason_prefix="plan_intent")
+
+    if append_mode:
+        if len(old_intent) > MAX_INTENT_CHARS:
+            fail("plan_intent_overflow", f"maximum is {MAX_INTENT_CHARS} characters")
+        incoming_bytes, _ = read_regular(
+            args.append_intent_file, label="intent_input", max_bytes=MAX_PLAN_BYTES
+        )
+        incoming = remove_file_line_ending(
+            decode_utf8(incoming_bytes, label="intent_input")
+        )
+        if not incoming:
+            fail("intent_append_empty", "append input must not be empty")
+        candidate = old_intent + incoming
+        reason_prefix = "intent_append"
+    else:
+        core_bytes, _ = read_regular(
+            args.compact_core_intent_file,
+            label="intent_core",
+            max_bytes=MAX_PLAN_BYTES,
+        )
+        latest_bytes, _ = read_regular(
+            args.latest_intent_file,
+            label="intent_latest",
+            max_bytes=MAX_PLAN_BYTES,
+        )
+        core = normalized_intent(
+            remove_file_line_ending(decode_utf8(core_bytes, label="intent_core")),
+            reason_prefix="intent_core",
+        )
+        latest = normalized_intent(
+            remove_file_line_ending(decode_utf8(latest_bytes, label="intent_latest")),
+            reason_prefix="intent_latest",
+            minimum=1,
+        )
+        if not old_intent.startswith(core):
+            fail(
+                "intent_core_not_preserved",
+                "compact core must be an exact prefix of the current intent",
+            )
+        if latest in old_intent:
+            fail(
+                "intent_latest_not_new",
+                "latest transition is already present in the current intent",
+            )
+        core_chars, core_sha256 = stable_core_identity(plan)
+        if len(old_intent) < core_chars:
+            fail(
+                "plan_core_identity_mismatch",
+                "current intent is shorter than its persisted stable-core identity",
+            )
+        persisted_core = old_intent[:core_chars]
+        if text_digest(
+            persisted_core,
+            reason="plan_core_identity_mismatch",
+            label="persisted stable core",
+        ) != core_sha256:
+            fail(
+                "plan_core_identity_mismatch",
+                "persisted stable-core identity does not match the current intent",
+            )
+        if len(core) != core_chars or text_digest(
+            core,
+            reason="intent_core_identity_mismatch",
+            label="compact core",
+        ) != core_sha256:
+            fail(
+                "intent_core_identity_mismatch",
+                "compact core does not match the plan's persisted stable-core identity",
+            )
+        archive_discarded_intent(plan, old_intent=old_intent, core=core)
+        candidate = f"{core}\n\n{latest}"
+        reason_prefix = "intent_compact"
+
+    candidate = normalized_intent(candidate, reason_prefix=reason_prefix)
+    if len(candidate) > MAX_INTENT_CHARS:
+        fail(
+            f"{reason_prefix}_overflow",
+            f"candidate has {len(candidate)} characters; maximum is {MAX_INTENT_CHARS}; rebuild intent as core + latest and keep history in evidence/prior results",
+        )
+
+    plan["intent"] = candidate
+    updated = render_plan(plan)
+    atomic_replace(args.plan, updated, plan_mode)
+    # flush inside the guarded path: without it the receipt sits in the stdout
+    # buffer and a closed pipe only surfaces BrokenPipeError at interpreter
+    # shutdown, after main() returned rc 0 and past its handler.
+    print(
+        "review_plan_intent_updated "
+        f"mode={'append' if append_mode else 'compact'} "
+        f"chars={len(candidate)} old_sha256={current_digest} new_sha256={digest(updated)}",
+        flush=True,
+    )
+    return 0
+
+
+def main() -> int:
+    try:
+        return run(sys.argv[1:])
+    except UpdateError as exc:
+        print(
+            f"review_plan_intent_error: reason={exc.reason} detail={exc.detail}",
+            file=sys.stderr,
+        )
+        return 2
+    except (BrokenPipeError, OSError):
+        # The success receipt is printed (flushing) only after atomic_replace
+        # committed, and every other file operation converts its OSError to
+        # UpdateError, so an OS-level error here means the receipt was lost on
+        # a closed/broken stdout — not that the update failed. rc 0 with no
+        # receipt would read as "no update happened"; report the committed-but-
+        # unreported state the same way a failed durability sync does.
+        try:
+            print(
+                "review_plan_intent_error: reason=plan_committed_receipt_lost "
+                "detail=stdout closed before the success receipt was delivered; "
+                "re-read the plan for the committed state and do not retry blindly",
+                file=sys.stderr,
+            )
+            sys.stderr.flush()
+        except (BrokenPipeError, OSError):
+            pass
+        # Point stdout at devnull so the interpreter's shutdown flush of the
+        # broken pipe cannot override this exit status with 120.
+        try:
+            devnull = os.open(os.devnull, os.O_WRONLY)
+            os.dup2(devnull, sys.stdout.fileno())
+            os.close(devnull)
+        except (OSError, ValueError):
+            pass
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/dist/assets/marketplace/plugins/ccl-skills/skills/go-microservice-dev/SKILL.md

@@ -18,7 +18,10 @@ Use this for implementation of new backend products and services. It should adap
 - Use codebase-specific skills only when the task is explicitly about an existing legacy/workspace repository.
 - Development references should turn already-chosen architecture into code, tests, and generated artifacts. If a change requires choosing ownership, security model, source of truth, or release governance, first apply `go-microservice-architecture`.
 - For money, billing, quota, permission, tenant/user data isolation, high-impact AI, repeated writes, async finality, or incident-explanation risk, apply `product-rd-workflow` high-risk resilience gates and route test-layer design through `testing-strategy`.
-- When a change edits strings, templates, or config values that are returned to, persisted for, emitted to, served to, synchronized with, or configured for client consumption (error copy, labels, notification text, localization payloads, content/CMS/seed rows, message or notification templates, flag-delivered content), classify the consumers with a recorded bounded check (client repo / contract / locale search) before closing on API/log evidence; if any client surface renders the value user-facing, or consumers are unknown, load `product-ui-ux-design` and record its implementation-owner checkpoint — including the consuming client stack owner(s) and `testing-strategy` per that checkpoint's field list — with client-side rendered-evidence routing. Backend-only closure without that recorded consumer check is invalid.
+- When a change can alter what a client renders or which state, action, or decision path it offers—including strings/templates/config/flags and API/event/schema fields, enums, status/progress, permission/capability signals, defaults, or result shapes—load `../product-ui-ux-design/references/delivery-contract.md`, create the applicable full or lightweight record in that contract, and follow its canonical consumer-universe classification, design/test/client handoffs, and terminal-status rules.
+- This Go owner returns only its `producer_record` delta: immutable binding, build/schema/config artifact identity, exact command/environment, and API/event/log/output observation.
+
+- For a standalone Go CLI, this skill owns Go parser/library implementation mechanics. Any change to a user-facing command tree, subcommand, flag/default/action path, help/output/exit behavior, confirmation, progress, or recovery path also loads `terminal-cli-dev`, which owns the terminal contract and its UI/UX/testing handoff. Only internal parser refactors proven to preserve all user-visible semantics may skip that owner.
 
 ## Generalization Discipline
 

package/dist/assets/marketplace/plugins/ccl-skills/skills/llm-inference-integration/SKILL.md

@@ -16,7 +16,8 @@ Use this for product backend work that calls, hosts, evaluates, or operates LLM
 - Use `product-rd-workflow` first when the request spans product goal, PRD, architecture, implementation plan, release, and learning loop.
 - Use `product-rd-workflow` first for AI/algorithm product launch SOPs, business acceptance baselines, build-vs-buy ROI, new-vs-iteration launch gates, or multi-algorithm product quality gates. This skill owns inference implementation/evaluation mechanics after the product gate is defined.
 - For high-impact answers or decisions where wrong output can mislead users, affect money/rights/access, or create support/compliance risk, use `product-rd-workflow` high-risk resilience gates before fallback, downgrade, or launch decisions.
-- When a change edits strings, templates, or config values that are returned to, persisted for, emitted to, served to, synchronized with, or configured for client consumption (error copy, labels, notification text, localization payloads, content/CMS/seed rows, message or notification templates, flag-delivered content), classify the consumers with a recorded bounded check (client repo / contract / locale search) before closing on API/log evidence; if any client surface renders the value user-facing, or consumers are unknown, load `product-ui-ux-design` and record its implementation-owner checkpoint — including the consuming client stack owner(s) and `testing-strategy` per that checkpoint's field list — with client-side rendered-evidence routing. Inference-side closure without that recorded consumer check is invalid.
+- When a change can alter what a client renders or which state, action, or decision path it offers—including strings/templates/config/flags and API/event/schema fields, enums, status/progress, permission/capability signals, defaults, or result shapes—you must load `../product-ui-ux-design/references/delivery-contract.md`, create the applicable full or lightweight record in that contract, and follow its canonical consumer-universe classification, design/test/client handoffs, and terminal-status rules.
+- This inference owner returns only its `producer_record` delta: immutable binding, prompt/model/config/artifact identity, exact command/environment, and API/event/log/output observation.
 
 ## Generalization Discipline
 

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

@@ -23,9 +23,9 @@ For evaluating whether Taro is the right choice for a given project (vs native,
 
 ## 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.
+The current baseline is **vendor-spec + framework-canonical**, not `mature confirmed`: host-platform guidelines, Taro documentation/examples, and canonical Taro UI libraries (taroify, NutUI-Taro, tdesign React mapping). No production-quality miniapp portfolio has been observed end-to-end. Apply positive rules as defaults and anti-patterns as guardrails, and mark them `confirmed` only after a correction-free real feature delivery.
 
-**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.
+**Existing team codebases** do not automatically supply positive rules: production use proves distribution, not quality. Until audited end-to-end against this skill or piloted through one real feature with a `skill-extraction-workflow` retrospective, label them `quality-unverified` per `references/source-evidence-map.md`. Use this skill from the start and feed lessons back through extraction, not silently copy patterns.
 
 ## Runtime Compatibility
 
@@ -101,7 +101,7 @@ Cross-checking rule: when editing code shared with a React web project, also che
 
 ## 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.
+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, API-visible, host-capability, platform-review/release, bug-fix, branch/MR, unclear-risk, or high-risk work needs explicit task split, host/target verification matrix, acceptance checks, verification commands, rollback or stop conditions, and named handoffs to testing, web/app, backend, release, or diagnosis skills before edits. Runtime-visible work consumes the canonical Design brief and Test Phase 0 before implementation.
 
 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.
@@ -116,8 +116,8 @@ Before editing Taro/native mini-program code, page config, host capability adapt
    - 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.
+   - For every visible UI change, load `../product-ui-ux-design/references/delivery-contract.md` and consume either its full Design brief + Phase 0 or its valid low-risk copy-only record + lightweight Phase 0 before coding. The lightweight path checks semantics, accessible name, localization, rendered extent, and target-host render without inventing unrelated matrices; risk-bearing copy uses the full path. For full slices, map structure, state/adaptation matrices, behavior and criteria to pages/host adapters; record route/back/share entry, hosts, capabilities, recovery geometry, and preserved behavior. A mini-program `web-view` has a host member here and a separate web-content owner member; browser/H5-only preview satisfies neither the shipped-host bridge nor the complete owner set.
+   - Before the first implementation edit, add the canonical `client_entry` defined there: local rule identifier or short quote and implementation decision, target surface/runtime, planned run/capture command, and behavior that must remain unchanged.
 
 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.
@@ -155,15 +155,16 @@ Before editing Taro/native mini-program code, page config, host capability adapt
      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 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.
+   - Return the complete canonical client-record member defined in `../product-ui-ux-design/references/delivery-contract.md` for testing Phase 1 and the design verdict. The member includes its applied rule/decision, affected files/components, preserved behavior, exact command, immutable candidate binding, producer member/version actually exercised, artifacts, tested host/tool/device targets, states/dimensions/capabilities, criterion-mapped observations, coverage boundary, and gaps. A host render proves only the captured host/member states; it cannot close an unbound producer member. `testing-strategy` records aggregate sufficiency before the design owner records the candidate-bound verdict.
+   - 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 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
@@ -184,7 +185,7 @@ Before editing Taro/native mini-program code, page config, host capability adapt
 - 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 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.