intentdna 1.4.2 → 1.4.4

package/spec/schema-spec.md

@@ -0,0 +1,676 @@
+# Intent DNA Schema Specification
+
+Version: 0.1.0 | For: LLM code generation | Format: YAML (preferred) or JSON
+
+## Overview
+
+Intent DNA is a declarative policy layer that compiles human intent into agent behavioral constraints. A DNA config file defines **what an agent should prefer, avoid, and enforce** — not how to implement it.
+
+The compiler pipeline: **DNA Config** -> Cascade (merge layers) -> Activate (apply context) -> Compile -> **Constraint IR** -> Adapter output (CLAUDE.md, hooks, SDK config, skills)
+
+---
+
+## Document Structure
+
+```yaml
+# Required top-level fields
+version: "0.1.0"           # Schema version (always "0.1.0")
+id: my_project_dna          # Unique identifier (snake_case recommended)
+name: My Project DNA         # Human-readable name
+type: project                # DNA type (see below)
+
+cascade:                     # Required: inheritance config
+  inherits: ["species:default"]
+  priority: 100
+
+genes: {}                    # Required: intent definitions (can be empty {})
+contexts: {}                 # Required: situational overrides (can be empty {})
+
+# Optional top-level fields
+namespace: myns              # 2-8 lowercase alphanumeric, starts with letter
+roles: {}                    # Agent role definitions
+workflow: {}                 # Single workflow (mutually exclusive with workflows)
+workflows: {}                # Multiple workflows (mutually exclusive with workflow)
+variables: {}                # Template variables for {{var}} substitution
+mcp: {}                      # MCP server definitions
+epigenetic:                  # Experience-driven markers
+  markers: []
+metadata: {}                 # Timestamps and stats
+```
+
+### DNA Types
+
+| Type | Priority | Use Case |
+|------|----------|----------|
+| `species` | 0 | Universal base DNA (rarely authored manually) |
+| `enterprise` | 50 | Organization-wide policies |
+| `project` | 100 | Project-specific rules (most common) |
+| `personal` | 100 | Individual developer preferences |
+| `context` | 150 | Situational overlays (e.g., "migration mode") |
+| `task` | 200 | Task-specific overrides (highest priority) |
+
+Higher priority overrides lower in cascade merge.
+
+---
+
+## Genes
+
+Genes are the atomic unit of intent. Each gene has a description and one or more codons.
+
+```yaml
+genes:
+  quality_over_speed:
+    description: Prefer thoroughness over velocity
+    tags: [quality, core]           # Optional: for categorization
+    codons:
+      - type: attract
+        target: comprehensive_tests
+      - type: attract
+        target: code_review
+      - type: repel
+        target: quick_and_dirty
+      - type: weight
+        a: quality
+        b: speed
+        ratio: 0.7                  # 70% quality, 30% speed
+```
+
+### Codon Types (5 primitives)
+
+#### 1. attract — Prefer/seek a behavior
+```yaml
+- type: attract
+  target: descriptive_variable_names    # What to prefer (free-form string)
+```
+
+#### 2. repel — Avoid a behavior
+```yaml
+- type: repel
+  target: magic_numbers                 # What to avoid
+```
+
+#### 3. threshold — Hard constraint (compiles to gates/hooks)
+```yaml
+- type: threshold
+  condition: "test_regression == false"  # Condition string
+  # Compiles to a pre-execution gate that blocks when condition triggers
+```
+
+#### 4. weight — Trade-off between two values
+```yaml
+- type: weight
+  a: safety                    # First value
+  b: speed                     # Second value
+  ratio: 0.8                   # 0.0-1.0, weight of 'a' (b = 1 - ratio)
+```
+
+#### 5. sense — Detect signal and respond
+```yaml
+- type: sense
+  signal: uncertain_information         # What to detect
+  response: verify_before_share         # How to respond
+```
+
+**Valid responses**: `escalate_to_human`, `verify_before_share`, `compare_alternatives`, `retry_with_more_depth`, `block`, `warn`, `log`, or any custom string.
+
+### Gene Validation Rules
+- `description`: required, non-empty string
+- `codons`: required, at least 1 codon
+- `weight.ratio`: must be 0.0 to 1.0
+- `sense.signal` and `sense.response`: both required
+- `threshold.condition`: required, non-empty string
+
+### Gene Naming Conventions
+Use snake_case descriptive names. Common patterns:
+- Behavioral: `quality_over_speed`, `small_steps`, `test_first`
+- Safety: `data_privacy`, `no_force_push`, `scope_discipline`
+- Process: `review_rigor`, `constructive_feedback`, `behavior_preservation`
+
+---
+
+## Contexts
+
+Contexts are situational overlays that modulate gene expression when active.
+
+```yaml
+contexts:
+  migration:
+    description: Active during codebase migration
+    modifiers:
+      - gene: quality_over_speed
+        action: amplify
+        factor: 1.5               # 1.5x stronger (default: 2.0 for amplify)
+      - gene: scope_discipline
+        action: suppress
+        factor: 0.3               # Reduced to 30% (default: 0.5 for suppress)
+    activate_genes: [extra_caution]       # Turn on specific genes
+    deactivate_genes: [fast_iteration]    # Turn off specific genes
+    threshold_overrides:                  # Add extra thresholds
+      - condition: "migration_test_pass == false"
+        response: block
+```
+
+### Modifier Actions
+
+| Action | Effect | Default Factor |
+|--------|--------|---------------|
+| `amplify` | Increase gene strength | 2.0 |
+| `suppress` | Decrease gene strength | 0.5 |
+| `activate` | Turn gene on (level -> 1.0 if was 0) | — |
+| `deactivate` | Turn gene off (level -> 0) | — |
+
+### Context Validation Rules
+- `modifiers[].gene`: must reference an existing gene name
+- `modifiers[].factor`: must be positive number
+- `activate_genes` / `deactivate_genes`: must reference existing gene names
+- No gene can appear in both `activate_genes` and `deactivate_genes`
+
+---
+
+## Roles
+
+Roles define agent personas in a workflow with permissions and scope constraints.
+
+```yaml
+roles:
+  reviewer:
+    description: Code reviewer — read-only analysis
+    model: sonnet                    # Optional: sonnet | opus | haiku
+    tool_permissions:
+      allow: [Read, Grep, Glob, Bash]
+      deny: [Edit, Write, NotebookEdit]
+    scope:
+      read: ["**/*"]                 # Glob patterns
+      write: []                      # Empty = no write permission
+    instructions:                    # Behavior directives for the agent
+      - Check design compliance against task specification
+      - Verify test coverage for new functionality
+      - Give clear PASS/FAIL verdict with line references
+    post_checks:                     # Commands to run after execution
+      - vitest_run
+      - tsc_no_errors
+    success_criteria:
+      - All critical issues addressed
+    failure_modes:
+      - Rubber-stamp approval without thorough check
+
+  implementer:
+    description: Code implementer — scoped write access
+    tool_permissions:
+      allow: [Read, Edit, Write, Grep, Glob, Bash]
+    scope:
+      read: ["**/*"]
+      write: ["src/**", "test/**"]   # Can only write to src/ and test/
+    output_schema:                   # Structured output requirements
+      required_sections: [Changes, Testing]
+      format: markdown
+    activates_genes: [thoroughness]
+    suppresses_genes: [fast_iteration]
+```
+
+### Tool Names (Claude Code)
+`Read`, `Edit`, `Write`, `Bash`, `Grep`, `Glob`, `NotebookEdit`, `Agent`, `WebFetch`, `WebSearch`
+
+### Scope Patterns
+- `**/*` — all files (default read)
+- `src/**` — everything under src/
+- `test/**/*.test.ts` — test files only
+- `docs/behavior/**` — specific doc directory
+- `*.md` — markdown files at root
+
+### Output Schema (structured form)
+```yaml
+output_schema:
+  path: "docs/reviews/{{task_id}}.md"    # Supports {{var}} substitution
+  required_sections: [Summary, Issues, Verdict]
+  format: markdown                        # markdown | json | csv
+```
+
+### Role Validation Rules
+- `description`: required
+- `tool_permissions.allow` / `deny`: tool names must be non-empty strings
+- `scope.write` / `read`: glob patterns must be non-empty strings
+- `activates_genes` / `suppresses_genes`: must reference existing genes, no overlap
+- `instructions`: array of non-empty strings
+
+---
+
+## Workflows
+
+Workflows define multi-step agent pipelines with dependency ordering, parallel execution, retry, and artifact handoff.
+
+### Single Workflow
+```yaml
+workflow:
+  name: review-cycle
+  description: Implement then review with retry on failure
+  steps:
+    - id: implement
+      role: implementer
+      description: Implement the feature
+      prompt: "Implement task {{task_id}} according to the design document."
+      handoff:
+        produces:
+          - type: git_commit
+            description: "Implementation commit"
+
+    - id: review
+      role: reviewer
+      description: Review the implementation
+      depends_on: [implement]        # Explicit dependency
+      prompt: "Review all changes for task {{task_id}}. Output PASS or FAIL."
+      handoff:
+        consumes:
+          - type: git_commit
+            from: implement
+            description: "Implementation to review"
+        produces:
+          - type: summary
+            description: "Review verdict"
+
+  transitions:
+    - from: review
+      to: implement
+      condition: fail                # Retry on failure
+
+  retry_policy:
+    max_retries: 2
+    retry_from: implement
+```
+
+### Multiple Workflows
+```yaml
+workflows:
+  dev_pipeline:
+    name: dev-pipeline
+    steps: [...]
+
+  release_pipeline:
+    name: release-pipeline
+    steps: [...]
+```
+
+**Note**: `workflow` (singular) and `workflows` (plural) are mutually exclusive.
+
+### Step Fields
+
+```yaml
+- id: step_name           # Required: unique within workflow
+  role: role_name          # Required: must exist in roles section
+  description: What this step does
+  depends_on: [other_step] # Step IDs for ordering (optional)
+  optional: false          # Skip if dependency fails (default: false)
+  run_if: "round == 1"    # Condition: "always" (default) | "round == 1" (first run only)
+  prompt: "Do X for {{task_id}}"  # Agent prompt (supports {{var}})
+  checkpoints:             # Boundary conditions
+    - assert: clean_working_tree
+      message: "Commit changes before proceeding"
+      action: block        # block (default) | warn
+  handoff:                 # Artifact flow
+    consumes: [...]
+    produces: [...]
+```
+
+### Dependency Rules
+- If NO step has `depends_on`, steps run **sequentially** in array order
+- If ANY step has `depends_on`, only explicit dependencies are used
+- Steps with no dependencies (and explicit mode active) run in **parallel**
+- No circular dependencies allowed
+- Steps cannot depend on themselves
+
+### Handoff Artifacts
+
+```yaml
+handoff:
+  produces:
+    - type: file                    # Artifact type
+      path: docs/behavior/home.md   # File path (enables re-run detection)
+      description: Behavior spec    # Required
+
+  consumes:
+    - type: file
+      path: docs/behavior/home.md
+      from: write_doc               # Source step ID
+      description: Behavior spec from write-doc step
+```
+
+**Artifact types**: `file`, `directory`, `test_result`, `git_commit`, `summary`, `state`
+
+**Re-run idempotency**: When a workflow is re-run, the enforcement engine checks if consumed artifacts with `path` fields already exist on disk. If they do, the dependency is considered satisfied even if the producing step hasn't run in the current session.
+
+### Transitions
+
+```yaml
+transitions:
+  - from: review            # Source step
+    to: implement           # Target step
+    condition: fail          # pass | fail | always | error
+```
+
+### Retry Policy
+
+```yaml
+retry_policy:
+  max_retries: 2            # 0 = no retry
+  retry_from: implement     # Step to restart from
+  backoff: none             # none | linear | exponential
+```
+
+Or shorthand: `max_rounds: 3` (equivalent to max_retries: 2)
+
+### Checkpoints (predefined asserts)
+
+| Assert | Description |
+|--------|-------------|
+| `clean_working_tree` | `git status --porcelain` is empty |
+| `no_test_regression` | Test failure count didn't increase |
+| `lint_passing` | Lint command exits 0 |
+| `build_passing` | Build command exits 0 |
+| Custom string | Requires `command` field |
+
+### Workflow Validation Rules
+- `name`: required
+- `steps`: required, at least 1 step
+- `steps[].id`: required, unique within workflow
+- `steps[].role`: required, must exist in `roles`
+- `depends_on`: referenced step IDs must exist, no self-reference
+- `transitions.from` / `to`: must reference existing step IDs
+- `transitions.condition`: must be `pass`, `fail`, `always`, or `error`
+- `retry_policy.retry_from`: must reference existing step ID
+- `max_rounds` >= 1
+
+---
+
+## Cascade (Inheritance)
+
+DNA configs inherit from parent layers using CSS-like cascade.
+
+```yaml
+cascade:
+  inherits: ["species:default"]   # Parent DNA IDs to inherit from
+  priority: 100                    # Higher = more specific, wins on conflict
+```
+
+### Merge Rules
+1. **Genes**: Same-name genes merge codons; thresholds always union (never dropped); non-threshold codons replaced by higher priority
+2. **Contexts**: Higher priority replaces entirely
+3. **Roles**: With namespace, keys get `{ns}_` prefix; same namespace higher priority replaces
+4. **Workflows**: With namespace, names/roles get `{ns}_` prefix
+5. **Epigenetic markers**: All collected (union)
+
+### Threshold Protection
+Threshold codons from lower-priority layers **cannot be removed** by higher-priority layers. This ensures safety invariants propagate up the chain.
+
+---
+
+## Variables
+
+Template variables for `{{var}}` substitution in prompts, descriptions, and output paths.
+
+```yaml
+variables:
+  task_id: "PROJ-123"              # Simple string value
+  target_module:                    # With description
+    description: Module being worked on
+    default: home
+```
+
+All `{{var_name}}` references in the DNA are replaced with the variable value at compile time.
+
+---
+
+## MCP Servers
+
+Define MCP (Model Context Protocol) servers for tool integration.
+
+```yaml
+mcp:
+  project_db:
+    description: Project database access
+    command: npx
+    args: ["-y", "@mcp/sqlite", "--db", "{{db_path}}"]
+    env:
+      DB_PATH: "{{db_path}}"
+    optional: false                 # Default: false
+
+  remote_api:
+    description: Remote API server
+    url: https://mcp.example.com/sse
+    timeout: 30                     # Connection timeout in seconds
+```
+
+**Rules**: Must have either `command` OR `url` (not both). `description` required.
+
+---
+
+## Namespace
+
+Namespaces prevent name collisions when multiple DNA layers define roles/workflows.
+
+```yaml
+namespace: crp    # 2-8 chars, lowercase alphanumeric, starts with letter
+```
+
+**Effect**: Role `reviewer` becomes `crp_reviewer` in cascade. Workflow steps referencing `reviewer` auto-resolve to `crp_reviewer`.
+
+**When to use**: Always use namespace when defining roles + workflows to avoid collisions with other DNA layers.
+
+---
+
+## Epigenetic Markers
+
+Experience-driven modifiers generated by the evolution engine. Rarely authored manually.
+
+```yaml
+epigenetic:
+  markers:
+    - id: marker_1
+      trigger: "test failure after refactoring"
+      timestamp: "2026-03-21T10:00:00Z"
+      decay: 0.95                   # 0.0-1.0, strength over time
+      effects:
+        - gene: test_first
+          action: amplify
+          factor: 1.5
+```
+
+**Decay formula**: `strength = decay ^ (age_days / 30)`. Markers with strength < 0.01 are ignored.
+
+---
+
+## Common Patterns
+
+### Pattern 1: Simple Behavioral Policy (no roles/workflows)
+Best for personal preferences or basic project rules.
+
+```yaml
+version: "0.1.0"
+id: my_preferences
+name: My Preferences
+type: personal
+cascade:
+  inherits: ["species:default"]
+  priority: 100
+genes:
+  quality:
+    description: Prefer quality over speed
+    codons:
+      - type: attract
+        target: comprehensive_testing
+      - type: repel
+        target: shortcuts
+      - type: weight
+        a: correctness
+        b: velocity
+        ratio: 0.7
+contexts: {}
+```
+
+### Pattern 2: Role-Based Pipeline (most common)
+For structured multi-agent workflows.
+
+```yaml
+version: "0.1.0"
+id: my_pipeline
+name: My Pipeline
+type: project
+namespace: mp
+cascade:
+  inherits: ["species:default"]
+  priority: 100
+genes:
+  thoroughness:
+    description: Be thorough in all steps
+    codons:
+      - type: attract
+        target: complete_analysis
+      - type: repel
+        target: skip_steps
+contexts: {}
+roles:
+  planner:
+    description: Plans the approach
+    tool_permissions:
+      allow: [Read, Grep, Glob]
+      deny: [Edit, Write]
+    scope:
+      read: ["**/*"]
+      write: []
+  implementer:
+    description: Implements the plan
+    scope:
+      read: ["**/*"]
+      write: ["src/**", "test/**"]
+  tester:
+    description: Runs and writes tests
+    scope:
+      read: ["**/*"]
+      write: ["test/**"]
+workflow:
+  name: dev-cycle
+  steps:
+    - id: plan
+      role: planner
+      description: Analyze and plan
+      run_if: "round == 1"
+    - id: implement
+      role: implementer
+      description: Write the code
+    - id: test
+      role: tester
+      description: Verify with tests
+  retry_policy:
+    max_retries: 2
+    retry_from: implement
+```
+
+### Pattern 3: Handoff-Driven Pipeline
+For workflows where steps produce artifacts consumed by later steps.
+
+```yaml
+workflow:
+  name: behavior-lock
+  steps:
+    - id: write-doc
+      role: doc_writer
+      description: Write behavior specification
+      handoff:
+        produces:
+          - type: file
+            path: "docs/behavior/{{module}}.md"
+            description: "Behavior specification"
+    - id: write-test
+      role: test_writer
+      depends_on: [write-doc]
+      description: Write tests from spec
+      handoff:
+        consumes:
+          - type: file
+            path: "docs/behavior/{{module}}.md"
+            from: write-doc
+            description: "Behavior spec to test against"
+        produces:
+          - type: directory
+            path: "test/behavior/{{module}}/"
+            description: "Test files"
+    - id: verify
+      role: reviewer
+      depends_on: [write-test]
+      description: Verify tests match spec
+```
+
+### Pattern 4: Safety-First with Thresholds
+For high-stakes environments where certain actions must be blocked.
+
+```yaml
+genes:
+  data_safety:
+    description: Protect sensitive data
+    codons:
+      - type: threshold
+        condition: "personal_data_exposure == false"
+      - type: repel
+        target: logging_pii
+      - type: sense
+        signal: sensitive_data_detected
+        response: escalate_to_human
+  no_destructive_ops:
+    description: Block dangerous operations
+    codons:
+      - type: threshold
+        condition: "force_push == false"
+      - type: repel
+        target: drop_table
+      - type: repel
+        target: rm_rf
+```
+
+---
+
+## Generation Checklist
+
+When generating a DNA config, verify:
+
+1. All required fields present: `version`, `id`, `name`, `type`, `cascade`, `genes`, `contexts`
+2. `cascade.inherits` includes `["species:default"]` unless intentionally standalone
+3. Every gene has `description` and at least 1 codon
+4. `weight.ratio` is between 0.0 and 1.0
+5. Context modifiers reference existing gene names
+6. Role `tool_permissions` use valid Claude Code tool names
+7. Workflow step `role` values match defined role names
+8. `depends_on` references are valid step IDs (no cycles, no self-ref)
+9. Handoff `from` references are valid step IDs
+10. `namespace` is 2-8 lowercase alphanumeric if specified
+11. `workflow` and `workflows` are not both present
+12. Variables referenced as `{{var}}` have matching entries in `variables`
+
+---
+
+## Available Templates
+
+These templates can be used as starting points (install with `dna init --template <name>`):
+
+| Template | Description |
+|----------|-------------|
+| `safe-refactoring` | Step-by-step safe refactoring with test guards |
+| `code-review-pipeline` | Implement-review cycle with retry |
+| `tdd-strict` | Test-driven development enforcement |
+| `full-pipeline` | Plan-implement-test-review 4-step pipeline |
+| `systematic-debugging` | Structured debugging workflow |
+| `verification-loop` | Iterative verification cycle |
+| `secure-dev` | Security-focused development |
+| `enterprise-baseline` | Organization-wide base policies |
+| `frontend-quality` | Frontend-specific quality rules |
+| `api-backend` | API/backend development standards |
+| `mobile-dev` | Mobile development (Flutter/RN) |
+| `documentation-writer` | Documentation generation |
+| `devops-cicd` | CI/CD pipeline management |
+| `monorepo-governance` | Monorepo rules and boundaries |
+| `flutter-behavior-lock` | Flutter behavior specification + test locking |
+| `flutter-rewrite` | Flutter rewrite with behavior preservation |
+| `multi-perspective-review` | Multi-reviewer parallel review |
+| `subagent-parallel` | Parallel subagent execution |
+| `yolo-with-guardrails` | Fast iteration with safety nets |
+| `brainstorming-first` | Exploration before implementation |
+| `branch-finishing` | Branch cleanup and PR prep |
+| `pr-submitter` | PR creation workflow |