@ebowwa/logic-spec 1.0.0

package/README.md

@@ -0,0 +1,125 @@
+# Logic Specification Framework
+
+A language-agnostic standard for extracting pure logic from implementations into `logic.yaml`.
+
+## Quick Start
+
+```yaml
+# logic.yaml
+meta:
+  spec_version: "1.0"
+  name: my-module
+  version: "1.0.0"
+
+inputs:
+  - name: data
+    type: string
+
+outputs:
+  - name: result
+    type: string
+
+logic:
+  - id: process
+    type: transform
+    input: data
+    output: result
+    algorithm: |
+      1. Transform input
+      2. Return output
+```
+
+## Why
+
+| Problem | Solution |
+|----------|----------|
+| AI agents drown in implementation details | Clean spec they can parse |
+| Logic locked to one language | Portable across any runtime |
+| Tests scattered in codebase | Assertions in the spec |
+| State machines implicit | Explicit state definitions |
+| Errors handled inconsistently | Declared failure modes |
+
+## Documentation
+
+| File | Purpose |
+|------|---------|
+| [skill.md](skill.md) | Skill definition and workflow |
+| [SPEC.md](SPEC.md) | Full specification |
+| [REFERENCE.md](REFERENCE.md) | Quick reference card |
+| [schema.json](schema.json) | JSON Schema for validation |
+| [examples/](examples/) | Example logic.yaml files |
+
+## Examples
+
+| Example | Demonstrates |
+|---------|--------------|
+| [minimal.yaml](examples/minimal.yaml) | Basic transform |
+| [state-machine.yaml](examples/state-machine.yaml) | State machine |
+| [smart-glass-supervisor.yaml](examples/smart-glass-supervisor.yaml) | Full complex system |
+
+## Core Principles
+
+```
+┌────────────────────────┬─────────────────────────────────────────┐
+│      Principle         │                   Why                   │
+├────────────────────────┼─────────────────────────────────────────┤
+│ I/O at edges           │ Logic blocks are pure                  │
+│ Algorithm as text      │ Human-readable, language-agnostic      │
+│ Types explicit         │ Schema validation                      │
+│ State first-class      │ State machines are explicit            │
+│ Constraints separate   │ Performance not buried in code         │
+│ Failures declared      │ Errors part of the contract            │
+│ Composable blocks      │ Logic chains, not monoliths            │
+│ Versioned              │ Spec can evolve without breaking       │
+│ Observable             │ Metrics/logging hooks built-in         │
+│ Testable               │ Assertions in spec                     │
+└────────────────────────┴─────────────────────────────────────────┘
+```
+
+## Sections
+
+| Section | Required | Purpose |
+|---------|----------|---------|
+| `meta` | ✅ | Identity, version |
+| `inputs` | ✅ | Entry points |
+| `outputs` | ✅ | Exit points |
+| `types` | ❌ | Custom type definitions |
+| `logic` | ✅ | Pure function blocks |
+| `state` | ❌ | State machine |
+| `flows` | ❌ | Logic composition |
+| `failures` | ❌ | Error handling |
+| `constraints` | ❌ | Performance bounds |
+| `dependencies` | ❌ | External services |
+| `observability` | ❌ | Metrics/logging |
+| `tests` | ❌ | Built-in assertions |
+
+## Validate
+
+```bash
+# Using ajv-cli
+bunx ajv-cli validate -s schema.json -d logic.yaml
+
+# Or using yajsv
+bunx yajsv -s schema.json logic.yaml
+```
+
+## Use with AI
+
+### Extract from code:
+```
+"Extract logic.yaml from this authentication module"
+```
+
+### Generate from spec:
+```
+"Generate TypeScript from this logic.yaml"
+```
+
+### Validate spec:
+```
+"Validate this logic.yaml against the spec"
+```
+
+## License
+
+MIT

package/REFERENCE.md

@@ -0,0 +1,147 @@
+# logic.yaml Quick Reference
+
+## Minimal Valid Spec
+
+```yaml
+meta:
+  spec_version: "1.0"
+  name: my-module
+  version: "1.0.0"
+
+inputs:
+  - name: data
+    type: any
+
+outputs:
+  - name: result
+    type: any
+
+logic:
+  - id: process
+    type: transform
+    input: data
+    output: result
+    algorithm: |
+      Transform data to result
+```
+
+## All Sections
+
+| Section | Required | Purpose |
+|---------|----------|---------|
+| `meta` | ✅ | Identity, version |
+| `inputs` | ✅ | Entry points |
+| `outputs` | ✅ | Exit points |
+| `types` | ❌ | Custom type definitions |
+| `logic` | ✅ | Pure function blocks |
+| `state` | ❌ | State machine |
+| `flows` | ❌ | Logic composition |
+| `failures` | ❌ | Error handling |
+| `constraints` | ❌ | Performance bounds |
+| `dependencies` | ❌ | External services |
+| `observability` | ❌ | Metrics/logging |
+| `tests` | ❌ | Built-in assertions |
+
+## Logic Block Types
+
+| Type | Use For |
+|------|---------|
+| `transform` | Data transformation |
+| `validate` | Input validation |
+| `compute` | Calculations |
+| `decision` | Conditionals, branching |
+| `aggregate` | Combine multiple inputs |
+| `inference` | AI/ML model calls |
+| `query` | External data fetch |
+
+## Primitives
+
+```
+string | number | boolean | array | object | null | any
+```
+
+## Test Matchers
+
+| Matcher | Meaning |
+|---------|---------|
+| `value` | Exact match |
+| `">= n"` | Greater/equal |
+| `"<= n"` | Less/equal |
+| `"type:Name"` | Type check |
+| `"/regex/"` | Pattern match |
+| `"!null"` | Not null |
+| `"any"` | Just check presence |
+
+## Recovery Strategies
+
+| Strategy | Action |
+|----------|--------|
+| `retry` | Retry N times |
+| `fallback` | Use alternative |
+| `escalate` | Raise severity |
+| `ignore` | Log and continue |
+
+## State Machine
+
+```yaml
+state:
+  initial: state_a
+  transitions:
+    - from: state_a
+      to: state_b
+      trigger: event_name
+      action: logic_block_id    # optional
+      guard: condition          # optional
+```
+
+## Flows
+
+```yaml
+flows:
+  - name: my_flow
+    steps: [step1, step2, step3]
+    parallel: false      # or true
+    timeout_ms: 5000
+    retry:
+      count: 3
+      backoff: exponential
+      delay_ms: 100
+```
+
+## Constraints
+
+```yaml
+constraints:
+  latency_max_ms: 500
+  throughput_min_rps: 1000
+  memory_limit_mb: 512
+  cpu_limit_percent: 80
+  availability_percent: 99.9
+```
+
+## Observability
+
+```yaml
+observability:
+  metrics:
+    - name: metric_name
+      type: counter | gauge | histogram
+      unit: ms
+      labels: [label1, label2]
+  logs:
+    level: info
+    include: [field1]
+    exclude: [sensitive_field]
+  traces:
+    enabled: true
+    sample_rate: 0.1
+```
+
+## Validation Checklist
+
+- [ ] `meta`, `inputs`, `outputs`, `logic` present
+- [ ] All IDs unique
+- [ ] Type references resolved
+- [ ] Input/output connectivity valid
+- [ ] State transitions reference defined states
+- [ ] Each flow has test coverage