intentdna 1.7.5 → 1.8.0

package/dist/templates/safe-refactoring.dna.yaml

@@ -6,6 +6,24 @@
 version: "0.1.0"
 id: template_safe_refactoring
 name: Safe Refactoring
+purpose: Refactor code in small behavior-preserving steps after characterization and verification are in place.
+maturity: reviewed
+fit:
+  - Refactors where external behavior must stay stable.
+  - Cleanup work that needs tests before structural edits.
+not_for:
+  - Feature changes mixed into refactor commits.
+  - Untested broad rewrites.
+inputs:
+  - refactor task scope
+  - characterization tests
+  - verification command
+outputs:
+  - scoped refactor commits
+  - regression evidence
+  - reviewable behavior preservation notes
+lineage:
+  source: TDD refactor phase and verification-before-completion workflow shape
 type: project
 namespace: sr
 
@@ -64,3 +82,306 @@ genes:
         target: mixed_refactor_and_feature
 
 contexts: {}
+
+variables:
+  task_id:
+    description: Refactor task identifier used for evidence artifacts
+    default: refactor-task
+  test_command:
+    description: Command that proves behavior has not regressed
+    default: npm test
+  target_scope:
+    description: Code paths allowed for the rewrite step
+    default: src/**
+
+roles:
+  intent_mapper:
+    description: Locks the refactor intent, success criteria, and non-goals before code changes.
+    tool_permissions:
+      allow: [Read, Grep, Glob, Write]
+      deny: [Edit, Bash, NotebookEdit]
+    scope:
+      read: ["**/*"]
+      write: [".dna/refactor/**"]
+    instructions:
+      - Capture the exact refactor intent and explicit non-goals.
+      - Define observable behavior that must remain equivalent.
+      - Do not edit source code or tests.
+
+  boundary_guard:
+    description: Freezes the allowed read/write boundary and records risk constraints.
+    tool_permissions:
+      allow: [Read, Grep, Glob, Write]
+      deny: [Edit, Bash, NotebookEdit]
+    scope:
+      read: ["**/*"]
+      write: [".dna/refactor/**"]
+    instructions:
+      - Record allowed write paths and forbidden areas.
+      - Treat broad or unclear scope as a blocker.
+      - Do not edit implementation files.
+
+  baseline_tester:
+    description: Characterizes current behavior before rewrite.
+    tool_permissions:
+      allow: [Read, Grep, Glob, Bash, Write]
+      deny: [Edit, NotebookEdit]
+    scope:
+      read: ["**/*"]
+      write: [".dna/refactor/**"]
+    instructions:
+      - Run the declared test command before rewrite.
+      - Record baseline output and known failures.
+      - Do not change code to make the baseline pass.
+
+  rewrite_surgeon:
+    description: Performs behavior-preserving rewrite inside the frozen boundary.
+    tool_permissions:
+      allow: [Read, Edit, Write, Grep, Glob, Bash]
+    scope:
+      read: ["**/*"]
+      write: ["{{target_scope}}"]
+    instructions:
+      - Apply the smallest behavior-preserving rewrite that satisfies the intent.
+      - Stay inside the frozen boundary and do not expand scope silently.
+      - Run targeted checks after each material change.
+      - Revert or escalate if behavior may have changed.
+
+  equivalence_verifier:
+    description: Proves the rewrite is logically equivalent to baseline behavior.
+    tool_permissions:
+      allow: [Read, Grep, Glob, Bash, Write]
+      deny: [Edit, NotebookEdit]
+    scope:
+      read: ["**/*"]
+      write: [".dna/refactor/**"]
+    instructions:
+      - Compare baseline and post-rewrite behavior.
+      - Run the declared test command and record output.
+      - Mark any unproven equivalence as a blocker.
+
+  refactor_reviewer:
+    description: Reviews the diff and packages evidence for handoff.
+    tool_permissions:
+      allow: [Read, Grep, Glob, Bash, Write]
+      deny: [Edit, NotebookEdit]
+    scope:
+      read: ["**/*"]
+      write: [".dna/refactor/**"]
+    instructions:
+      - Review the final diff against intent, boundary, and equivalence evidence.
+      - Produce a compact evidence package with verdict and residual risks.
+      - Do not approve if tests, baseline, or boundary evidence is missing.
+
+workflows:
+  refactor-equivalence:
+    name: Refactor With Equivalence
+    description: "Intent-locked refactor workflow: freeze scope, characterize baseline, rewrite, prove equivalence, and package evidence."
+    consumes:
+      - type: state
+        name: refactor_request
+        required: true
+        description: User refactor request and target behavior.
+    produces:
+      - type: file
+        path: ".dna/refactor/{{task_id}}/evidence.md"
+        description: Final evidence package for the refactor.
+    default_isolation: worktree
+    retry_policy:
+      max_retries: 1
+      retry_from: equivalence_verify
+      backoff: none
+    steps:
+      - id: intent_lock
+        role: intent_mapper
+        description: Lock intent, non-goals, and equivalence criteria.
+        enforce:
+          read_only: true
+          additional_write_paths: [".dna/refactor/**"]
+        handoff:
+          produces:
+            - type: file
+              path: ".dna/refactor/{{task_id}}/intent.md"
+              description: Locked intent, non-goals, and equivalence criteria.
+        completion:
+          - file_contains: { path: ".dna/refactor/{{task_id}}/intent.md", pattern: "Equivalence criteria" }
+        checkpoints:
+          - assert: clean_working_tree
+            action: warn
+            message: "Record any pre-existing dirty state before refactor."
+        prompt: |
+          Lock the refactor intent before any implementation work.
+          Write .dna/refactor/{{task_id}}/intent.md with:
+          - Refactor goal
+          - Explicit non-goals
+          - Equivalence criteria
+          - Allowed target scope: {{target_scope}}
+
+      - id: boundary_freeze
+        role: boundary_guard
+        depends_on: [intent_lock]
+        description: Freeze allowed scope, tool policy, and risky boundaries.
+        enforce:
+          read_only: true
+          additional_write_paths: [".dna/refactor/**"]
+        handoff:
+          consumes:
+            - type: file
+              path: ".dna/refactor/{{task_id}}/intent.md"
+              from: intent_lock
+              description: Locked intent.
+          produces:
+            - type: file
+              path: ".dna/refactor/{{task_id}}/boundary.md"
+              description: Frozen read/write/action boundary.
+        completion:
+          - file_contains: { path: ".dna/refactor/{{task_id}}/boundary.md", pattern: "Allowed writes" }
+        prompt: |
+          Freeze the refactor boundary. Write .dna/refactor/{{task_id}}/boundary.md with:
+          - Allowed writes
+          - Explicit forbidden areas
+          - Required checks
+          - Escalation triggers
+
+      - id: baseline_characterization
+        role: baseline_tester
+        depends_on: [boundary_freeze]
+        description: Capture baseline behavior before rewrite.
+        handoff:
+          consumes:
+            - type: file
+              path: ".dna/refactor/{{task_id}}/boundary.md"
+              from: boundary_freeze
+              description: Frozen boundary.
+          produces:
+            - type: test_result
+              path: ".dna/refactor/{{task_id}}/baseline.log"
+              description: Baseline test output before rewrite.
+        completion:
+          - command_success: "{{test_command}}"
+          - file_not_empty: ".dna/refactor/{{task_id}}/baseline.log"
+        checkpoints:
+          - assert: no_test_regression
+            command: "{{test_command}}"
+            message: "Baseline command must run before rewrite."
+        prompt: |
+          Capture baseline behavior before code edits.
+          Run: {{test_command}}
+          Save the output or a concise transcript to .dna/refactor/{{task_id}}/baseline.log.
+          If baseline already fails, record known failures and stop for review.
+
+      - id: rewrite
+        role: rewrite_surgeon
+        depends_on: [baseline_characterization]
+        description: Perform the behavior-preserving rewrite inside the frozen boundary.
+        isolation: worktree
+        enforce:
+          additional_write_paths: ["{{target_scope}}"]
+        handoff:
+          consumes:
+            - type: file
+              path: ".dna/refactor/{{task_id}}/intent.md"
+              from: intent_lock
+              description: Locked intent.
+            - type: file
+              path: ".dna/refactor/{{task_id}}/boundary.md"
+              from: boundary_freeze
+              description: Frozen boundary.
+            - type: test_result
+              path: ".dna/refactor/{{task_id}}/baseline.log"
+              from: baseline_characterization
+              description: Baseline behavior output.
+          produces:
+            - type: summary
+              name: rewrite_summary
+              description: Summary of behavior-preserving changes.
+        checkpoints:
+          - assert: no_test_regression
+            command: "{{test_command}}"
+            message: "Rewrite must keep the declared test command green."
+        prompt: |
+          Perform the rewrite inside {{target_scope}} only.
+          Preserve behavior exactly according to .dna/refactor/{{task_id}}/intent.md.
+          Keep changes small. Run {{test_command}} after material changes.
+          Produce a concise rewrite summary for the verifier.
+
+      - id: equivalence_verify
+        role: equivalence_verifier
+        depends_on: [rewrite]
+        description: Prove rewritten behavior is equivalent to baseline.
+        handoff:
+          consumes:
+            - type: test_result
+              path: ".dna/refactor/{{task_id}}/baseline.log"
+              from: baseline_characterization
+              description: Baseline test output.
+            - type: summary
+              name: rewrite_summary
+              from: rewrite
+              description: Rewrite summary.
+          produces:
+            - type: test_result
+              path: ".dna/refactor/{{task_id}}/equivalence.log"
+              description: Post-rewrite equivalence output.
+            - type: file
+              path: ".dna/refactor/{{task_id}}/equivalence.md"
+              description: Equivalence verdict and comparison notes.
+        completion:
+          - command_success: "{{test_command}}"
+          - file_contains: { path: ".dna/refactor/{{task_id}}/equivalence.md", pattern: "Equivalent: yes" }
+        checkpoints:
+          - assert: no_test_regression
+            command: "{{test_command}}"
+            message: "Equivalence validation must pass before review."
+        prompt: |
+          Prove equivalence after the rewrite.
+          Run: {{test_command}}
+          Save output to .dna/refactor/{{task_id}}/equivalence.log.
+          Write .dna/refactor/{{task_id}}/equivalence.md with:
+          - Equivalent: yes/no
+          - Baseline comparison
+          - Any unverified behavior or residual risk
+
+      - id: review
+        role: refactor_reviewer
+        depends_on: [equivalence_verify]
+        description: Review final diff and evidence before handoff.
+        enforce:
+          read_only: true
+          additional_write_paths: [".dna/refactor/**"]
+        handoff:
+          consumes:
+            - type: file
+              path: ".dna/refactor/{{task_id}}/intent.md"
+              from: intent_lock
+              description: Locked intent.
+            - type: file
+              path: ".dna/refactor/{{task_id}}/boundary.md"
+              from: boundary_freeze
+              description: Frozen boundary.
+            - type: test_result
+              path: ".dna/refactor/{{task_id}}/equivalence.log"
+              from: equivalence_verify
+              description: Equivalence test output.
+            - type: file
+              path: ".dna/refactor/{{task_id}}/equivalence.md"
+              from: equivalence_verify
+              description: Equivalence verdict.
+          produces:
+            - type: file
+              path: ".dna/refactor/{{task_id}}/evidence.md"
+              description: Final evidence package.
+        completion:
+          - file_contains: { path: ".dna/refactor/{{task_id}}/evidence.md", pattern: "Verdict: APPROVE" }
+        checkpoints:
+          - assert: clean_working_tree
+            action: warn
+            message: "Record final dirty state before handoff."
+        prompt: |
+          Review the final diff and evidence.
+          Write .dna/refactor/{{task_id}}/evidence.md with:
+          - Intent summary
+          - Boundary summary
+          - Test/equivalence evidence
+          - RuntimeDecisionEvent or diagnostic evidence refs when available
+          - Verdict: APPROVE or REQUEST_CHANGES

package/dist/templates/secure-dev.dna.yaml

@@ -5,6 +5,25 @@
 version: "0.1.0"
 id: template_secure_dev
 name: Secure Development Baseline
+purpose: Provide a security-first development baseline with code quality, safe operations, review, implementation, and hotfix boundaries.
+maturity: draft
+fit:
+  - Development teams needing a general security and quality baseline before richer workflows exist.
+  - Work where destructive operations and unsafe changes must be constrained.
+not_for:
+  - Replacing formal security review, threat modeling, or incident response.
+  - Granting broad production authority or bypassing human approval.
+inputs:
+  - development task scope
+  - security and operational constraints
+  - review or hotfix context
+outputs:
+  - security and quality guardrails
+  - review or implementation role boundaries
+  - safe-operation reminders
+lineage:
+  source: built-in secure development baseline template
+  reference: src/templates/secure-dev.dna.yaml
 type: project
 namespace: sd
 

package/dist/templates/subagent-parallel.dna.yaml

@@ -6,6 +6,25 @@
 version: "0.1.0"
 id: template_subagent_parallel
 name: Subagent Parallel Development
+purpose: Split large work into isolated subagent lanes with two-phase review before integration.
+maturity: reviewed
+fit:
+  - Large tasks with independent subtasks and clear write-scope boundaries.
+  - Parallel implementation where each lane needs spec compliance and code quality review.
+not_for:
+  - Shared-file work without a conflict plan.
+  - Letting parallel workers change architecture or global scope independently.
+inputs:
+  - task decomposition
+  - lane ownership and write scopes
+  - per-lane acceptance criteria
+outputs:
+  - subtask implementation outputs
+  - two-phase review evidence
+  - integrated result plan
+lineage:
+  source: subagent-driven development and parallel-agent workflow shape
+  reference: docs/archive/2026H1/references/branch-consolidation-handoff-20260709.md
 type: project
 namespace: sap
 

package/dist/templates/systematic-debugging.dna.yaml

@@ -5,6 +5,25 @@
 version: "0.1.0"
 id: template_systematic_debugging
 name: Systematic Debugging
+purpose: Debug through hypotheses, evidence, root-cause isolation, and regression prevention instead of trial-and-error fixes.
+maturity: reviewed
+fit:
+  - Defects where the cause is unknown or multiple causes are plausible.
+  - Teams needing a repeatable debugging discipline before code changes.
+not_for:
+  - Applying guessed fixes without evidence.
+  - Ignoring regression tests after a bug is fixed.
+inputs:
+  - bug report or failing behavior
+  - logs, tests, traces, and reproduction steps
+  - changed code or environment context
+outputs:
+  - ranked hypotheses
+  - verified root cause
+  - fix and regression-prevention evidence
+lineage:
+  source: systematic-debugging workflow pattern
+  reference: src/templates/systematic-debugging.dna.yaml
 type: project
 namespace: dbg
 

package/dist/templates/tdd-strict.dna.yaml

@@ -5,6 +5,25 @@
 version: "0.1.0"
 id: template_tdd_strict
 name: Strict Test-Driven Development
+purpose: Enforce a red-green-refactor loop where meaningful tests are written before implementation and stay green through cleanup.
+maturity: reviewed
+fit:
+  - Feature or bug work where desired behavior can be specified with tests first.
+  - Teams practicing strict TDD with continuous verification.
+not_for:
+  - Exploratory spikes where the behavior contract is intentionally unknown.
+  - Writing tautological or implementation-only tests after the fact.
+inputs:
+  - behavior requirement
+  - test location and framework
+  - verification command
+outputs:
+  - failing test first
+  - minimal passing implementation
+  - refactor evidence with tests green
+lineage:
+  source: strict test-driven development workflow
+  reference: src/templates/tdd-strict.dna.yaml
 type: project
 namespace: tdd
 

package/dist/templates/ui-visual-regression-qa.dna.yaml

@@ -0,0 +1,133 @@
+version: "0.1.0"
+id: template_ui_visual_regression_qa
+name: UI Visual Regression QA
+purpose: Capture desktop and mobile UI evidence so visual regressions, blank states, overflow, and route issues are reviewed before release.
+maturity: reviewed
+fit:
+  - UI routes that need screenshot, DOM, and layout evidence before completion.
+  - Local or deployed product surfaces where visual QA must be separated from runtime enforcement.
+not_for:
+  - Claiming runtime policy authority from browser-rendered evidence.
+  - Accepting desktop-only checks for responsive UI work.
+inputs:
+  - target local or deployed route
+  - desktop and mobile viewport requirements
+  - screenshot, DOM, and layout evidence directory
+outputs:
+  - visual QA evidence bundle
+  - layout and overflow findings
+  - reviewed visual QA verdict
+lineage:
+  source: IntentDNA Online visual QA correction path
+  reference: apps/online
+type: project
+namespace: uvr
+
+cascade:
+  inherits: ["species:default"]
+  priority: 100
+
+variables:
+  target_url:
+    description: "Local or deployed UI route to inspect"
+    default: "$ARGUMENTS"
+  evidence_dir:
+    description: "Screenshot, DOM, and layout evidence output directory"
+    default: ".dna/ui-qa/$ARGUMENTS"
+  verdict_path:
+    description: "Visual QA verdict artifact"
+    default: ".dna/ui-qa/$ARGUMENTS.verdict.json"
+
+evidence:
+  - label: Online route visual QA boundary
+    kind: doc
+    path: docs/archive/2026H1/references/three-products-boundary.md
+    description: Product boundary requiring online UI to remain projection/authoring/community, not runtime truth.
+
+genes:
+  viewport_evidence_required:
+    description: UI QA requires explicit desktop and mobile evidence before pass claims
+    codons:
+      - type: attract
+        target: capture_mobile_and_desktop_screenshots
+      - type: attract
+        target: inspect_dom_and_console
+      - type: repel
+        target: visual_pass_without_screenshot
+      - type: threshold
+        condition: "viewport_evidence_count >= 2"
+        action: block
+
+  layout_stability:
+    description: Detect overlap, clipping, blank states, and horizontal overflow
+    codons:
+      - type: attract
+        target: overflow_check
+      - type: attract
+        target: text_fit_check
+      - type: attract
+        target: nonblank_canvas_or_media_check
+      - type: repel
+        target: screenshot_only_happy_path
+
+  projection_boundary:
+    description: UI evidence is product QA, not runtime enforcement
+    codons:
+      - type: repel
+        target: browser_state_as_policy_truth
+      - type: threshold
+        condition: "ui_claims_runtime_authority == false"
+        action: block
+
+contexts: {}
+
+roles:
+  visual_tester:
+    description: Captures UI evidence and console/layout diagnostics.
+    tool_permissions:
+      allow: [Read, Write, Grep, Glob, Bash]
+      deny: [Edit, NotebookEdit]
+    scope:
+      read: ["**/*"]
+      write: [".dna/ui-qa/**", "output/ui-qa/**"]
+    instructions:
+      - Open {{target_url}} at mobile and desktop viewports.
+      - Capture screenshots, console errors, DOM summaries, and horizontal overflow checks.
+      - Record evidence under {{evidence_dir}}.
+      - Do not change application code or product policy.
+
+  visual_reviewer:
+    description: Reviews UI evidence and writes a pass/fail visual verdict.
+    tool_permissions:
+      allow: [Read, Write, Grep, Glob]
+      deny: [Edit, Bash, NotebookEdit]
+    scope:
+      read: ["**/*", ".dna/ui-qa/**", "output/ui-qa/**"]
+      write: [".dna/ui-qa/**"]
+    instructions:
+      - Inspect all screenshots and diagnostics before judging.
+      - Fail if text overlaps, critical controls are clipped, canvas/media is blank, or public pages expose management-only data.
+      - Distinguish product defects from environment blockers.
+      - Write {{verdict_path}} with PASS, REQUEST_CHANGES, BLOCKED, or INCONCLUSIVE.
+
+workflows:
+  visual-regression-qa:
+    name: UI Visual Regression QA
+    description: Capture viewport evidence, inspect layout, and write a visual QA verdict.
+    steps:
+      - id: collect-ui-evidence
+        role: visual_tester
+        description: Capture screenshots and layout diagnostics for the target route.
+        prompt: |
+          Collect UI QA evidence for {{target_url}}.
+          Use at least one mobile and one desktop viewport.
+          Save screenshots, console output, DOM/layout notes, and overflow results under {{evidence_dir}}.
+          Do not treat browser-local state as runtime truth.
+      - id: review-ui-evidence
+        role: visual_reviewer
+        depends_on: [collect-ui-evidence]
+        description: Review captured evidence and write a visual verdict.
+        prompt: |
+          Review all evidence under {{evidence_dir}}.
+          Check overlap, clipping, blank states, console errors, privacy leaks, and public/management separation.
+          Write {{verdict_path}} with verdict, blockers, evidence paths, and next actions.