opencastle 0.32.12 → 0.33.0

package/src/orchestrator/skills/documentation-standards/WRITING-GUIDE.md

@@ -0,0 +1,39 @@
+> Parent: [SKILL.md](./SKILL.md)
+
+# Writing & Formatting Guide
+
+## Voice & Tone
+
+- **Imperative mood** for instructions: "Add the header" not "You should add the header"
+- **Active voice**: "The function returns X" not "X is returned by the function"
+- **Concise**: one idea per sentence; trim filler words (just, simply, basically, very)
+
+## Formatting Rules
+
+| Element | Convention |
+|---------|-----------|
+| Headings | Sentence case (`## Core principles`, not `## Core Principles`). Exception: proper nouns and acronyms. |
+| Lists | Parallel structure — all items start with the same part of speech |
+| Code | Inline backticks for symbols/commands; fenced blocks for multi-line |
+| Links | Descriptive text: `[migration guide](./migrate.md)` not `[click here](./migrate.md)` |
+| Tables | Use for structured comparisons; keep columns ≤5 |
+| Line length | Wrap prose at ~120 characters for diff readability |
+
+## Markdown Standards
+
+- One blank line before and after headings, code blocks, and tables
+- No trailing whitespace
+- Files end with a single newline
+- Use `---` for horizontal rules (sparingly)
+- Prefer `-` for unordered lists
+
+## Anti-Patterns
+
+| Anti-pattern | Fix |
+|-------------|-----|
+| Walls of prose without structure | Break into headings, bullets, or tables |
+| Duplicate content across docs | Link to the canonical source |
+| Stale "Last Updated" dates | Remove or automate; manual dates drift |
+| TODO/FIXME placeholders in published docs | Resolve before merging |
+| Screenshots without alt text | Add descriptive alt text for accessibility |
+| Overly nested headings (h4+) | Flatten; if you need h4, consider splitting the doc |

package/src/orchestrator/skills/fast-review/REFERENCE.md

@@ -0,0 +1,30 @@
+> Parent: [SKILL.md](./SKILL.md)
+
+# Fast Review — Reviewer Prompt Template
+
+```markdown
+You are a code reviewer. Be concise and specific.
+
+## Task: [ID] — [Title]
+Acceptance Criteria: [list]
+
+## File Partition: [allowed dirs/files]
+## Changed Files: [path + key diff]
+## Deterministic: Lint: [P/F] | Tests: [P/F] | Build: [P/F]
+
+## Checklist
+1. Acceptance criteria met?
+2. Partition respected?
+3. No regressions?
+4. Errors surfaced (no swallowed exceptions)?
+5. Type safety (no `as any`)?
+6. No secrets/injection vectors?
+7. Edge cases handled?
+
+## Prior Feedback (retry only): [previous FAIL]
+
+VERDICT: PASS | FAIL
+ISSUES: - [severity:critical|major|minor] Description
+FEEDBACK: [Actionable feedback.]
+CONFIDENCE: low | medium | high
+```

package/src/orchestrator/skills/fast-review/SKILL.md

@@ -1,7 +1,6 @@
-````skill
 ---
 name: fast-review
-description: "Mandatory single-reviewer gate that runs after every agent delegation. Provides automatic retry with feedback and escalation to panel review after repeated failures. Essential for overnight/long-running autonomous sessions."
+description: "Mandatory post-delegation gate that checks output completeness, verifies acceptance criteria compliance, flags regressions, and produces a PASS/FAIL verdict. Use when checking delegated work against acceptance criteria, running the post-delegation gate, validating agent output before acceptance, verifying a sub-agent completed its assignment, or running a post-delegation QA check."
 ---
 
 # Skill: Fast Review
@@ -14,7 +13,7 @@ description: "Mandatory single-reviewer gate that runs after every agent delegat
 | Reviewer | Single sub-agent; Economy tier (Standard for premium/security work) |
 | Verdict | PASS or FAIL with structured feedback |
 | Retry | ≤2 retries on FAIL; 3rd FAIL → panel review |
-| Budget | ~2–5 min |
+ 
 
 ## Procedure
 
@@ -26,6 +25,10 @@ Issue + acceptance criteria, file diff, file partition, deterministic results (l
 
 Single `runSubagent`. Context = acceptance criteria, diff, partition, deterministic results **only** — no session history, no delegation prompt.
 
+```js
+runSubagent({ agentName: 'Reviewer', prompt: `Review against ACs:\n${criteria}\nDiff:\n${diff}\nGates: lint ✅ test ✅ build ✅` });
+```
+
 ### 3 — Parse Verdict
 
 ```
@@ -54,37 +57,16 @@ CONFIDENCE: low | medium | high
 
 ## Reviewer Prompt Template
 
-```markdown
-You are a code reviewer. Be concise and specific.
-
-## Task: [ID] — [Title]
-Acceptance Criteria: [list]
+See [REFERENCE.md](REFERENCE.md) for the full reviewer prompt template.
 
-## File Partition: [allowed dirs/files]
-## Changed Files: [path + key diff]
-## Deterministic: Lint: [P/F] | Tests: [P/F] | Build: [P/F]
-
-## Checklist
-1. Acceptance criteria met?
-2. Partition respected?
-3. No regressions?
-4. Errors surfaced (no swallowed exceptions)?
-5. Type safety (no `as any`)?
-6. No secrets/injection vectors?
-7. Edge cases handled?
+## Logging
 
-## Prior Feedback (retry only): [previous FAIL]
+> **⛔ HARD GATE — Log the review before proceeding.**
 
-VERDICT: PASS | FAIL
-ISSUES: - [severity:critical|major|minor] Description
-FEEDBACK: [Actionable feedback.]
-CONFIDENCE: low | medium | high
+```sh
+npx opencastle log review --skill <name> --outcome pass|fail --reviewer "Reviewer" --mechanism sub-agent
 ```
 
-## Logging
-
-> **⛔ HARD GATE — Log the review before proceeding.** Use **observability-logging** skill's review record command.
-
 ## Integration & Overnight Mode
 
 `on-post-delegate` Gate 5 (after deterministic Gates 1–4), ~5–15% token overhead. Overnight: upgrade one tier, escalate after 2 FAILs, checkpoint before panel.
@@ -97,5 +79,3 @@ CONFIDENCE: low | medium | high
 - **Ignoring minor issues** — track; 3+ recurrences → ticket.
 - **Force-accepting FAIL** — retry or escalate.
 - **Skipping deterministic checks** — does NOT replace lint/test/build.
-
-````

package/src/orchestrator/skills/frontend-design/COMPONENTS.md

@@ -0,0 +1,113 @@
+> Parent: [SKILL.md](./SKILL.md)
+
+# Frontend Design Components
+
+Extended component patterns, card variants, and hero animations for the **frontend-design** skill.
+
+## Design Tokens (starter)
+
+```css
+:root {
+	--color-bg: #0f1724;
+	--color-ink: #e6eef8;
+	--color-accent: #ff7a59;
+	--space-1: 4px;
+	--space-2: 8px;
+	--space-3: 16px;
+	--radius-1: 6px;
+}
+```
+
+## Entrance Animation (starter)
+
+```css
+@keyframes fadeUp {
+	from { opacity: 0; transform: translateY(8px); }
+	to   { opacity: 1; transform: translateY(0); }
+}
+
+@media (prefers-reduced-motion: no-preference) {
+	.fade-in-up { animation: fadeUp 420ms cubic-bezier(.2,.9,.2,1) both; }
+}
+```
+
+## Card Patterns
+
+### Glass Card
+
+```css
+.card-glass {
+	background: rgba(255, 255, 255, 0.05);
+	backdrop-filter: blur(12px);
+	border: 1px solid rgba(255, 255, 255, 0.1);
+	border-radius: var(--radius-1);
+	padding: var(--space-3);
+}
+```
+
+### Elevated Card
+
+```css
+.card-elevated {
+	background: var(--color-bg);
+	border-radius: var(--radius-1);
+	padding: var(--space-3);
+	box-shadow: 0 4px 24px rgba(0, 0, 0, 0.12);
+	transition: transform 200ms ease, box-shadow 200ms ease;
+}
+.card-elevated:hover {
+	transform: translateY(-2px);
+	box-shadow: 0 8px 32px rgba(0, 0, 0, 0.18);
+}
+```
+
+## Hero Animations
+
+### Staggered Fade-In
+
+```css
+.hero-stagger > * {
+	opacity: 0;
+	transform: translateY(12px);
+	animation: fadeUp 500ms cubic-bezier(.2,.9,.2,1) forwards;
+}
+.hero-stagger > *:nth-child(1) { animation-delay: 0ms; }
+.hero-stagger > *:nth-child(2) { animation-delay: 80ms; }
+.hero-stagger > *:nth-child(3) { animation-delay: 160ms; }
+```
+
+### Gradient Shift
+
+```css
+.hero-gradient {
+	background: linear-gradient(135deg, var(--color-accent), var(--color-bg));
+	background-size: 200% 200%;
+	animation: gradientShift 6s ease infinite;
+}
+@keyframes gradientShift {
+	0%, 100% { background-position: 0% 50%; }
+	50% { background-position: 100% 50%; }
+}
+```
+
+## Button Variants
+
+```css
+.btn-primary {
+	background: var(--color-accent);
+	color: #fff;
+	padding: var(--space-2) var(--space-3);
+	border-radius: var(--radius-1);
+	font-weight: 600;
+	transition: opacity 150ms ease;
+}
+.btn-primary:hover { opacity: 0.9; }
+
+.btn-ghost {
+	background: transparent;
+	color: var(--color-ink);
+	border: 1px solid currentColor;
+	padding: var(--space-2) var(--space-3);
+	border-radius: var(--radius-1);
+}
+```

package/src/orchestrator/skills/frontend-design/REFERENCE.md

@@ -0,0 +1,36 @@
+> Parent: [SKILL.md](./SKILL.md)
+
+Frontend Design REFERENCE: detailed principles, typography catalogue, tokens, and component patterns.
+
+Last Updated: 2026-03-31
+
+## Design Principles (extended)
+
+| Dimension | Rule |
+|-----------|------|
+| Direction | Pick an extreme aesthetic (brutally minimal, maximalist, retro-futuristic, luxury, brutalist, art deco, editorial…) and commit fully. Name it in 2–3 words. |
+| Typography | Characterful display+body pair. No Inter/Roboto/Arial. `clamp()` fluid scale; heading lh ~1.1–1.2, body lh ~1.5–1.7; letter-spacing on uppercase/small. |
+| Color | CSS vars only; dominant + sharp accent hierarchy; WCAG AA (4.5:1 body, 3:1 large); dark/light both intentional. |
+| Motion | CSS-only for HTML; Motion library for React; staggered page entrance; custom easing; `prefers-reduced-motion` fallback. |
+| Layout | Asymmetry, overlap, diagonal flow, grid-breaking. Consistent spacing tokens — no ad-hoc values. Holds at mobile/tablet/desktop. |
+| Atmosphere | Gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows. No purple-on-white defaults. |
+
+## Typography Pairings (catalogue)
+
+| Aesthetic | Display | Body | Mood |
+|-----------|---------|------|------|
+| Editorial luxury | Playfair Display | Source Serif 4 | Authoritative, rich |
+| Swiss precision | Darker Grotesque | IBM Plex Sans | Sharp grotesque |
+| Warm humanist | Fraunces | Nunito Sans | Friendly, approachable |
+| Brutalist edge | Monument Extended | JetBrains Mono | Raw technical power |
+| Art nouveau organic | Cormorant Garamond | Lora | Flowing, calligraphic |
+| Retro-futuristic | Syne | Outfit | Geometric boldness |
+
+## Tokens & Patterns
+
+See `COMPONENTS.md` for tokens and component code snippets. This reference holds the rationale and extended examples used across projects.
+
+## Usage
+
+- Use these tables to choose a type system and enforce token fallbacks.
+- Link lessons and PRs that change foundational tokens to the `project-consistency` skill guidance.

package/src/orchestrator/skills/frontend-design/SKILL.md

@@ -1,111 +1,62 @@
 ---
 name: frontend-design
-description: "Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics."
+description: "Defines a named visual aesthetic, selects typography pairings, builds CSS token systems, and adds entrance animations for high-design-quality pages. Use when the user asks to design a landing page, style a marketing site, create a distinctive UI theme, pick fonts, or add CSS animations — specifically when visual polish and brand identity matter rather than generic component scaffolding."
 license: Complete terms in LICENSE.txt
 ---
 
 <!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .opencastle/ directory instead. -->
 
-## Design Principles
-
-| Dimension | Rule |
-|-----------|------|
-| Direction | Pick an extreme aesthetic (brutally minimal, maximalist, retro-futuristic, luxury, brutalist, art deco, editorial…) and commit fully. Name it in 2–3 words. |
-| Typography | Characterful display+body pair. No Inter/Roboto/Arial. `clamp()` fluid scale; heading lh ~1.1–1.2, body lh ~1.5–1.7; letter-spacing on uppercase/small. |
-| Color | CSS vars only; dominant + sharp accent hierarchy; WCAG AA (4.5:1 body, 3:1 large); dark/light both intentional. |
-| Motion | CSS-only for HTML; Motion library for React; staggered page entrance; custom easing; `prefers-reduced-motion` fallback. |
-| Layout | Asymmetry, overlap, diagonal flow, grid-breaking. Consistent spacing tokens — no ad-hoc values. Holds at mobile/tablet/desktop. |
-| Atmosphere | Gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows. No purple-on-white defaults. |
+## Design Workflow
 
-**Every design must have one unforgettable detail.** No two designs should look alike.
+1. **Name the aesthetic** — declare a 2–3 word direction in a code comment at the top of the main CSS file
+2. **Set foundations** — define `:root` CSS custom properties for colors, spacing, and radii
+3. **Build components** — implement layout, cards, heroes, forms using only tokens from step 2
+4. **Add motion** — add `@keyframes` entrance animations wrapped in a reduced-motion guard
+5. **Validate** — run Quality Checklist below; fix any failing item before marking done
 
-## Design System Foundations
+### Quick-start example
 
 ```css
+/* Aesthetic: minimal neon */
 :root {
-  --color-ink:     #1a1614;  --color-paper:   #f5f0e8;
-  --color-accent:  #c8e630;  --color-muted:   #9b9083;
-  --color-surface: #eae3d8;  --color-border:  rgba(26, 22, 20, 0.08);
-
-  --text-sm:   clamp(0.875rem, 0.83rem + 0.22vw, 1rem);
-  --text-base: clamp(1rem, 0.95rem + 0.25vw, 1.125rem);
-  --text-xl:   clamp(1.563rem, 1.35rem + 1.06vw, 2rem);
-  --text-2xl:  clamp(1.953rem, 1.6rem + 1.77vw, 2.75rem);
-  --text-hero: clamp(2.441rem, 1.8rem + 3.2vw, 4.5rem);
-
-  --space-2: 0.5rem; --space-4: 1rem;  --space-6: 1.5rem;
-  --space-8: 2rem;   --space-16: 4rem; --space-32: 8rem;
-
-  --ease-out-expo:    cubic-bezier(0.16, 1, 0.3, 1);
-  --ease-in-out-back: cubic-bezier(0.68, -0.6, 0.32, 1.6);
-  --duration-fast: 150ms; --duration-normal: 300ms; --duration-slow: 600ms;
-
-  --shadow-md: 0 4px 16px rgba(26, 22, 20, 0.08);
-  --shadow-lg: 0 12px 48px rgba(26, 22, 20, 0.12);
-}
-```
-
-## Component Patterns
-
-**Card:**
-```css
-.card {
-  position: relative;
-  background: var(--color-paper);
-  border: 1px solid var(--color-border);
-  border-left: 4px solid var(--color-accent);
-  padding: var(--space-8) var(--space-6);
-  transition: transform var(--duration-normal) var(--ease-out-expo),
-              box-shadow var(--duration-normal) var(--ease-out-expo);
-}
-.card:hover { transform: translateY(-3px); box-shadow: var(--shadow-lg); }
-.card__label {
-  position: absolute; top: calc(-1 * var(--space-3)); left: var(--space-4);
-  background: var(--color-accent); color: var(--color-ink);
-  font-size: var(--text-xs); font-weight: 700;
-  letter-spacing: 0.08em; text-transform: uppercase;
-  padding: var(--space-1) var(--space-3);
+  --color-bg: #0a0a0f; --color-surface: #141420;
+  --color-text: #e8e6e3; --color-accent: #6366f1;
+  --space-sm: 8px; --space-md: 16px; --space-lg: 32px;
+  --radius-md: 8px;
+  --font-heading: 'Fraunces', 'Georgia', serif;
+  --font-body: 'Inter', system-ui, sans-serif;
 }
-```
-
-**Hero staggered reveal:**
-```css
-@keyframes rise {
-  from { opacity: 0; transform: translateY(24px); }
+@keyframes fade-up {
+  from { opacity: 0; transform: translateY(12px); }
   to   { opacity: 1; transform: translateY(0); }
 }
-.hero           { overflow: hidden; padding: var(--space-32) var(--space-8); }
-.hero__eyebrow  { animation: rise var(--duration-slow) var(--ease-out-expo) both; animation-delay: 100ms; }
-.hero__headline { animation: rise var(--duration-slow) var(--ease-out-expo) both; animation-delay: 250ms; }
-.hero__body     { animation: rise var(--duration-slow) var(--ease-out-expo) both; animation-delay: 400ms; }
-.hero__cta      { animation: rise var(--duration-slow) var(--ease-out-expo) both; animation-delay: 550ms; }
+@media (prefers-reduced-motion: no-preference) {
+  .hero__title { animation: fade-up 0.4s ease-out both; }
+}
 ```
 
-## Typography Pairings
-
-| Aesthetic | Display | Body | Mood |
-|-----------|---------|------|------|
-| Editorial luxury | Playfair Display | Source Serif 4 | Authoritative, rich |
-| Swiss precision | Darker Grotesque | IBM Plex Sans | Sharp grotesque |
-| Warm humanist | Fraunces | Nunito Sans | Friendly, approachable |
-| Brutalist edge | Monument Extended | JetBrains Mono | Raw technical power |
-| Art nouveau organic | Cormorant Garamond | Lora | Flowing, calligraphic |
-| Retro-futuristic | Syne | Outfit | Geometric boldness |
+Card patterns, hero animations, and extended token sets are in [COMPONENTS.md](./COMPONENTS.md).
 
-Include a metric-preserving fallback chain (e.g., `'Fraunces', 'Georgia', serif`).
+## Design Principles
 
-## Quality Checklist
+High-level design principles and the full set of example constraints live in [REFERENCE.md](./REFERENCE.md). Keep this checklist as a short reminder:
 
-**Identity:** aesthetic named in 2–3 words · color/type/space/motion tell one story · one memorable detail
+- Pick a named aesthetic (2–3 words) and commit to it.
+- Use tokenized colors/spacing, respect WCAG contrast, and prefer semantic HTML.
+- Respect `prefers-reduced-motion` and keep critical animations under 500ms.
 
-**Typography:** display+body pair distinct · `clamp()` fluid scale · heading lh ~1.1–1.2 / body lh ~1.5–1.7 · letter-spacing on uppercase/small
+**Every design must have one unforgettable detail.** No two designs should look alike.
 
-**Color:** CSS vars only · dominant+accent hierarchy · WCAG AA (4.5:1 body, 3:1 large) · dark/light both intentional
+## Typography Pairings
 
-**Layout:** spacing tokens throughout · one grid-breaking element · responsive at mobile/tablet/desktop
+Recommended typography pairings and an extended catalogue are in [REFERENCE.md](./REFERENCE.md). For production, always include a metric-preserving fallback chain (e.g., `'Fraunces', 'Georgia', serif`).
 
-**Motion:** coordinated entrance sequence · hover/focus on all interactives · custom easing curves · `prefers-reduced-motion` fallback
+> Load the **project-consistency** skill for the full Foundation Phase pattern and prompt templates.
 
-**Production:** no hardcoded widths · `alt`/`aria-hidden` on images · visible focus indicators · no scroll-animation layout thrashing
+### Quality Checklist (quick)
 
-> Load the **project-consistency** skill for the full Foundation Phase pattern and prompt templates.
+- **Contrast:** Text ≥4.5:1 body, ≥3:1 large.
+- **Tokens:** All spacing/colors in `:root` tokens; avoid ad-hoc values.
+- **Responsiveness:** Layouts break at defined tokens; no overflow at mobile sizes.
+- **Motion:** `prefers-reduced-motion` respected; key animations <500ms.
+- **Accessibility:** Keyboard focus states visible; semantic HTML used.

package/src/orchestrator/skills/git-workflow/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: git-workflow
-description: "Git branching, PR workflow, delivery requirements, discovered issues policy, and task tracking conventions. Load when committing, pushing, or opening PRs."
+description: "Defines branch naming conventions, PR template requirements, commit message format, discovered-issues escalation policy, and task tracking conventions. Load when committing, pushing, or opening PRs."
 ---
 
 # Git Workflow & Delivery
@@ -22,7 +22,18 @@ description: "Git branching, PR workflow, delivery requirements, discovered issu
 1. Branch `<type>/<ticket-id>-<slug>` from `main`
 2. Atomic commits referencing issue ID
 3. Push branch to origin
-4. Open PR (do NOT merge): `GH_PAGER=cat gh pr create --base main --title "TAS-XX: …" --body "Resolves TAS-XX"`
+4. Open PR (do NOT merge) — write the body to a temp file first, then use `--body-file`:
+   ```sh
+   # Write PR body to a temp file to avoid shell escaping issues
+   cat > /tmp/pr-body.md << 'EOF'
+   Resolves TAS-XX
+   
+   ## Changes
+   - ...
+   EOF
+   GH_PAGER=cat gh pr create --base main --title "TAS-XX: Short description" --body-file /tmp/pr-body.md
+   ```
+   **Never use inline `--body` with markdown/backticks/special chars** — it breaks in zsh heredocs and quoted strings.
 5. Update issue with PR URL
 
 ## Discovered Issues Policy

package/src/orchestrator/skills/memory-merger/REFERENCE.md

@@ -0,0 +1,20 @@
+> Parent: [SKILL.md](./SKILL.md)
+
+## Memory Merger Reference
+
+### Worked Example: LES-042 — MCP Tool Timeout
+
+**Lesson:** `LES-042: MCP tool timeout causes silent failures — always set explicit timeout and check return value` (cited 4×, severity high, 90 days old)
+
+**Draft:**
+```
+Lesson: LES-042 — MCP tool timeout
+Target: .github/skills/orchestration-protocols/SKILL.md
+Section: Error Recovery Playbook
+Edit: Add row: | **MCP timeout** | Tool returns null/undefined after delay | Set explicit timeout (30s); check return value; retry once; fall back to CLI; log to DLQ | <!-- Merged from LES-042 -->
+```
+
+**After merge in target file**, archive in LESSONS-LEARNED.md:
+```markdown
+### LES-042: MCP tool timeout → Merged to `.github/skills/orchestration-protocols/SKILL.md` on 2026-03-15
+```

package/src/orchestrator/skills/memory-merger/SKILL.md

@@ -1,49 +1,34 @@
 ---
 name: memory-merger
-description: "Protocol for graduating mature lessons from LESSONS-LEARNED.md into permanent instruction and skill files. Closes the self-improvement loop by codifying validated knowledge at the source level."
+description: "Reviews mature LESSONS-LEARNED.md entries, rewrites them as permanent rules in skill/instruction files, and archives graduated lessons. Use when graduating lessons into skills, promoting validated lessons, updating skills from past learnings, archiving mature lessons, codifying repeated patterns, or cleaning up a crowded LESSONS-LEARNED.md."
 ---
 
 # Memory Merger
 
-Promotes validated lessons from `.opencastle/LESSONS-LEARNED.md` into instruction/skill files where they have permanent impact.
 
-## When to Run
+## Run Criteria
 
-| Trigger | Threshold |
-|---------|-----------|
-| File size | >50 entries |
-| Citation count | Cited 3+ times |
-| Age | >60 days old |
+Combined signals to identify merge candidates.
+
+| Criterion | Signal / Threshold |
+|-----------|--------------------|
+| File size | LESSONS-LEARNED.md > 50 entries |
+| Citation count | Cited 3+ times across sessions |
+| Age | >60 days and still relevant |
 | Category cluster | 5+ lessons in same category |
-| Discretionary | Lessons file feels stale |
+| Severity | Marked `high` or blocking |
+| Discretionary | Curator / maintainer judgement (stale file) |
 
-## Merge Protocol
+## Workflow (numbered)
+
+1. Scan LESSONS-LEARNED.md for candidate entries (frequency, severity, age).
+2. Map each candidate to a target file and section.
+3. Draft the exact edit (concise rule or example).
+4. Apply the edit with an attribution comment.
+5. Archive the migrated lesson in LESSONS-LEARNED.md with a merge note.
+6. Update the index and run validation checks.
 
-### 1 — Scan Candidates
-
-| Criterion | Signal |
-|-----------|--------|
-| Frequency | Cited/re-discovered 3+ times |
-| Severity | Marked `high` |
-| Age | >60 days, still relevant |
-| Concentration | 5+ in same category → extract pattern |
-| Tool-specific | MCP tool, codebase-tool command, or framework pattern |
-
-### 2 — Map to Target File
-
-| Category | Target |
-|----------|--------|
-| `task-management` | skill-matrix `task-management` slot |
-| `mcp-tools` | agent/skill that uses the tool |
-| `codebase-tool` | skill-matrix `codebase-tool` slot |
-| `cms` / `database` | respective skill-matrix slots |
-| `browser-testing` | skill-matrix `e2e-testing` slot |
-| `git-workflow` | `.github/skills/git-workflow/SKILL.md` |
-| `deployment` | `.github/skills/deployment-infrastructure/SKILL.md` |
-| `delegation` | `.github/agents/team-lead.agent.md` or `team-lead-reference` skill |
-| `testing` | `.github/skills/testing-workflow/SKILL.md` |
-| `ui` / `framework` | `framework` slot or `react-development` skill |
-| Cross-cutting | `.github/instructions/general.instructions.md` |
+## Merge Protocol
 
 ### 3 — Draft Edit
 
@@ -73,12 +58,18 @@ Move merged lessons to `## Archived (Merged)` at the bottom of `LESSONS-LEARNED.
 
 Update `## Index by Category` in `LESSONS-LEARNED.md` to mark archived lessons.
 
-## Quality Gates
+### Worked Example
+
+See [REFERENCE.md](./REFERENCE.md) for a full worked merge example (LES-042: MCP tool timeout).
+
+## Quality Gates (validation checkpoints)
 
 - [ ] Merged content reads naturally (not copy-pasted)
-- [ ] No duplicate rules created
-- [ ] Archived lesson references target file
+- [ ] No duplicate rules created in target files or other skills
+- [ ] Archived lesson references target file and date
 - [ ] Core insight preserved — no loss of nuance
+- [ ] Target file still passes lint/markdown checks (if applicable)
+- [ ] A quick smoke verification (search for relevant keyword) confirms merge applied
 
 ## Anti-Patterns
 

package/src/orchestrator/skills/observability-logging/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: observability-logging
-description: "Session logging, delegation records, review/panel/dispute NDJSON logging, pre-response checklists. Load before responding to verify all logs are written."
+description: "Writes session logs, records delegation decisions, and tracks review/dispute outcomes in NDJSON format. Use when logging session activity, recording audit trails, or running pre-response verification checklists."
 ---
 
 # Observability Logging
@@ -62,21 +62,14 @@ Verify any append: `tail -1 .opencastle/logs/events.ndjson`
 **⛔ STOP.** Verify before responding — fix any missing log NOW.
 
 - [ ] **Lessons read** — `.opencastle/LESSONS-LEARNED.md` read at session start
-- [ ] **Lessons captured** — new lesson added via **self-improvement** if any retry occurred
-- [ ] **Discovered issues tracked** — pre-existing bugs added to `KNOWN-ISSUES.md` or tracker
-- [ ] **Lint/type/test pass** — no new errors after code changes
 - [ ] **Session logged** — `events.ndjson` has a `session` record (ALWAYS)
-- [ ] **Delegations logged** — `delegation` record per delegation (Team Lead)
-- [ ] **Reviews logged** — `review` record per fast review (if any)
-- [ ] **Panels logged** — `panel` record per panel vote (if any)
-- [ ] **Disputes logged** — `dispute` record per dispute (if any)
+- [ ] **Delegations logged** — `delegation` record per delegation (Team Lead) (if applicable)
+- [ ] **Reviews logged** — `review` record per fast review (if applicable)
 
 ## Universal Agent Rules
 
-1. **Never delegate** — complete own work; document cross-domain needs in output contract.
-2. **Follow Discovered Issues Policy** — See [discovered-issues-policy](../../snippets/discovered-issues-policy.md).
-3. **Read and update lessons** — Read `.opencastle/LESSONS-LEARNED.md` before starting; add lessons after retries via **self-improvement** skill.
-4. **Log every session** — See [logging-mandatory](../../snippets/logging-mandatory.md).
+1. **Read and update lessons** — Read `.opencastle/LESSONS-LEARNED.md` before starting; add lessons after retries via **self-improvement** skill.
+2. **Log every session** — See [logging-mandatory](../../snippets/logging-mandatory.md).  
 
 ## Base Output Contract