docs: Add design pattern examples and update submodule

Add Design Pattern Documentation:
- Add CopyFirstMigration.md - Documents the copy-first migration principle
  used in the TestDrive-JSUI capability migration
- Add DontRepeatYourself.md - Documents the DRY principle
- Add DesignPrincipleSchema.json - JSON schema for design pattern documentation

Update Submodule:
- Update testdrive-jsui submodule pointer to include Phase 4 documentation
  (migration completion with legacy file cleanup)

Context:
These design pattern examples document the principles applied during the
successful TestDrive-JSUI migration, which serves as a reference implementation
of the copy-first migration pattern.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

examples/design-patterns/CopyFirstMigration.md

@@ -0,0 +1,158 @@
+# Design Principle: Copy First Migration
+
+## Meta
+- **Name:** Copy First Migration
+- **ShortName:** CopyFirst
+- **Version:** 0.1
+- **Status:** Draft
+- **Tags:** refactoring, migration, safety, testing, legacy
+- **RelatedPrinciples:** Don’t Repeat Yourself, Safe Refactoring, Test Pyramid, Capability-Based Testing
+
+---
+
+## Intent
+Enable safe refactoring and structural migration of codebases by preserving
+existing, working functionality until the new implementation is fully verified.
+
+This principle prioritizes **reversibility, confidence, and continuity** over
+speed or elegance.
+
+---
+
+## CoreStatement
+Never move code directly; always copy first and delete only after verified
+behavioral equivalence is established.
+
+---
+
+## Scope
+
+### InScope
+- Large-scale refactors or directory restructurings
+- Technology or language migrations (e.g. JS → new JS layout, JS → Python integration)
+- Legacy code stabilization
+- Safety-critical or business-critical systems
+- Situations with incomplete test coverage
+
+### OutOfScope
+- Greenfield development
+- Trivial refactors with full and trusted test coverage
+- One-off throwaway scripts
+- Performance-driven rewrites where duplication is unacceptable
+
+---
+
+## InterpretationGuidelines
+
+### What “Copy First” Means
+- The original code remains untouched and functional
+- The new version is treated as **experimental until proven**
+- Deletion is a **final, explicit act**, not an implicit side effect
+
+### Common Misinterpretations
+- “This is inefficient because it duplicates code”  
+  → Duplication is intentional and temporary
+- “Moving files is faster”  
+  → Speed is not the optimization target here
+- “Tests alone are enough”  
+  → Tests are necessary but not sufficient without behavioral comparison
+
+---
+
+## DetectionHeuristics
+
+### Structural Signals
+- Files or modules being relocated across directories or packages
+- Parallel implementations during migration
+- Introduction of a new architectural boundary
+
+### Semantic Signals
+- Code paths that must remain behaviorally identical
+- Business rules with high regression risk
+- Legacy logic that is poorly documented but relied upon
+
+### Change-Cost Signals
+- Rollbacks are expensive or disruptive
+- Failures would impact production or customers
+- Migration spans multiple commits or teams
+
+---
+
+## DiagnosticQuestions
+1. What breaks if this migration is wrong?
+2. Do we have a known-good reference implementation?
+3. Can both old and new code paths run in parallel?
+4. How quickly can we revert if a defect is found?
+5. What is the minimal proof of behavioral equivalence?
+
+---
+
+## RecommendedActions
+
+### Low-Risk Actions
+- Copy files to the new location instead of moving
+- Preserve original imports and entry points
+- Add logging or tracing for comparison
+
+### Medium-Risk Actions
+- Introduce dual-track execution (old + new)
+- Add integration tests targeting both implementations
+- Compare outputs, side effects, and error behavior
+
+### High-Risk Actions
+- Switch production usage to the new implementation
+- Remove old code only after full verification
+- Collapse duplicated paths once confidence is established
+
+---
+
+## AcceptanceCriteria
+- Original code remains functional until final removal
+- New code passes all existing tests
+- New integration tests validate identical behavior
+- Dual-track comparisons show no regressions
+- Deletion of old code is deliberate and reversible up to the final step
+
+---
+
+## AntiPatterns
+- Moving files directly without a fallback
+- Refactoring and migration in a single irreversible step
+- Deleting “unused” code before equivalence is proven
+- Assuming test parity guarantees behavioral parity
+- Big-bang migrations without rollback paths
+
+---
+
+## Tradeoffs
+Applying Copy First Migration intentionally:
+- Introduces temporary duplication
+- Increases short-term codebase size
+- Slows perceived progress
+
+These costs are justified by dramatically reduced risk and higher confidence
+during complex migrations.
+
+---
+
+## AgentUsage
+
+### When to Apply This Lens
+- During directory, module, or architecture migrations
+- When refactoring legacy or poorly understood code
+- When safety and uptime matter more than speed
+- When rollback must remain possible at all times
+
+### When to Suspend This Lens
+- In greenfield projects
+- When full test coverage and confidence already exist
+- For trivial mechanical refactors
+
+### Expected Agent Output
+- Identification of migration boundaries
+- Copy-first migration plan with explicit stages
+- Test strategy (unit, integration, dual-track)
+- Rollback points and deletion criteria
+- Clear signal for when old code may be removed
+
+xxx

examples/design-patterns/DesignPrincipleSchema.json

@@ -0,0 +1,135 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "title": "Schema for DesignPrinciples",
+  "description": "JSON schema describing the markdown structure of OperationalKnowledge DesignPrinciples",
+  "properties": {
+    "headings": {
+      "type": "object",
+      "description": "Document heading structure",
+      "properties": {
+        "level_1": {
+          "type": "array",
+          "description": "Headings at level 1",
+          "items": {
+            "type": "object",
+            "properties": {
+              "content": {
+                "type": "string"
+              },
+              "level": {
+                "type": "integer"
+              },
+              "position": {
+                "type": "integer"
+              }
+            },
+            "required": [
+              "content",
+              "level"
+            ]
+          },
+          "minItems": 1,
+          "maxItems": 1
+        },
+        "level_2": {
+          "type": "array",
+          "description": "Headings at level 2",
+          "items": {
+            "type": "object",
+            "properties": {
+              "content": {
+                "type": "string"
+              },
+              "level": {
+                "type": "integer"
+              },
+              "position": {
+                "type": "integer"
+              }
+            },
+            "required": [
+              "content",
+              "level"
+            ]
+          },
+          "minItems": 4,
+          "maxItems": 12
+        },
+        "level_3": {
+          "type": "array",
+          "description": "Headings at level 3",
+          "items": {
+            "type": "object",
+            "properties": {
+              "content": {
+                "type": "string"
+              },
+              "level": {
+                "type": "integer"
+              },
+              "position": {
+                "type": "integer"
+              }
+            },
+            "required": [
+              "content",
+              "level"
+            ]
+          },
+          "minItems": 0,
+          "maxItems": 40
+        }
+      }
+    },
+    "paragraphs": {
+      "type": "array",
+      "description": "Text paragraphs",
+      "minItems": 8,
+      "maxItems": 120
+    },
+    "lists": {
+      "type": "array",
+      "description": "Lists (ordered and unordered)",
+      "minItems": 0,
+      "maxItems": 20
+    },
+    "emphasis": {
+      "type": "array",
+      "description": "Text emphasis (bold, italic)",
+      "minItems": 0,
+      "maxItems": 120
+    },
+    "metadata": {
+      "type": "object",
+      "description": "Document structure metadata",
+      "properties": {
+        "total_elements": {
+          "type": "integer",
+          "const": 115
+        },
+        "structure_types": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "All structural element types found",
+          "const": [
+            "paragraph_close",
+            "heading_close",
+            "hr",
+            "bullet_list_open",
+            "paragraph_open",
+            "heading_open",
+            "ordered_list_open",
+            "ordered_list_close",
+            "inline",
+            "list_item_close",
+            "list_item_open",
+            "bullet_list_close"
+          ]
+        }
+      }
+    }
+  }
+}

examples/design-patterns/DontRepeatYourself.md

@@ -0,0 +1,160 @@
+# Design Principle: Don’t Repeat Yourself (DRY)
+
+## Meta
+- **Name:** Don’t Repeat Yourself
+- **ShortName:** DRY
+- **Version:** 0.1
+- **Status:** Stable
+- **Tags:** maintainability, refactoring, architecture, quality
+- **RelatedPrinciples:** Single Responsibility, YAGNI, Separation of Concerns
+
+---
+
+## Intent
+Reduce maintenance cost and behavioral drift by ensuring that each piece of
+knowledge, rule, or decision logic has a single authoritative representation
+in the codebase.
+
+---
+
+## CoreStatement
+A codebase violates DRY when the same knowledge is expressed in multiple places
+such that a change would require edits in more than one location or risks
+inconsistent behavior.
+
+---
+
+## Scope
+
+### InScope
+- Business rules and decision logic
+- Algorithms and validation logic
+- Data schemas, DTOs, and field definitions
+- Configuration values and feature flags
+- Repeated workflows or orchestration logic
+- Test setup and invariant test scenarios
+
+### OutOfScope
+- Superficial textual similarity without shared meaning
+- Intentional duplication for isolation or clarity
+- Early-stage exploratory code where abstractions are not yet clear
+- Performance-driven duplication with explicit justification
+
+---
+
+## InterpretationGuidelines
+
+### What “Repeat” Means
+DRY is about **duplication of knowledge**, not duplication of text.
+
+Examples of knowledge duplication:
+- The same validation rule implemented in multiple services
+- Identical conditional logic controlling the same behavior
+- The same data structure defined independently in multiple modules
+
+### Common Misinterpretations
+- “Any repeated code is bad” (false)
+- “DRY means maximum abstraction” (false)
+- “Utility modules automatically improve DRY” (often false)
+
+---
+
+## DetectionHeuristics
+
+### Structural Signals
+- Functions with highly similar bodies and signatures
+- Repeated constants, strings, regexes, or SQL fragments
+- Parallel modules with mirrored internal structure
+
+### Semantic Signals
+- Identical error messages or validation rules in different layers
+- Repeated mapping logic between the same concepts
+- Copy-paste variations differing only in naming
+
+### Change-Cost Signals
+- A requirement change touches multiple files for the same reason
+- Fixes applied in one location but missing in others
+- Tests failing inconsistently after partial updates
+
+---
+
+## DiagnosticQuestions
+1. Is this duplication representing the same rule or policy?
+2. If this rule changes, how many places must be updated?
+3. Is the duplicated logic stable or likely to evolve?
+4. Are the differences intentional or accidental?
+5. Where is the natural “source of truth” for this knowledge?
+6. Would abstraction reduce or increase cognitive load?
+
+---
+
+## RecommendedActions
+
+### Low-Risk Refactors
+- Extract constants or configuration values
+- Centralize literals and error messages
+- Introduce shared test fixtures or helpers
+
+### Medium-Risk Refactors
+- Extract pure helper functions
+- Introduce shared domain services or modules
+- Unify schema/type definitions
+
+### High-Risk Refactors
+- Introduce strategy/template patterns
+- Merge parallel subsystems
+- Redesign domain boundaries to align ownership of rules
+
+---
+
+## AcceptanceCriteria
+- Each rule or behavior has a single authoritative implementation
+- Required changes affect fewer locations than before
+- Naming reflects domain meaning, not technical convenience
+- Tests pass without behavior regression
+- Coupling does not increase unintentionally
+
+---
+
+## AntiPatterns
+- “God” utility modules with unrelated helpers
+- Over-generalized abstractions with many parameters
+- Shared code across domains that should evolve independently
+- Premature abstraction of coincidental similarities
+- Hiding meaningful differences behind generic interfaces
+
+---
+
+## Tradeoffs
+Applying DRY may:
+- Increase indirection
+- Reduce local readability
+- Introduce coupling between modules
+
+These costs are acceptable only when outweighed by reduced change cost
+and increased behavioral consistency.
+
+---
+
+## AgentUsage
+
+### When to Apply This Lens
+- During refactoring or maintenance work
+- When change requests repeatedly touch similar code
+- When bugs recur due to partial updates
+- During architectural consolidation
+
+### When to Suspend This Lens
+- During early exploration or prototyping
+- When future variability is unclear
+- When isolation is more valuable than reuse
+
+### Expected Agent Output
+- Identified DRY violations with locations
+- Rationale for why duplication matters
+- Volatility assessment (stable vs evolving)
+- Recommended refactor type and target
+- Risk notes and minimal patch sequence
+
+xxx
+