intentdna 1.7.5 → 1.8.1

package/dist/templates/flutter-rewrite-new.dna.yaml

@@ -0,0 +1,506 @@
+# flutter-rewrite-new: Flutter rewrite with workflow-infra governance stages
+# Purpose: demonstrate the next template shape after workflow capability foundation.
+# Keeps Flutter-specific migration knowledge, but moves execution into explicit
+# intent, boundary, baseline, diagnosis, rewrite, equivalence, review, evidence gates.
+
+version: "0.1.0"
+id: template_flutter_rewrite_new
+name: Flutter Rewrite New
+purpose: Demonstrate the governed Flutter rewrite workflow shape with explicit intent, boundary, baseline, diagnosis, rewrite, equivalence, review, and evidence gates.
+maturity: draft
+fit:
+  - Designing or reviewing the next generation Flutter rewrite workflow shape.
+  - Migration work that needs explicit stage boundaries before adopting the full dogfood-proven asset.
+not_for:
+  - Replacing the adopted flutter-rewrite asset without review.
+  - Feature redesigns or runtime execution outside local dna sync.
+inputs:
+  - target module or feature slug
+  - v1 source root
+  - v2 Flutter package root
+  - behavior and evidence directories
+outputs:
+  - governed rewrite stage plan
+  - baseline, diagnosis, rewrite, equivalence, and review evidence
+  - adoption review material
+lineage:
+  source: workflow-infra governance template shape
+  reference: src/templates/flutter-rewrite.dna.yaml
+type: project
+namespace: frwn
+
+cascade:
+  inherits: ["species:default"]
+  priority: 100
+
+variables:
+  module:
+    description: "Target module or feature slug"
+    default: "$ARGUMENTS"
+  v1_path:
+    description: "v1 source root used as behavior truth"
+    default: "common/lib"
+  v2_path:
+    description: "v2 Flutter package root"
+    default: "v2/packages"
+  behavior_docs:
+    description: "Behavior contract output directory"
+    default: "docs/behavior"
+  test_path:
+    description: "Behavior test output directory"
+    default: "test/behavior"
+  evidence_dir:
+    description: "Rewrite governance evidence directory"
+    default: ".dna/rewrite/{{module}}"
+  test_command:
+    description: "Command that verifies the target module"
+    default: "flutter test"
+  target_scope:
+    description: "Allowed write scope for the rewrite step"
+    default: "v2/**"
+
+genes:
+  v1_behavior_truth:
+    description: v1 source is the behavior truth for rewrite decisions.
+    codons:
+      - type: attract
+        target: read_v1_source_before_changing
+      - type: attract
+        target: cite_v1_evidence
+      - type: repel
+        target: guess_api_signature
+      - type: threshold
+        condition: "v1_reference_missing == false"
+        action: block
+
+  workflow_gates_before_code:
+    description: Rewrite cannot begin until intent, boundary, and baseline are recorded.
+    codons:
+      - type: attract
+        target: intent_lock
+      - type: attract
+        target: boundary_freeze
+      - type: attract
+        target: baseline_characterization
+      - type: repel
+        target: direct_edit_without_evidence
+      - type: threshold
+        condition: "prewrite_evidence_complete == true"
+        action: block
+
+  equivalence_over_improvement:
+    description: The rewrite preserves v1 behavior rather than improving product behavior.
+    codons:
+      - type: attract
+        target: logic_equivalence_validation
+      - type: attract
+        target: same_inputs_same_outputs
+      - type: repel
+        target: opportunistic_improvement
+      - type: threshold
+        condition: "behavior_delta_approved == true"
+        action: escalate
+
+  small_bounded_rounds:
+    description: Each rewrite round stays small, scoped, and reviewable.
+    codons:
+      - type: attract
+        target: single_module_focus
+      - type: attract
+        target: targeted_tests_per_round
+      - type: repel
+        target: cross_module_rewrite
+      - type: threshold
+        condition: "files_changed_per_round <= 5"
+        action: escalate
+
+  evidence_before_completion:
+    description: Completion requires reviewable evidence, not a prose claim.
+    codons:
+      - type: attract
+        target: evidence_package
+      - type: attract
+        target: runtime_decision_evidence
+      - type: repel
+        target: claim_without_test_output
+
+contexts: {}
+
+context_files:
+  mandatory:
+    - CLAUDE.md
+    - docs/refactoring-workflow-v2.md
+    - v2/docs/PROVIDER_DESIGN.md
+    - v2/docs/memory/flutter_architecture_guide.md
+  per_role:
+    intent_mapper:
+      - "{{behavior_docs}}/{{module}}.md"
+    boundary_guard:
+      - "{{behavior_docs}}/{{module}}.md"
+    baseline_tester:
+      - "{{behavior_docs}}/{{module}}.md"
+    diagnosis_analyst:
+      - "{{evidence_dir}}/intent.md"
+      - "{{evidence_dir}}/boundary.md"
+      - "{{evidence_dir}}/baseline.log"
+    rewrite_surgeon:
+      - "{{evidence_dir}}/intent.md"
+      - "{{evidence_dir}}/boundary.md"
+      - "{{evidence_dir}}/diagnosis.md"
+    equivalence_verifier:
+      - "{{evidence_dir}}/baseline.log"
+      - "{{evidence_dir}}/diagnosis.md"
+    rewrite_reviewer:
+      - "{{evidence_dir}}/intent.md"
+      - "{{evidence_dir}}/boundary.md"
+      - "{{evidence_dir}}/equivalence.md"
+
+verifier_policy:
+  allow_builtin_asserts:
+    - clean_working_tree
+    - no_test_regression
+
+roles:
+  intent_mapper:
+    description: Locks module intent, v1 truth, success criteria, and explicit non-goals.
+    tool_permissions:
+      allow: [Read, Grep, Glob, Write]
+      deny: [Edit, Bash, NotebookEdit]
+    scope:
+      read: ["**/*"]
+      write: ["{{evidence_dir}}/**"]
+    instructions:
+      - "Read the behavior doc and v1 source references before writing intent."
+      - "Define exact module scope, success criteria, and explicit non-goals."
+      - "Do not edit implementation or tests."
+
+  boundary_guard:
+    description: Freezes allowed paths, forbidden areas, tool policy, and escalation triggers.
+    tool_permissions:
+      allow: [Read, Grep, Glob, Write]
+      deny: [Edit, Bash, NotebookEdit]
+    scope:
+      read: ["**/*"]
+      write: ["{{evidence_dir}}/**"]
+    instructions:
+      - "Record allowed write paths and forbidden source areas."
+      - "Treat cross-module rewrites or unbounded scope as blockers."
+      - "Do not edit implementation or tests."
+
+  baseline_tester:
+    description: Captures baseline test behavior before rewrite.
+    tool_permissions:
+      allow: [Read, Grep, Glob, Bash, Write]
+      deny: [Edit, NotebookEdit]
+    scope:
+      read: ["**/*"]
+      write: ["{{evidence_dir}}/**"]
+    instructions:
+      - "Run the declared test command before edits."
+      - "Record pass/fail/skip/hung counts and known failures."
+      - "Do not change code to make baseline pass."
+
+  diagnosis_analyst:
+    description: Classifies gaps using v1 behavior evidence without prescribing implementation.
+    tool_permissions:
+      allow: [Read, Grep, Glob, Write]
+      deny: [Edit, Bash, NotebookEdit]
+    scope:
+      read: ["**/*"]
+      write: ["{{evidence_dir}}/**"]
+    instructions:
+      - "For each failing, skipped, or missing behavior, read test code, v1 source, and v2 current state."
+      - "Classify as BUG, UNIMPLEMENTED, INFRA, TEST_BUG, or REMOVED."
+      - "Write evidence and classification only; do not include fix prescriptions."
+
+  rewrite_surgeon:
+    description: Performs the smallest behavior-preserving v2 rewrite inside the frozen boundary.
+    tool_permissions:
+      allow: [Read, Edit, Write, Grep, Glob, Bash]
+    scope:
+      read: ["**/*"]
+      write: ["{{target_scope}}", "{{test_path}}/**"]
+    instructions:
+      - "Read intent, boundary, approved diagnosis, and v1 source before any edit."
+      - "Apply the smallest behavior-preserving rewrite for this module."
+      - "Use v2 architecture conventions, but do not change product behavior."
+      - "Run targeted tests after material changes."
+      - "Stop if the required change exceeds the frozen boundary."
+
+  equivalence_verifier:
+    description: Compares baseline and post-rewrite behavior and records equivalence evidence.
+    tool_permissions:
+      allow: [Read, Grep, Glob, Bash, Write]
+      deny: [Edit, NotebookEdit]
+    scope:
+      read: ["**/*"]
+      write: ["{{evidence_dir}}/**"]
+    instructions:
+      - "Run the declared test command after rewrite."
+      - "Compare current results with baseline and diagnosis classifications."
+      - "Mark unproven equivalence as a blocker."
+
+  rewrite_reviewer:
+    description: Reviews diff, evidence, and risk before final approval.
+    tool_permissions:
+      allow: [Read, Grep, Glob, Bash, Write]
+      deny: [Edit, NotebookEdit]
+    scope:
+      read: ["**/*"]
+      write: ["{{evidence_dir}}/**"]
+    instructions:
+      - "Review final diff against intent, boundary, diagnosis, and equivalence evidence."
+      - "Reject scope creep, fake tests, unrelated refactors, or unapproved behavior deltas."
+      - "Write final evidence package with verdict and residual risks."
+
+workflows:
+  rewrite-governed:
+    name: Governed Flutter Rewrite
+    description: "Intent-locked Flutter rewrite workflow: freeze scope, capture baseline, diagnose, rewrite, prove equivalence, and package evidence."
+    consumes:
+      - type: state
+        name: module_rewrite_request
+        required: true
+        description: Target module and rewrite goal.
+    produces:
+      - type: file
+        path: "{{evidence_dir}}/evidence.md"
+        description: Final rewrite evidence package.
+    default_isolation: worktree
+    retry_policy:
+      max_retries: 1
+      retry_from: equivalence_verify
+      backoff: none
+    steps:
+      - id: intent_lock
+        role: intent_mapper
+        description: Lock module intent, v1 truth, success criteria, and non-goals.
+        enforce:
+          read_only: true
+          additional_write_paths: ["{{evidence_dir}}/**"]
+        handoff:
+          produces:
+            - type: file
+              path: "{{evidence_dir}}/intent.md"
+              description: Locked module intent and equivalence criteria.
+        completion:
+          - file_contains: { path: "{{evidence_dir}}/intent.md", pattern: "Equivalence criteria" }
+        checkpoints:
+          - assert: clean_working_tree
+            action: warn
+            message: "Record any pre-existing dirty state before rewrite."
+        prompt: |
+          Lock rewrite intent for module {{module}} before implementation.
+          Write {{evidence_dir}}/intent.md with:
+          - Module and exact target scope
+          - v1 truth references under {{v1_path}}
+          - v2 target paths under {{v2_path}}
+          - Explicit non-goals
+          - Equivalence criteria
+          - Allowed behavior deltas, if any
+
+      - id: boundary_freeze
+        role: boundary_guard
+        depends_on: [intent_lock]
+        description: Freeze allowed write paths, forbidden areas, tool policy, and escalation triggers.
+        enforce:
+          read_only: true
+          additional_write_paths: ["{{evidence_dir}}/**"]
+        handoff:
+          consumes:
+            - type: file
+              path: "{{evidence_dir}}/intent.md"
+              from: intent_lock
+              description: Locked intent.
+          produces:
+            - type: file
+              path: "{{evidence_dir}}/boundary.md"
+              description: Frozen rewrite boundary.
+        completion:
+          - file_contains: { path: "{{evidence_dir}}/boundary.md", pattern: "Allowed writes" }
+        prompt: |
+          Freeze rewrite boundary for module {{module}}.
+          Write {{evidence_dir}}/boundary.md with:
+          - Allowed writes: {{target_scope}}, {{test_path}}/**
+          - Forbidden areas
+          - Required context files
+          - Required checks: {{test_command}}
+          - Escalation triggers
+
+      - id: baseline_characterization
+        role: baseline_tester
+        depends_on: [boundary_freeze]
+        description: Capture baseline behavior before rewrite.
+        handoff:
+          consumes:
+            - type: file
+              path: "{{evidence_dir}}/boundary.md"
+              from: boundary_freeze
+              description: Frozen boundary.
+          produces:
+            - type: test_result
+              path: "{{evidence_dir}}/baseline.log"
+              description: Baseline test output before rewrite.
+        completion:
+          - file_not_empty: "{{evidence_dir}}/baseline.log"
+        checkpoints:
+          - assert: no_test_regression
+            command: "{{test_command}}"
+            action: warn
+            message: "Baseline command should run before rewrite; known failures must be recorded."
+        prompt: |
+          Capture baseline behavior for module {{module}} before code edits.
+          Run: {{test_command}}
+          Save output or concise transcript to {{evidence_dir}}/baseline.log.
+          Record known failures, skipped tests, and any command that cannot run.
+
+      - id: diagnosis
+        role: diagnosis_analyst
+        depends_on: [baseline_characterization]
+        description: Classify failures and missing behavior using v1 evidence.
+        enforce:
+          read_only: true
+          additional_write_paths: ["{{evidence_dir}}/**"]
+        handoff:
+          consumes:
+            - type: file
+              path: "{{evidence_dir}}/intent.md"
+              from: intent_lock
+              description: Locked intent.
+            - type: test_result
+              path: "{{evidence_dir}}/baseline.log"
+              from: baseline_characterization
+              description: Baseline output.
+          produces:
+            - type: file
+              path: "{{evidence_dir}}/diagnosis.md"
+              description: Evidence-only diagnosis classification.
+        completion:
+          - file_contains: { path: "{{evidence_dir}}/diagnosis.md", pattern: "Classification" }
+        prompt: |
+          Diagnose module {{module}} without editing code.
+          Write {{evidence_dir}}/diagnosis.md with:
+          - Classification table: BUG / UNIMPLEMENTED / INFRA / TEST_BUG / REMOVED
+          - v1 evidence path and snippet reference for each item
+          - v2 current state path for each item
+          - Baseline evidence reference
+          Do not include implementation order, prescriptions, or surgeon notes.
+
+      - id: rewrite
+        role: rewrite_surgeon
+        depends_on: [diagnosis]
+        description: Rewrite inside the frozen boundary while preserving behavior.
+        isolation: worktree
+        enforce:
+          additional_write_paths: ["{{target_scope}}", "{{test_path}}/**"]
+        handoff:
+          consumes:
+            - type: file
+              path: "{{evidence_dir}}/intent.md"
+              from: intent_lock
+              description: Locked intent.
+            - type: file
+              path: "{{evidence_dir}}/boundary.md"
+              from: boundary_freeze
+              description: Frozen boundary.
+            - type: file
+              path: "{{evidence_dir}}/diagnosis.md"
+              from: diagnosis
+              description: Diagnosis classification.
+          produces:
+            - type: summary
+              name: rewrite_summary
+              description: Summary of behavior-preserving rewrite changes.
+        checkpoints:
+          - assert: no_test_regression
+            command: "{{test_command}}"
+            action: warn
+            message: "Rewrite should keep the declared verification path non-regressing."
+        prompt: |
+          Rewrite module {{module}} inside the frozen boundary only.
+          Before editing, read {{evidence_dir}}/intent.md, boundary.md, diagnosis.md, and the relevant v1 source.
+          Preserve behavior exactly unless the intent file explicitly approves a delta.
+          Use v2 Flutter architecture conventions.
+          Run targeted checks after material changes.
+          Produce a concise rewrite_summary with files changed, diagnosis items addressed, and commands run.
+
+      - id: equivalence_verify
+        role: equivalence_verifier
+        depends_on: [rewrite]
+        description: Prove rewritten behavior is equivalent to v1 and baseline expectations.
+        handoff:
+          consumes:
+            - type: test_result
+              path: "{{evidence_dir}}/baseline.log"
+              from: baseline_characterization
+              description: Baseline output.
+            - type: summary
+              name: rewrite_summary
+              from: rewrite
+              description: Rewrite summary.
+          produces:
+            - type: test_result
+              path: "{{evidence_dir}}/equivalence.log"
+              description: Post-rewrite verification output.
+            - type: file
+              path: "{{evidence_dir}}/equivalence.md"
+              description: Equivalence verdict.
+        completion:
+          - file_contains: { path: "{{evidence_dir}}/equivalence.md", pattern: "Equivalent: yes" }
+        checkpoints:
+          - assert: no_test_regression
+            command: "{{test_command}}"
+            message: "Equivalence validation must pass or record a blocker before review."
+        prompt: |
+          Verify module {{module}} after rewrite.
+          Run: {{test_command}}
+          Save output to {{evidence_dir}}/equivalence.log.
+          Write {{evidence_dir}}/equivalence.md with:
+          - Equivalent: yes/no
+          - Baseline comparison
+          - v1 behavior evidence covered
+          - Remaining unimplemented / skipped / blocked behavior
+          - Any unverified behavior or residual risk
+
+      - id: review
+        role: rewrite_reviewer
+        depends_on: [equivalence_verify]
+        description: Review final diff and package evidence.
+        enforce:
+          read_only: true
+          additional_write_paths: ["{{evidence_dir}}/**"]
+        handoff:
+          consumes:
+            - type: file
+              path: "{{evidence_dir}}/intent.md"
+              from: intent_lock
+              description: Locked intent.
+            - type: file
+              path: "{{evidence_dir}}/boundary.md"
+              from: boundary_freeze
+              description: Frozen boundary.
+            - type: file
+              path: "{{evidence_dir}}/diagnosis.md"
+              from: diagnosis
+              description: Diagnosis.
+            - type: file
+              path: "{{evidence_dir}}/equivalence.md"
+              from: equivalence_verify
+              description: Equivalence verdict.
+          produces:
+            - type: file
+              path: "{{evidence_dir}}/evidence.md"
+              description: Final rewrite evidence package.
+        completion:
+          - file_contains: { path: "{{evidence_dir}}/evidence.md", pattern: "Verdict: APPROVE" }
+        prompt: |
+          Review module {{module}} rewrite evidence.
+          Write {{evidence_dir}}/evidence.md with:
+          - Intent summary
+          - Boundary summary
+          - Diagnosis items addressed
+          - Test/equivalence evidence
+          - RuntimeDecisionEvent or diagnostic evidence refs when available
+          - Unsupported or partial harness capability gaps
+          - Residual risks
+          - Verdict: APPROVE or REQUEST_CHANGES