diff --git a/capabilities/testdrive-jsui b/capabilities/testdrive-jsui index 796c0470..66cbd5c3 160000 --- a/capabilities/testdrive-jsui +++ b/capabilities/testdrive-jsui @@ -1 +1 @@ -Subproject commit 796c04709a925f128cad52cc2cefbfcb247d48f6 +Subproject commit 66cbd5c3d824ba9a048baac6e7e8cf0471d5c2ea diff --git a/examples/design-patterns/CopyFirstMigration.md b/examples/design-patterns/CopyFirstMigration.md new file mode 100644 index 00000000..d09dab6a --- /dev/null +++ b/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 diff --git a/examples/design-patterns/DesignPrincipleSchema.json b/examples/design-patterns/DesignPrincipleSchema.json new file mode 100644 index 00000000..f3efdfe6 --- /dev/null +++ b/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" + ] + } + } + } + } +} diff --git a/examples/design-patterns/DontRepeatYourself.md b/examples/design-patterns/DontRepeatYourself.md new file mode 100644 index 00000000..70c32dc0 --- /dev/null +++ b/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 +