ocmm 0.5.0 → 0.5.2

package/skills/frontend/references/design/design-system-architecture.md

@@ -15,11 +15,19 @@ Every frontend project MUST have a `DESIGN.md` at its root. This file is the sin
 
 ## DESIGN.md Structure
 
-The file has 7 sections. Every section is mandatory. Skip nothing.
+The file has nine sections, numbered 0 through 8. Every section is mandatory. Skip nothing. Section 0 applies to greenfield UI; existing-project extraction may state that historical research is unavailable instead of inventing it.
 
 ```markdown
 # [Project Name] Design System
 
+## 0. Research Log
+
+For greenfield UI, record the design decision before writing product screens.
+
+- **Candidates considered**: 2-3 relevant local Layer B/design references, with a short reason each fits or does not fit.
+- **Selection**: the chosen Layer A execution skill and Layer B/design reference, with rationale tied to the product and audience.
+- **Evidence (optional)**: a local `ui-ux-db` lookup, user-provided image, or local mockup. If a tool/source is unavailable or not relevant, record the reason instead of forcing network research.
+
 ## 1. Atmosphere & Identity
 
 One paragraph. What this product FEELS like. Not what it does — how it feels to use.
@@ -112,18 +120,23 @@ All spacing derives from a base of **4px**.
 
 ## 5. Components
 
-Document reusable patterns as they emerge. Format:
+### Planned Showcase Primitives
+
+This is a pre-implementation verification checklist, not reusable component documentation. Before composing a greenfield product screen, list each intended primitive and check its applicable default, hover, focus, disabled, loading, empty, and error states in a component showcase or equivalent state page.
+
+### Implemented Reusable Patterns
+
+Document only implemented reusable patterns used 2+ times. Format:
 
 ### [Component Name]
 - **Structure**: HTML/JSX outline
 - **Variants**: list
 - **Spacing**: which tokens
-- **States**: default, hover, active, focus, disabled, loading, error
+- **States**: default, hover, active, focus, disabled, loading, empty, error
 - **Accessibility**: keyboard, ARIA, contrast
 - **Motion**: entry/exit animations
 
-Start with components used 2+ times. Do not pre-document components
-that don't exist yet.
+Do not promote planned primitives or one-off implementations into reusable component documentation.
 
 ## 6. Motion & Interaction
 
@@ -162,6 +175,20 @@ If borders:
 
 If tonal-shift:
 Surfaces use progressively lighter/darker shades. No borders, no shadows.
+
+## 8. Accessibility Constraints & Accepted Debt
+
+### Constraints
+
+- **WCAG goal**: state the target level and the testable scope.
+- **Contrast**: document text, control, and focus-indicator contrast requirements.
+- **Keyboard and focus**: every interactive primitive has a keyboard path and visible focus treatment.
+- **ARIA**: semantic HTML first; document required names, roles, and live-region behavior for custom controls.
+- **Reduced motion**: respect `prefers-reduced-motion` and identify any essential motion.
+
+### Accepted Debt
+
+Each exception records its location, reason, owner, and exit criteria. An agent may not accept accessibility debt or a constraint exception silently: it requires explicit user authorization.
 ```
 
 ## Creation Workflow
@@ -169,13 +196,15 @@ Surfaces use progressively lighter/darker shades. No borders, no shadows.
 ### For New Projects
 
 1. **Ask or infer the product domain** — SaaS dashboard? Marketing site? Dev tool?
-2. **Write the Atmosphere paragraph** — one chance to establish identity.
-3. **Define palette** — derive from atmosphere. Not random. Not generic.
-4. **Set typography** — match the atmosphere. Editorial = serif. Technical = mono-heavy. Clean = geometric sans.
-5. **Lock spacing** — base-4 system. Customize only the section-level values.
-6. **Document initial components** — only those you are about to build.
-7. **Choose depth strategy** — one. Not "a mix."
-8. **Write it to `DESIGN.md`** at project root.
+2. **Write the Research Log** — consider 2-3 relevant local design candidates, select Layer A + Layer B, and record optional local evidence or why it was unavailable.
+3. **Write the Atmosphere paragraph** — one chance to establish identity.
+4. **Define palette** — derive from atmosphere. Not random. Not generic.
+5. **Set typography** — match the atmosphere. Editorial = serif. Technical = mono-heavy. Clean = geometric sans.
+6. **Lock spacing** — base-4 system. Customize only the section-level values.
+7. **Fill in Planned Showcase Primitives** — use the pre-implementation verification checklist to cover intended primitives and states before composing a product screen; do not treat it as reusable component documentation.
+8. **Choose depth strategy** — one. Not "a mix."
+9. **Set accessibility constraints and record no debt without user authorization.**
+10. **Write it to `DESIGN.md`** at project root.
 
 ### For Existing Projects (Extraction)
 
@@ -194,8 +223,10 @@ After every component implementation, check:
 - [ ] All spacing values are multiples of `--space-1` (4px). No magic numbers.
 - [ ] Interactive elements have all required states from Section 6.
 - [ ] Depth treatment matches the chosen strategy from Section 7.
-- [ ] Component reused 2+ times? Documented in Section 5.
+- [ ] Implemented reusable pattern used 2+ times? Documented in Section 5.
 - [ ] Motion follows the timing table. No arbitrary durations.
+- [ ] `Planned Showcase Primitives` is complete for greenfield UI, with a showcase (or equivalent state page) covering default, hover, focus, disabled, loading, empty, and error before product-screen composition.
+- [ ] Section 8 constraints were checked; any accepted debt has location, reason, owner, exit criteria, and explicit user authorization.
 
 ## Memory Management
 

package/skills/v1/requesting-code-review/SKILL.md

@@ -77,6 +77,10 @@ Two reviewer agents are available, with distinct semantics:
 
 **Default:** `oracle` for simple tasks. Upgrade to both when the orchestrator judges the task complex or large.
 
+`oracle` can also be an optional independent consultation for a high-risk implementation plan. It does not replace the `plan-critic` receipt, does not make dual plan review mandatory, and a timeout or partial response is not a conclusion.
+
+**GPT/Codex reasoning policy:** `reviewer` and `oracle` use `xhigh` minimum. For complex or high-risk review or verification, request local `max`; the adapter maps it to the target's maximum supported effort (currently `xhigh` for GPT/Codex). `plan-critic` remains `xhigh`.
+
 ## Example
 
 ```

package/skills/v1/writing-plans/SKILL.md

@@ -154,24 +154,26 @@ If you find issues, fix them inline. No need to re-review — just fix and move
 
 ## plan-critic Review Loop
 
-After self-review passes, submit the plan to the `plan-critic` agent for a mandatory review loop. The plan-critic agent reads the plan path or inline plan and returns a three-state verdict.
+After self-review passes, submit the plan to the `plan-critic` agent for a mandatory review loop. A review round covers exactly one saved, complete, current plan revision. A current receipt is valid only when that round returns an explicit `[OKAY]` or `[OKAY-UNAMBIGUOUS]`; any plan edit invalidates every earlier receipt.
+
+Timeouts, `WORKING`, acknowledgements, partial output, a missing verdict, or a review of an older/incomplete plan are not approval. Wait for a complete verdict, follow up, or re-dispatch the critic for the current full plan. Dispatch success is not a receipt.
 
 **Loop procedure:**
 
-1. Submit the plan to the `plan-critic` agent (pass the plan file path, or the inline plan if not yet saved).
-2. Dispatch the plan-critic agent and wait for its verdict.
+1. Save the complete plan, then submit that exact plan path to the `plan-critic` agent.
+2. Dispatch the plan-critic agent and wait for one explicit verdict for the current revision.
 3. Branch on the verdict:
 
    | Verdict | Meaning | Action |
    |---|---|---|
-   | `[REJECT]` | Critical blockers exist; plan not executable as-is | Apply the blocker fixes (max 3), re-run self-review, resubmit. Loop. |
+   | `[REJECT]` | Critical blockers exist; plan not executable as-is | Apply the blocker fixes (max 3), re-run self-review, save the updated complete plan, then begin a fresh critic round. |
    | `[OKAY]` | Plan is executable; residual uncertainty/ambiguity remains | Exit the loop. Proceed to user approval (unless delegation applies). |
    | `[OKAY-UNAMBIGUOUS]` | Plan is executable AND logically clear with no ambiguity | Exit the loop. Skip user approval. Proceed to Execution Handoff. |
 
 **Loop cap (user delegation "review N 次就下一步"):**
 
 If the user has delegated with "review N 次就下一步" / "review N times then proceed", cap the loop at N iterations. After N iterations:
-- If still `[REJECT]`: record the unresolved blockers in the plan (as a "Known Unresolved Blockers" section) and proceed anyway. Do not block the workflow.
+- If still `[REJECT]`, or no current receipt exists: record unresolved blockers in the plan (as a "Known Unresolved Blockers" section) and proceed only under the explicit status `delegated-without-plan-approval`. Do not call this approved, passed, or receipted.
 - If `[OKAY]` or `[OKAY-UNAMBIGUOUS]` reached before N: exit early.
 
 **Plan approval conditionality:**
@@ -185,11 +187,13 @@ After the loop exits, determine whether user approval is required:
 
   > "Plan written to `<path>`. plan-critic verdict: `[OKAY]` (executable, residual uncertainty). Please review and approve before execution, or delegate with '你自己决定' / '无需批准自行继续' to proceed."
 
-  Wait for the user's response. If they request changes, make them, re-run self-review, and re-run the plan-critic loop. Only proceed once the user approves or delegates.
+  Wait for the user's response. If they request changes, make them, re-run self-review, and re-run the plan-critic loop for the changed plan. Only proceed once the user approves or delegates.
+
+`oracle` may provide an optional, independent consultation for a high-risk plan, but it never replaces the current `plan-critic` receipt and does not create a mandatory dual-review gate.
 
 ## Execution Handoff
 
-After saving the plan, proceed to the subagent-driven-development skill to execute it.
+Proceed to the subagent-driven-development skill only with a current plan-critic receipt, user approval where required, or an explicitly labeled `delegated-without-plan-approval` exception. Report the current receipt verdict or `waiting for receipt`; never treat a dispatch timeout or acknowledgement as pass.
 
 **Execution:**
 - Fresh subagent per task + completion/integration check after each returned agent + final acceptance review once after all tasks