opencode-skills-collection 4.1.2 → 4.1.4

package/bundled-skills/idea-to-blueprint/scripts/lint_blueprint.py

@@ -0,0 +1,460 @@
+#!/usr/bin/env python3
+"""Lint a generated blueprint (.md) for the structural guarantees the build sessions rely on.
+
+Usage:
+    python3 lint_blueprint.py path/to/blueprint.md [--strict]
+
+Exit code 0 = no errors (warnings may remain), 1 = errors found (or warnings with --strict).
+
+What it checks (E = error, W = warning):
+  E  required top-level sections present (by English anchor in a `## ` heading)
+  E  no placeholder text (TODO, TBD, TBA, FIXME, XXX, lorem, ???, [insert, to be defined/decided)
+  E  at least one `## Epic nn — Title` and Epic 00 present
+  E  each epic has **Definition of Done**;   W  each epic has **Session handoff checklist**
+  E  story headings `### Enn-Snn — Title` are unique and live inside the matching epic
+  E  each story has **Acceptance Criteria**, **Edge cases**, **Tests**, at least one `AC-n`, and names a persona `P<n>`
+  W  each story has **Story**, **Context**, **Scope**, **Tasks**, **Story DoD**
+  E  no "As a user" stories
+  E  every `[UNKNOWN → OQ-nn]` has a matching OQ-nn row in the Open Questions section; bare `[UNKNOWN]` without an OQ is an error
+  E  every table body row in the Tech Stack section carries [VERIFIED / [ASSUMED / [STATED (or [UNVERIFIED], which also raises W)
+  E  every S-nn cited in a [VERIFIED …] tag exists in the Sources section;   W  fewer than 5 URLs in Sources
+  E  every defined persona P<n> is used by at least one story
+  W  copy IDs (CP-…) referenced in stories are defined in the Copy section
+  W  dangling story references (Enn-Snn mentioned but not defined)
+  W  `## ` headings with non-ASCII text carry an ASCII anchor in parentheses
+  W  vague adjectives inside AC lines (properly, appropriately, fast, quickly, easily, seamless, user-friendly, intuitive)
+  W  Session Protocol section mentions an Amendments log;   W  an appendix with session prompts exists
+  E  Architecture section defines drivers AD-n and mentions fitness functions;   W  <3 drivers, drivers
+     with no number in them, no explicit non-drivers
+  E  every AD-n referenced outside the Architecture section is defined inside it
+  W  Tech Stack table has a runner-up column (a choice with no stated cost was not a decision)
+  E  Quality section names a `check` command and embeds >=10 review-checklist items of the form `[ ] …`
+  W  Quality section names critical e2e paths, says something about mutation testing, has M-nn metric
+     rows, and lists anti-metrics
+  E  no metric row defines an output-per-person metric (lines of code, commits/PRs/diffs per engineer,
+     story points as productivity);   W  coverage appearing as a metric without the word "floor"
+
+Add `<!-- lint-ignore -->` at the end of a line to suppress placeholder/adjective findings on that line
+(e.g., the rule sentence "No TODO or TBD anywhere" in the How-to-use section).
+"""
+from __future__ import annotations
+
+import re
+import sys
+from dataclasses import dataclass, field
+
+REQUIRED_SECTIONS_ERROR = [
+    "How to use", "Executive summary", "Scope", "Research", "Assumptions", "Personas",
+    "Goals", "Architecture", "Tech Stack", "Quality", "Edge Cases", "Delivery Plan",
+    "Epics", "Session Protocol", "Risks", "Open Questions", "Glossary", "Sources",
+]
+REQUIRED_SECTIONS_WARN = ["Flows", "Screens", "Design", "UX Writing", "Copy"]
+
+PLACEHOLDER_RE = re.compile(
+    r"\bTODO\b|\bTBD\b|\bTBA\b|\bFIXME\b|\bXXX\b|lorem ipsum|\?\?\?|\[insert|to be defined|to be decided",
+    re.IGNORECASE,
+)
+EPIC_HEADING_RE = re.compile(r"^## Epic (\d{2})\s*[—–-]\s*(.+?)\s*$")
+STORY_HEADING_RE = re.compile(r"^### (E(\d{2})-S(\d{2}))\s*[—–-]\s*(.+?)\s*$")
+STORY_REF_RE = re.compile(r"\bE\d{2}-S\d{2}\b")
+AC_LINE_RE = re.compile(r"^\s*[-*]\s*AC-\d+", re.IGNORECASE)
+PERSONA_REF_RE = re.compile(r"(?<![A-Za-z])P(\d+)\b")
+UNKNOWN_RE = re.compile(r"\[UNKNOWN([^\]]*)\]")
+OQ_IN_UNKNOWN_RE = re.compile(r"OQ-(\d+)")
+VERIFIED_SOURCE_RE = re.compile(r"\[VERIFIED[^\]]*?\bS-(\d+)")
+SOURCE_ID_RE = re.compile(r"\bS-(\d+)\b")
+URL_RE = re.compile(r"https?://\S+")
+CP_ID_RE = re.compile(r"\bCP-[A-Za-z0-9]+-\d+\b")
+EVIDENCE_TAG_RE = re.compile(r"\[(VERIFIED|ASSUMED|STATED|UNVERIFIED)\b")
+UNVERIFIED_RE = re.compile(r"\[UNVERIFIED\]")
+VAGUE_RE = re.compile(
+    r"\b(properly|appropriately|fast|quickly|easily|seamless(?:ly)?|user-friendly|intuitive(?:ly)?)\b",
+    re.IGNORECASE,
+)
+AS_A_USER_RE = re.compile(r"\bAs an? user\b", re.IGNORECASE)
+AD_ID_RE = re.compile(r"\bAD-(\d+)\b")
+DIGIT_RE = re.compile(r"\d")
+FITNESS_RE = re.compile(r"fitness function", re.IGNORECASE)
+CHECK_CMD_RE = re.compile(r"`[^`\n]*\bcheck\b[^`\n]*`")
+CHECKLIST_ITEM_RE = re.compile(r"^\s*(?:[-*]\s*)?\[ \]\s+\S")
+METRIC_ROW_RE = re.compile(r"\bM-\d+(?:\.\d+)?\b")
+BANNED_METRIC_RE = re.compile(
+    r"lines of code|\bLOC\b|commits? per (?:engineer|developer|dev|person)"
+    r"|(?:pull requests?|PRs?|diffs?) per (?:engineer|developer|dev|person)"
+    r"|story points? (?:per|as a measure|completed per)|velocity per",
+    re.IGNORECASE,
+)
+COVERAGE_TARGET_RE = re.compile(r"coverage", re.IGNORECASE)
+LINT_IGNORE = "<!-- lint-ignore -->"
+
+
+@dataclass
+class Findings:
+    errors: list[str] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+
+    def err(self, line: int | None, msg: str) -> None:
+        self.errors.append(f"L{line}: {msg}" if line else msg)
+
+    def warn(self, line: int | None, msg: str) -> None:
+        self.warnings.append(f"L{line}: {msg}" if line else msg)
+
+
+@dataclass
+class Section:
+    title: str
+    start: int  # 0-based index of heading line
+    end: int    # exclusive
+
+
+def level2_sections(lines: list[str]) -> list[Section]:
+    idx = [i for i, l in enumerate(lines) if l.startswith("## ")]
+    sections = []
+    for n, i in enumerate(idx):
+        end = idx[n + 1] if n + 1 < len(idx) else len(lines)
+        sections.append(Section(lines[i][3:].strip(), i, end))
+    return sections
+
+
+def find_section(sections: list[Section], anchor: str) -> Section | None:
+    a = anchor.lower()
+    for s in sections:
+        if EPIC_HEADING_RE.match("## " + s.title):
+            continue
+        if a in s.title.lower():
+            return s
+    return None
+
+
+def block_text(lines: list[str], start: int, end: int) -> str:
+    return "\n".join(lines[start:end])
+
+
+def table_body_rows(lines: list[str], start: int, end: int) -> list[tuple[int, str]]:
+    """Return (line_no, row) for table rows that are neither header nor separator."""
+    rows = []
+    in_table = False
+    header_seen = False
+    for i in range(start, end):
+        l = lines[i].strip()
+        if l.startswith("|"):
+            if not in_table:
+                in_table, header_seen = True, True  # first row of a table is its header
+                continue
+            if re.match(r"^\|[\s:\-|]+\|$", l):
+                continue  # separator
+            rows.append((i + 1, l))
+        else:
+            in_table, header_seen = False, False
+    return rows
+
+
+def main(argv: list[str]) -> int:
+    if len(argv) < 2 or argv[1] in {"-h", "--help"}:
+        print(__doc__)
+        return 0
+    path = argv[1]
+    strict = "--strict" in argv
+    with open(path, encoding="utf-8") as f:
+        lines = f.read().splitlines()
+    f_ = Findings()
+    sections = level2_sections(lines)
+
+    # 1. Required sections
+    for anchor in REQUIRED_SECTIONS_ERROR:
+        if not find_section(sections, anchor):
+            f_.err(None, f"Missing required section with anchor '{anchor}' in a '## ' heading")
+    for anchor in REQUIRED_SECTIONS_WARN:
+        if not find_section(sections, anchor):
+            f_.warn(None, f"No section with anchor '{anchor}' — fine only if it truly does not apply (say so in the doc)")
+
+    # 2. Placeholders + vague adjectives + "As a user"
+    for i, l in enumerate(lines, 1):
+        if LINT_IGNORE in l:
+            continue
+        m = PLACEHOLDER_RE.search(l)
+        if m:
+            f_.err(i, f"Placeholder text '{m.group(0)}' — decide it or route to an [UNKNOWN → OQ-nn]")
+        if AC_LINE_RE.match(l):
+            v = VAGUE_RE.search(l)
+            if v:
+                f_.warn(i, f"Vague word '{v.group(0)}' in an acceptance criterion — replace with a number or observable result")
+        if AS_A_USER_RE.search(l):
+            f_.err(i, "'As a user' — stories must name a persona ID and name (e.g. 'As **P2 (Owner)**')")
+
+    # 3. Epics and stories
+    epics: list[tuple[int, str, Section]] = []  # (epic_no, title, section)
+    for s in sections:
+        m = EPIC_HEADING_RE.match("## " + s.title)
+        if m:
+            epics.append((int(m.group(1)), m.group(2), s))
+    if not epics:
+        f_.err(None, "No epics found — expected headings like '## Epic 00 — Foundation'")
+    elif not any(n == 0 for n, _, _ in epics):
+        f_.err(None, "Epic 00 (Foundation) is missing")
+
+    story_ids: dict[str, int] = {}
+    story_blocks: list[tuple[str, int, int, int]] = []  # (id, epic_no, start, end)
+    for epic_no, epic_title, sec in epics:
+        text = block_text(lines, sec.start, sec.end)
+        if "**Definition of Done**" not in text:
+            f_.err(sec.start + 1, f"Epic {epic_no:02d} has no **Definition of Done**")
+        if "**Session handoff checklist**" not in text:
+            f_.warn(sec.start + 1, f"Epic {epic_no:02d} has no **Session handoff checklist**")
+        # stories inside this epic
+        heads = [i for i in range(sec.start + 1, sec.end) if lines[i].startswith("### ")]
+        if not heads:
+            f_.err(sec.start + 1, f"Epic {epic_no:02d} has no stories ('### Enn-Snn — Title')")
+        for n, i in enumerate(heads):
+            end = heads[n + 1] if n + 1 < len(heads) else sec.end
+            m = STORY_HEADING_RE.match(lines[i])
+            if not m:
+                f_.warn(i + 1, f"Level-3 heading inside Epic {epic_no:02d} is not a story heading: '{lines[i][4:60]}'")
+                continue
+            sid, e_no = m.group(1), int(m.group(2))
+            if sid in story_ids:
+                f_.err(i + 1, f"Duplicate story ID {sid} (first at L{story_ids[sid]})")
+            story_ids[sid] = i + 1
+            if e_no != epic_no:
+                f_.err(i + 1, f"Story {sid} is inside Epic {epic_no:02d} but its ID says E{e_no:02d}")
+            story_blocks.append((sid, epic_no, i, end))
+
+    all_story_text = ""
+    for sid, _, start, end in story_blocks:
+        text = block_text(lines, start, end)
+        all_story_text += "\n" + text
+        for label in ("**Acceptance Criteria**", "**Edge cases**", "**Tests**"):
+            if label not in text:
+                f_.err(start + 1, f"{sid} is missing {label}")
+        for label in ("**Story**", "**Context**", "**Scope**", "**Tasks**", "**Story DoD**"):
+            if label not in text:
+                f_.warn(start + 1, f"{sid} is missing {label}")
+        if not any(AC_LINE_RE.match(l) for l in lines[start:end]):
+            f_.err(start + 1, f"{sid} has no 'AC-n' lines")
+        if not PERSONA_REF_RE.search(text):
+            f_.err(start + 1, f"{sid} does not reference a persona ID (P1, P2, … or P0 for the builder)")
+
+    # dangling story references
+    defined = set(story_ids)
+    for i, l in enumerate(lines, 1):
+        for ref in STORY_REF_RE.findall(l):
+            if ref not in defined:
+                f_.warn(i, f"Reference to undefined story {ref}")
+
+    # 4. UNKNOWN → OQ
+    oq_sec = find_section(sections, "Open Questions")
+    oq_text = block_text(lines, oq_sec.start, oq_sec.end) if oq_sec else ""
+    for i, l in enumerate(lines, 1):
+        for m in UNKNOWN_RE.finditer(l):
+            oqs = OQ_IN_UNKNOWN_RE.findall(m.group(1))
+            if not oqs:
+                f_.err(i, "[UNKNOWN] without an OQ reference — use '[UNKNOWN → OQ-nn]'")
+            for q in oqs:
+                if oq_sec and not re.search(rf"\bOQ-{q}\b", oq_text):
+                    f_.err(i, f"OQ-{q} referenced but not present in the Open Questions section")
+
+    # 5. Tech stack evidence
+    ts = find_section(sections, "Tech Stack")
+    if ts:
+        rows = table_body_rows(lines, ts.start, ts.end)
+        if not rows:
+            f_.err(ts.start + 1, "Tech Stack section has no table rows")
+        for ln, row in rows:
+            if not EVIDENCE_TAG_RE.search(row):
+                f_.err(ln, "Tech Stack table row without an evidence tag ([VERIFIED …] / [ASSUMED …] / [STATED])")
+
+    # 6. Sources
+    src = find_section(sections, "Sources")
+    if src:
+        src_text = block_text(lines, src.start, src.end)
+        defined_sources = set(SOURCE_ID_RE.findall(src_text))
+        urls = URL_RE.findall(src_text)
+        if len(urls) < 5:
+            f_.warn(src.start + 1, f"Only {len(urls)} URL(s) in Sources — deep research normally yields far more")
+        for i, l in enumerate(lines, 1):
+            if src.start < i - 1 < src.end:
+                continue
+            for s_id in VERIFIED_SOURCE_RE.findall(l):
+                if s_id not in defined_sources:
+                    f_.err(i, f"[VERIFIED …] cites S-{s_id}, which is not in the Sources section")
+
+    # 7. Personas used
+    per = find_section(sections, "Personas")
+    if per:
+        per_text = block_text(lines, per.start, per.end)
+        defined_personas = sorted({int(x) for x in PERSONA_REF_RE.findall(per_text)})
+        if not defined_personas:
+            f_.err(per.start + 1, "Personas section defines no persona IDs (P1, P2, …)")
+        used = {int(x) for x in PERSONA_REF_RE.findall(all_story_text)}
+        for p in defined_personas:
+            if p not in used:
+                f_.err(per.start + 1, f"Persona P{p} is never referenced by any story — remove it or write its stories")
+
+    # 8. Copy IDs referenced vs defined
+    cp = find_section(sections, "Copy")
+    if cp:
+        cp_defined = set(CP_ID_RE.findall(block_text(lines, cp.start, cp.end)))
+        for sid, _, start, end in story_blocks:
+            for ref in set(CP_ID_RE.findall(block_text(lines, start, end))):
+                if ref not in cp_defined:
+                    f_.warn(start + 1, f"{sid} references copy ID {ref} that is not defined in the Copy section")
+
+    # 9. Heading anchors
+    for s in sections:
+        if any(ord(ch) > 127 and ch.isalpha() for ch in s.title) and not re.search(r"\([A-Za-z][A-Za-z0-9 &/\-]*\)", s.title):
+            f_.warn(s.start + 1, f"Heading '{s.title[:40]}' has no ASCII anchor in parentheses")
+
+    # 10. Session protocol / appendix
+    sp = find_section(sections, "Session Protocol")
+    if sp and "amendment" not in block_text(lines, sp.start, sp.end).lower():
+        f_.warn(sp.start + 1, "Session Protocol section does not mention the Amendments log")
+    if not find_section(sections, "Session Prompts"):
+        f_.warn(None, "No appendix with 'Session Prompts' — the user needs one copy-paste prompt per epic")
+
+    # 11. UNVERIFIED tags (only legitimate when web tools were unavailable)
+    unverified = sum(len(UNVERIFIED_RE.findall(l)) for l in lines)
+    if unverified:
+        f_.warn(None, f"{unverified} [UNVERIFIED] tag(s) — acceptable only with the no-web-access warning on the cover; the first build session must re-verify each")
+
+    # 12. Architecture drivers and the style decision
+    arch = find_section(sections, "Architecture")
+    ad_defined: set[str] = set()
+    if arch:
+        arch_text = block_text(lines, arch.start, arch.end)
+        # A driver is *defined* where its ID opens the line (optionally after a list marker, bold
+        # marker or heading hashes) or opens a table row's first cell. Everywhere else is a reference.
+        for i in range(arch.start, min(arch.end, len(lines))):
+            l = lines[i]
+            head = l.lstrip().lstrip("#*->|").lstrip().lstrip("*_ ")
+            m = AD_ID_RE.match(head)
+            if m:
+                ad_defined.add(m.group(1))
+        if not ad_defined:
+            f_.err(
+                arch.start + 1,
+                "Architecture section defines no drivers (AD-1, AD-2, …) — the style decision has "
+                "nothing to be scored against, which is how a stack gets chosen first and justified after",
+            )
+        elif len(ad_defined) < 3:
+            f_.warn(arch.start + 1, f"Only {len(ad_defined)} architecture driver(s) — 5–8 ranked drivers is the target")
+        # Each driver definition line must carry a measurable target. Strip the AD-n IDs first:
+        # the digit in the ID itself does not make the driver measurable.
+        for i in range(arch.start, min(arch.end, len(lines))):
+            l = lines[i]
+            head = l.lstrip().lstrip("#*->|").lstrip().lstrip("*_ ")
+            if LINT_IGNORE in l or not AD_ID_RE.match(head):
+                continue
+            if not DIGIT_RE.search(AD_ID_RE.sub("", l)):
+                f_.warn(
+                    i + 1,
+                    "Architecture driver with no number in it — a driver without a measurable target "
+                    "cannot decide anything ('scalable' is not a driver)",
+                )
+        if not FITNESS_RE.search(arch_text):
+            f_.err(
+                arch.start + 1,
+                "Architecture section never mentions fitness functions — boundaries that are described "
+                "but not enforced are gone within a few sessions",
+            )
+        if "non-driver" not in arch_text.lower() and "not optimis" not in arch_text.lower() and "not optimiz" not in arch_text.lower():
+            f_.warn(arch.start + 1, "No explicit non-drivers ('what we are NOT optimising for') in the Architecture section")
+
+    # Every AD-n referenced anywhere must be defined by a driver line in the Architecture section
+    if ad_defined:
+        for i, l in enumerate(lines, 1):
+            head = l.lstrip().lstrip("#*->|").lstrip().lstrip("*_ ")
+            if arch and arch.start < i - 1 < arch.end and AD_ID_RE.match(head):
+                continue  # this is the definition line itself
+            for ad in AD_ID_RE.findall(l):
+                if ad not in ad_defined:
+                    f_.err(i, f"AD-{ad} is referenced but never defined as a driver in the Architecture section")
+
+    # 13. Tech stack table shape — every row must name what the runner-up would have bought
+    if ts:
+        header = ""
+        for i in range(ts.start, min(ts.end, len(lines))):
+            if lines[i].lstrip().startswith("|") and "---" not in lines[i]:
+                header = lines[i].lower()
+                break
+        if header and "runner" not in header:
+            f_.warn(
+                ts.start + 1,
+                "Tech Stack table has no runner-up column — a choice with no stated cost was not a decision",
+            )
+
+    # 14. Quality section: the gate, the checklist, the critical paths
+    q = find_section(sections, "Quality")
+    if q:
+        q_lines = lines[q.start : q.end]
+        q_text = "\n".join(q_lines)
+        q_lower = q_text.lower()
+        if not CHECK_CMD_RE.search(q_text):
+            f_.err(
+                q.start + 1,
+                "Quality section names no `check` command in backticks — the build sessions have no "
+                "definition of green",
+            )
+        checklist_items = sum(1 for l in q_lines if CHECKLIST_ITEM_RE.match(l))
+        if checklist_items < 10:
+            f_.err(
+                q.start + 1,
+                f"Quality section contains {checklist_items} review-checklist item(s) of the form '[ ] …' — "
+                "embed the review checklist verbatim (code-quality-and-review.md §11) or the reviewer "
+                "invents a different standard every session",
+            )
+        if "e2e" not in q_lower and "end-to-end" not in q_lower:
+            f_.warn(q.start + 1, "Quality section does not name the critical e2e paths")
+        if "mutation" not in q_lower:
+            f_.warn(
+                q.start + 1,
+                "Quality section says nothing about mutation testing — name the tool for this stack, "
+                "or state that no maintained one exists",
+            )
+        if not METRIC_ROW_RE.search(q_text):
+            f_.warn(q.start + 1, "Quality section has no metrics table rows (M-nn) — nothing will be measured")
+        if "anti-metric" not in q_lower and "will not measure" not in q_lower and "not measure" not in q_lower:
+            f_.warn(
+                q.start + 1,
+                "Quality section lists no anti-metrics — say explicitly what will not be measured and why",
+            )
+
+    # 15. Banned productivity metrics inside metric definition rows
+    for i, l in enumerate(lines, 1):
+        if LINT_IGNORE in l or not METRIC_ROW_RE.search(l):
+            continue
+        m = BANNED_METRIC_RE.search(l)
+        if m:
+            f_.err(
+                i,
+                f"Metric row defines '{m.group(0)}' — output-per-person metrics are gamed the moment they "
+                "become targets; measure the system, not the author",
+            )
+        if COVERAGE_TARGET_RE.search(l) and "floor" not in l.lower():
+            f_.warn(
+                i,
+                "Coverage appears as a metric without the word 'floor' — state it as a regression floor, "
+                "never as a target to raise",
+            )
+
+    # 16. Report
+    print(f"Blueprint lint — {path}")
+    print(f"  epics: {len(epics)}   stories: {len(story_ids)}   sections: {len(sections)}")
+    if f_.errors:
+        print(f"\nERRORS ({len(f_.errors)}):")
+        for e in f_.errors:
+            print("  ✘ " + e)
+    if f_.warnings:
+        print(f"\nWARNINGS ({len(f_.warnings)}):")
+        for w in f_.warnings:
+            print("  ! " + w)
+    if not f_.errors and not f_.warnings:
+        print("\nPASS — no findings.")
+    elif not f_.errors:
+        print("\nPASS with warnings — resolve or justify each warning in the document.")
+    else:
+        print("\nFAIL — fix every error before delivering the blueprint.")
+    return 1 if f_.errors or (strict and f_.warnings) else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))

package/bundled-skills/liuguang-banlan-ui/SKILL.md

@@ -44,7 +44,7 @@ Read [style-contract.md](references/style-contract.md) before choosing a mode or
 
 - Choose a neutral, information-dense workbench domain such as field research, inventory, monitoring, or operations.
 - Use a continuous three-pane or similarly coherent workspace: navigation, queue/list, detail, metadata, and one signature observation band.
-- Keep color in the field, ribbon, markers, and state accents; keep text, controls, boundaries, and semantic hierarchy stable.
+- Keep color in the field, map markers, and state accents. Keep the logo, avatar, rules, text, controls, boundaries, and semantic hierarchy neutral; do not paint them with palette gradients.
 - Prefer restrained surfaces and weak fills. Avoid turning every region into a floating card.
 
 ### 4. Implement the parameter contract
@@ -58,16 +58,18 @@ Maintain a serializable manifest with these top-level fields:
   base: { oklch },
   colors: [{
     id, label, oklch, srgbFallback,
-    intensity, peakOpacity, lightnessBias,
+    intensity, peakOpacity,
     fieldScale, phase,
     measuredCoverage, effectiveShare
   }],
   field: { scale, octaves, warpStrength, motionSpeed, staticTime, ditherStrength, luminanceCap },
-  output: { colorSpace, p3Enhancement, reducedMotion }
+  output: { colorSpace, reducedMotion }
 }
 ```
 
-- Keep every intensity in `[0, 1]`; make `overallColorIntensity` the global budget and `colors[].intensity` the per-color budget.
+- Keep every intensity in `[0, 1]`; make `overallColorIntensity` the global budget and `colors[].intensity` the per-color budget. The renderer multiplies `intensity` by `peakOpacity`, so treat `peakOpacity` as the calibrated strength at full intensity.
+- Order `colors` by hue. The renderer draws six hue stops around a loop and mixes each color with its array neighbors; near-complementary neighbors mix toward gray.
+- `luminanceCap` applies only in `obsidian`. `ditherStrength` is the dither amplitude in output codes; `1` removes quantization bias.
 - Use OKLCH as the authoring space and provide an sRGB fallback for non-OKLCH contexts.
 - Keep the seed, static frame, phases, and field scales deterministic; do not use random per render.
 - Expose sliders for the global intensity and every configured color. Make reset, JSON export, and copy actions available.
@@ -77,8 +79,10 @@ Maintain a serializable manifest with these top-level fields:
 - Use a procedural fBm/domain-warp field or an equivalent continuous field; keep it behind the interface with `pointer-events: none`.
 - Use broad flowing hue regions or ribbons, not obvious radial blobs, spotlight circles, or hard rainbow bands.
 - Upload the complete palette and per-color field scales to the renderer. Apply the dark-mode luminance cap after palette mixing.
-- Provide a CSS fallback with comparable visual intent when WebGL is unavailable.
-- Pause or freeze motion when the document is hidden or `prefers-reduced-motion` is active.
+- Encode output with the sRGB transfer function, dither in output codes, and quantize in the shader. A power-curve encode or a weak linear-light dither biases the output, most visibly in low-intensity fields and near black.
+- Provide a CSS fallback with comparable visual intent when WebGL is unavailable, such as one soft hue-ordered sweep calibrated against the WebGL field; do not use fixed radial spots.
+- Pause or freeze motion when the document is hidden or `prefers-reduced-motion` is active, and keep field time continuous so pausing and resuming do not jump.
+- Repaint after every resize. Resizing clears the canvas, and a paused field has no next frame to redraw it.
 - Keep the renderer local and dependency-light; do not require remote fonts, images, or APIs for the starter.
 
 ### 6. Preserve interaction and accessibility
@@ -90,13 +94,10 @@ Maintain a serializable manifest with these top-level fields:
 ### 7. Validate and report
 
 - Scaffold a clean starter with `scripts/scaffold_template.py` when a neutral implementation is needed.
-- The bundled helpers parse only the restricted data-literal assignment used by
-  the starter. They reject expressions, function calls, duplicate keys,
-  unsupported syntax, trailing statements, and oversized manifests without
-  executing JavaScript. Keep runtime theme configs data-only as well.
-- Run `scripts/validate_manifest.py` on each theme config before rendering.
-- Capture desktop and mobile screenshots with a real browser. Inspect them directly if visual capability is available.
-- Run `scripts/measure_preview.py` on the pure field screenshot and retain measured chromatic ratio, luminance statistics, per-color coverage, and effective share.
+- Keep theme configs as data-only assignments. The bundled parser rejects expressions, function calls, duplicate keys, trailing statements, and oversized manifests without executing JavaScript.
+- Run `scripts/validate_manifest.py` on each theme config before rendering, and resolve its warnings.
+- Serve previews with `scripts/serve_preview.py`, which disables caching, then capture desktop and mobile screenshots with a real browser. Inspect them directly if visual capability is available.
+- Run `scripts/measure_preview.py` on the pure field screenshot and retain measured chromatic ratio, tint, lightness shift, gray ratio, per-color coverage, and effective share.
 - Report configured parameters separately from measured values; do not imply that pixel attribution is an exact shader contribution.
 - Use `partial`, `visual-unverified`, or `blocked` when a required capability or native check is unavailable.
 
@@ -123,14 +124,17 @@ Use the bundled starter under `assets/starter/` as a neutral base. Copy only the
 ### scripts/
 
 - `scaffold_template.py`: copy the neutral starter for `opal`, `obsidian`, or both.
-- `manifest_parser.py`: statically parse the restricted data-only manifest grammar without executing JavaScript.
-- `validate_manifest.py`: validate required manifest fields and ranges.
-- `measure_preview.py`: measure a rendered pure-field PNG against the configured OKLCH palette.
+- `manifest_parser.py`: statically parse the restricted data-only theme manifest without executing JavaScript.
+- `validate_manifest.py`: validate required fields and ranges, and warn about hue order.
+- `measure_preview.py`: measure a rendered pure-field PNG as OKLab deviation from the configured base, including lightness shift and gray ratio. Install optional dependencies from `scripts/requirements.txt` when needed.
+- `serve_preview.py`: serve a directory locally with caching disabled.
+
+Run `python -m unittest discover -s tests` after changing a script.
 
 ### references/
 
-- `style-contract.md`: mode-specific visual rules and recommended parameter ranges.
-- `verification.md`: visual-capability gate, browser QA, pixel measurement, and report schema.
+- `style-contract.md`: mode-specific visual rules, recommended parameter ranges, and calibration for pages where no panel covers the field.
+- `verification.md`: visual-capability gate, browser QA, pixel measurement, darkening check, and report schema.
 
 ### assets/
 

package/bundled-skills/liuguang-banlan-ui/assets/starter/launcher.css

@@ -9,8 +9,8 @@ header span { display: block; margin-top: 16px; color: oklch(70% 0.01 220); font
 .template-list { border-top: 1px solid oklch(100% 0 0 / .12); }
 .template { display: grid; grid-template-columns: 116px minmax(0, 1fr) auto; align-items: center; gap: 24px; padding: 24px 0; border-bottom: 1px solid oklch(100% 0 0 / .12); color: inherit; text-decoration: none; }
 .swatch { width: 116px; height: 76px; border: 1px solid oklch(100% 0 0 / .15); border-radius: 10px; transition: transform 180ms cubic-bezier(.25,1,.5,1); }
-.opal .swatch { background: radial-gradient(circle at 20% 20%, oklch(90% .06 197), transparent 48%), radial-gradient(circle at 80% 35%, oklch(92% .055 18), transparent 48%), radial-gradient(circle at 46% 95%, oklch(90% .05 302), transparent 54%), oklch(98% .004 94); }
-.obsidian .swatch { background: radial-gradient(circle at 20% 20%, oklch(27% .07 188), transparent 50%), radial-gradient(circle at 80% 35%, oklch(23% .06 284), transparent 52%), radial-gradient(circle at 46% 95%, oklch(24% .05 78), transparent 56%), oklch(10% .012 236); }
+.opal .swatch { background: linear-gradient(100deg, oklch(93.5% .047 18), oklch(94% .041 62), oklch(93.6% .036 159), oklch(92.8% .043 201), oklch(91.8% .05 248), oklch(92.5% .045 304)); }
+.obsidian .swatch { background: linear-gradient(100deg, oklch(29% .055 188), oklch(25% .048 211), oklch(22.5% .047 251), oklch(24% .052 278), oklch(25.5% .05 318), oklch(30% .045 82)); }
 .copy small { display: block; color: oklch(58% 0.012 220); font-size: 10px; letter-spacing: .08em; text-transform: uppercase; }
 .copy strong { display: block; margin-top: 5px; font-size: 18px; font-weight: 620; }
 .copy span { display: block; margin-top: 6px; color: oklch(68% 0.012 220); font-size: 12px; }

package/bundled-skills/liuguang-banlan-ui/assets/starter/obsidian/index.html

@@ -116,10 +116,11 @@
           <article class="pane detail-pane" aria-labelledby="record-title">
             <div class="pane-head">
               <div class="tab-list" role="tablist" aria-label="记录视图">
-                <button class="tab" type="button" role="tab" aria-selected="true" aria-controls="detail-copy" data-copy="水线后退约 1.8 米，潮池外缘出现连续盐度跃迁。样本表面保持湿润，未观察到明显扰动。建议与 18:53 的浅滩网格记录并列复核。">记录</button>
-                <button class="tab" type="button" role="tab" aria-selected="false" aria-controls="detail-copy" data-copy="关联了 4 张现场照片、2 个水质读数与 1 条位置修正。附件校验通过，原始文件已进入只读归档队列。">附件</button>
-                <button class="tab" type="button" role="tab" aria-selected="false" aria-controls="detail-copy" data-copy="19:47 完成盐度标签修正；20:12 补充观察者备注；21:03 进入批次复核队列。所有变更均保留原始记录。">变更</button>
+                <button class="tab" type="button" role="tab" aria-controls="detail-copy" aria-selected="true" data-copy="水线后退约 1.8 米，潮池外缘出现连续盐度跃迁。样本表面保持湿润，未观察到明显扰动。建议与 18:53 的浅滩网格记录并列复核。">记录</button>
+                <button class="tab" type="button" role="tab" aria-controls="detail-copy" aria-selected="false" data-copy="关联了 4 张现场照片、2 个水质读数与 1 条位置修正。附件校验通过，原始文件已进入只读归档队列。">附件</button>
+                <button class="tab" type="button" role="tab" aria-controls="detail-copy" aria-selected="false" data-copy="19:47 完成盐度标签修正；20:12 补充观察者备注；21:03 进入批次复核队列。所有变更均保留原始记录。">变更</button>
               </div>
+              <button class="icon-button" type="button" aria-label="更多记录操作"><svg viewBox="0 0 24 24" fill="currentColor" stroke="none"><circle cx="5" cy="12" r="1.5"/><circle cx="12" cy="12" r="1.5"/><circle cx="19" cy="12" r="1.5"/></svg></button>
             </div>
             <div class="detail-title">
               <h2 id="record-title">潮池边缘 · 样本 042</h2>
@@ -127,7 +128,7 @@
             </div>
             <div class="detail-body">
               <div class="field-notes">
-            <p id="detail-copy" role="tabpanel">水线后退约 1.8 米，潮池外缘出现连续盐度跃迁。样本表面保持湿润，未观察到明显扰动。建议与 18:53 的浅滩网格记录并列复核。</p>
+                <p id="detail-copy" role="tabpanel">水线后退约 1.8 米，潮池外缘出现连续盐度跃迁。样本表面保持湿润，未观察到明显扰动。建议与 18:53 的浅滩网格记录并列复核。</p>
                 <dl>
                   <div class="note-rule"><dt>表面温度</dt><dd>18.6 °C · 稳定</dd></div>
                   <div class="note-rule"><dt>盐度</dt><dd>31.8 PSU · 高于同批中位值 1.4</dd></div>

package/bundled-skills/liuguang-banlan-ui/assets/starter/obsidian/theme-config.js

@@ -1,8 +1,8 @@
 window.SPECTRAL_THEME = {
-  schemaVersion: "1.0",
+  schemaVersion: "1.1",
   mode: "obsidian",
   label: "五彩斑斓黑",
-  preset: "obsidian-fieldnote-v1",
+  preset: "obsidian-fieldnote-v2",
   seed: 90821,
   overallColorIntensity: 1.0,
   base: {
@@ -16,7 +16,6 @@ window.SPECTRAL_THEME = {
       srgbFallback: "#183f3d",
       intensity: 0.72,
       peakOpacity: 0.29,
-      lightnessBias: 0.008,
       fieldScale: 0.84,
       phase: [0.11, 0.72],
       measuredCoverage: null,
@@ -29,7 +28,6 @@ window.SPECTRAL_THEME = {
       srgbFallback: "#17333a",
       intensity: 0.62,
       peakOpacity: 0.27,
-      lightnessBias: 0.006,
       fieldScale: 0.96,
       phase: [0.74, 0.19],
       measuredCoverage: null,
@@ -42,7 +40,6 @@ window.SPECTRAL_THEME = {
       srgbFallback: "#202b42",
       intensity: 0.54,
       peakOpacity: 0.26,
-      lightnessBias: 0.004,
       fieldScale: 1.08,
       phase: [0.37, 0.88],
       measuredCoverage: null,
@@ -55,7 +52,6 @@ window.SPECTRAL_THEME = {
       srgbFallback: "#2d2948",
       intensity: 0.42,
       peakOpacity: 0.24,
-      lightnessBias: 0.005,
       fieldScale: 0.91,
       phase: [0.93, 0.57],
       measuredCoverage: null,
@@ -68,7 +64,6 @@ window.SPECTRAL_THEME = {
       srgbFallback: "#3a293d",
       intensity: 0.30,
       peakOpacity: 0.21,
-      lightnessBias: 0.004,
       fieldScale: 1.14,
       phase: [0.25, 0.31],
       measuredCoverage: null,
@@ -81,7 +76,6 @@ window.SPECTRAL_THEME = {
       srgbFallback: "#473c22",
       intensity: 0.18,
       peakOpacity: 0.17,
-      lightnessBias: 0.007,
       fieldScale: 1.03,
       phase: [0.61, 0.46],
       measuredCoverage: null,
@@ -94,12 +88,11 @@ window.SPECTRAL_THEME = {
     warpStrength: 0.41,
     motionSpeed: 0.01,
     staticTime: 2.18,
-    ditherStrength: 0.82,
+    ditherStrength: 1,
     luminanceCap: 0.165
   },
   output: {
     colorSpace: "srgb",
-    p3Enhancement: "feature-detected",
     reducedMotion: "frozen-calibrated-frame"
   }
 };