intentdna 1.7.5 → 1.8.1

package/dist/templates/documentation-writer.dna.yaml

@@ -5,6 +5,25 @@
 version: "0.1.0"
 id: template_documentation_writer
 name: Documentation Writer
+purpose: Write technical documentation from code evidence with audience-aware structure and explicit accuracy constraints.
+maturity: draft
+fit:
+  - API docs, user guides, internal technical docs, or migration notes grounded in code.
+  - Documentation tasks where accuracy and scannable structure matter.
+not_for:
+  - Inventing behavior not present in code or verified references.
+  - Publishing docs without human or maintainer review.
+inputs:
+  - documentation request
+  - source code or API references
+  - target audience and format
+outputs:
+  - structured documentation draft
+  - code-grounded accuracy notes
+  - review-ready doc artifact
+lineage:
+  source: built-in technical documentation writer template
+  reference: src/templates/documentation-writer.dna.yaml
 type: project
 namespace: doc
 

package/dist/templates/flutter-behavior-lock.dna.yaml

@@ -6,6 +6,25 @@
 version: "0.1.0"
 id: template_flutter_behavior_lock
 name: Flutter Behavior Lock
+purpose: Capture source behavior as docs and tests before risky Flutter rewrite, refactor, diagnosis, or fix work starts.
+maturity: reviewed
+fit:
+  - Flutter module rewrites where v1 behavior must be preserved before implementation.
+  - Migration work that needs source-backed behavior documents and baseline tests per module.
+not_for:
+  - Editing app source during discovery.
+  - Feature redesigns or behavior changes mixed into migration evidence.
+inputs:
+  - v1 source module path
+  - v2 test and behavior-document destination
+  - target module name or route
+outputs:
+  - behavior document
+  - baseline unit or integration tests
+  - optional device smoke evidence
+lineage:
+  source: Flutter rewrite dogfood behavior-lock workflow
+  reference: /Users/samuel/lawark/lwk_flutter_v2-rewrite/docs/behavior
 type: project
 namespace: fbl
 

package/dist/templates/flutter-refactoring-rescue.dna.yaml

@@ -6,6 +6,25 @@
 version: "0.1.0"
 id: template_flutter_refactoring_rescue
 name: Flutter Refactoring Rescue
+purpose: Rescue an already migrated Flutter project by repairing one broken feature chain at a time using v1 as oracle.
+maturity: reviewed
+fit:
+  - Flutter migrations where framework movement is done but user-visible chains are broken.
+  - Small verified fixes that must preserve existing behavior.
+not_for:
+  - First-pass migration planning.
+  - Broad redesign or multi-feature cleanup work.
+inputs:
+  - broken feature chain
+  - v1 oracle behavior
+  - device or test verification output
+outputs:
+  - scoped fix plan
+  - reviewable change evidence
+  - runtime verification summary
+lineage:
+  source: dogfood extraction
+  reference: safe-refactoring plus verification-loop workflow shape
 type: project
 namespace: frr
 

package/dist/templates/flutter-rewrite-diagnosis-review.dna.yaml

@@ -0,0 +1,210 @@
+# flutter-rewrite-diagnosis-review: reusable diagnosis + reviewer gate extracted from Flutter rewrite dogfood
+# Source: flutter-rewrite diagnosis workflow and module-level progress evidence
+# Purpose: make "classify before editing" a smaller workflow asset users can adopt without the full rewrite loop
+
+version: "0.1.0"
+id: template_flutter_rewrite_diagnosis_review
+name: Flutter Rewrite Diagnosis Review
+purpose: Classify risky Flutter rewrite failures from evidence and require independent diagnosis review before implementation starts.
+maturity: reviewed
+fit:
+  - Rewrite or migration slices where failures must be classified before editing.
+  - Teams that need evidence-only diagnosis and a reviewer verdict before handoff to fixing.
+not_for:
+  - Writing implementation plans inside the diagnosis artifact.
+  - Self-approving diagnosis or skipping evidence review before code changes.
+inputs:
+  - behavior documents
+  - failing tests or runtime evidence
+  - v1 and v2 implementation references
+outputs:
+  - evidence-only diagnosis artifact
+  - independent review verdict
+  - manager-readable implementation route
+lineage:
+  source: Flutter rewrite dogfood diagnosis workflow
+  reference: /Users/samuel/lawark/lwk_flutter_v2-rewrite/.dna/specs
+type: project
+namespace: frdr
+
+cascade:
+  inherits: ["species:default"]
+  priority: 100
+
+variables:
+  behavior_docs:
+    description: "Behavior evidence directory"
+    default: "docs/behavior"
+  diagnosis_path:
+    description: "Diagnosis artifact path"
+    default: ".dna/specs/diagnosis-$ARGUMENTS.md"
+  diagnosis_review_path:
+    description: "Diagnosis review verdict path"
+    default: ".dna/specs/diagnosis-$ARGUMENTS.review.json"
+
+evidence:
+  - label: Flutter rewrite diagnosis workflow
+    kind: reference
+    path: /Users/samuel/lawark/lwk_flutter_v2-rewrite/.dna/specs
+    description: Dogfood diagnosis specs and review verdicts that gate implementation.
+  - label: Flutter rewrite progress evidence
+    kind: reference
+    path: /Users/samuel/lawark/lwk_flutter_v2-rewrite/.dna/fix-progress
+    description: Module-level progress JSON and test logs showing diagnosis/review as a repeated work pattern.
+
+genes:
+  diagnosis_before_edit:
+    description: Risky rewrite work must classify failures and missing behavior before any implementation edit
+    codons:
+      - type: attract
+        target: evidence_first_diagnosis
+      - type: repel
+        target: edit_before_classification
+      - type: threshold
+        condition: "diagnosis_review_verdict == APPROVE"
+        action: block
+
+  evidence_only_diagnosis:
+    description: Diagnosis artifacts describe facts and classifications, not implementation orders or hidden fix plans
+    codons:
+      - type: attract
+        target: v1_reference
+      - type: attract
+        target: failing_test_reference
+      - type: repel
+        target: fix_prescription_in_diagnosis
+      - type: sense
+        signal: missing_evidence_path
+        response: request_reanalysis
+
+  reviewer_gate:
+    description: A separate reviewer must approve diagnosis quality before the workflow can hand off to fixing
+    codons:
+      - type: attract
+        target: independent_reviewer_verdict
+      - type: repel
+        target: self_approved_diagnosis
+      - type: threshold
+        condition: "diagnosis_review_written == true"
+        action: block
+
+contexts: {}
+
+roles:
+  diagnostician:
+    description: Reads behavior evidence, tests, v1/v2 code, and writes an evidence-only diagnosis artifact.
+    tool_permissions:
+      allow: [Read, Grep, Glob, Write]
+      deny: [Edit, Bash, NotebookEdit]
+    scope:
+      read: ["**/*", ".dna/**", "docs/**"]
+      write: [".dna/specs/**"]
+    instructions:
+      - Read the behavior document, failing tests, v1 implementation, and v2 current state before writing diagnosis.
+      - Classify each issue as BUG, UNIMPLEMENTED, INFRA, REMOVED, or TEST_BUG.
+      - Include concrete evidence paths and v1/v2 references for every classification.
+      - Do not include fix prescriptions, implementation order, call-site instructions, or notes for the implementer.
+      - Write only the diagnosis artifact; do not edit app code, tests, org profiles, templates, or runtime artifacts.
+
+  diagnosis_reviewer:
+    description: Reviews diagnosis quality and writes the durable approval or reanalysis verdict.
+    tool_permissions:
+      allow: [Read, Grep, Glob, Write]
+      deny: [Edit, Bash, NotebookEdit]
+    scope:
+      read: ["**/*", ".dna/**", "docs/**"]
+      write: [".dna/specs/*.review.json"]
+    instructions:
+      - Verify every failing, skipped, or hung test from the baseline is covered.
+      - Verify v1 references and evidence paths exist and support the classifications.
+      - Reject diagnosis that contains implementation instructions or unsupported claims.
+      - Write verdict JSON with verdict, artifact_reviewed, sections_to_fix, evidence_paths, confidence, summary, and updated_at.
+      - APPROVE permits later fixing; REQUEST_REANALYSIS blocks implementation and routes back to diagnosis.
+
+  manager_reviewer:
+    description: Turns the diagnosis/review state into a manager-readable next-action packet.
+    tool_permissions:
+      allow: [Read, Grep, Glob]
+      deny: [Edit, Write, Bash, NotebookEdit]
+    scope:
+      read: ["**/*", ".dna/**", "docs/**"]
+      write: []
+    instructions:
+      - Summarize whether implementation is allowed, blocked, or needs reanalysis.
+      - Name the exact diagnosis and review artifacts used as evidence.
+      - If review is missing or REQUEST_REANALYSIS, block fixing and provide the next command.
+      - Keep Obsidian/wiki as internal memory only; use machine artifacts as workflow evidence.
+
+workflows:
+  diagnosis-review:
+    name: Diagnosis Review
+    description: Analyze module failures and require an independent diagnosis review before implementation starts.
+    steps:
+      - id: diagnose
+        role: diagnostician
+        description: Produce evidence-only diagnosis for the target module or risky rewrite slice.
+        prompt: |
+          Diagnose $ARGUMENTS before any implementation edit.
+          Read {{behavior_docs}}/$ARGUMENTS.md, failing test evidence, v1 implementation, and v2 current state.
+          Write {{diagnosis_path}} with classifications, evidence paths, v1/v2 references, and uncertainty.
+          Do not include fix prescriptions, implementation order, call-site instructions, or notes for the implementer.
+        handoff:
+          produces:
+            - type: file
+              path: "{{diagnosis_path}}"
+              description: Evidence-only diagnosis artifact.
+      - id: review-diagnosis
+        role: diagnosis_reviewer
+        depends_on: [diagnose]
+        description: Review diagnosis quality and write an approval or reanalysis verdict.
+        prompt: |
+          Review {{diagnosis_path}} for $ARGUMENTS.
+          Verify coverage, evidence paths, classification quality, and absence of fix prescriptions.
+          Write {{diagnosis_review_path}} with verdict APPROVE or REQUEST_REANALYSIS.
+        checkpoints:
+          - assert: diagnosis_review_verdict_present
+            command: "test -s \"{{diagnosis_review_path}}\""
+            message: "Diagnosis review verdict must exist before any implementation handoff."
+            action: block
+        handoff:
+          consumes:
+            - type: file
+              path: "{{diagnosis_path}}"
+              from: diagnose
+              description: Diagnosis artifact.
+          produces:
+            - type: file
+              path: "{{diagnosis_review_path}}"
+              description: Diagnosis review verdict.
+      - id: manager-route
+        role: manager_reviewer
+        depends_on: [review-diagnosis]
+        description: Produce manager-readable next action for implementation, reanalysis, or blocked scope.
+        prompt: |
+          Read {{diagnosis_path}} and {{diagnosis_review_path}}.
+          State whether fixing is allowed, blocked, or requires reanalysis.
+          Include evidence paths, confidence, and the next command.
+        handoff:
+          consumes:
+            - type: file
+              path: "{{diagnosis_review_path}}"
+              from: review-diagnosis
+              description: Diagnosis review verdict.
+          produces:
+            - type: summary
+              name: diagnosis_route
+              description: Manager-readable route to fix, reanalysis, or blocked state.
+
+controllers:
+  diagnosis-review-gate:
+    name: Diagnosis Review Gate
+    description: "Run diagnosis, independent diagnosis review, and manager route before implementation starts."
+    kind: sequential
+    workflow: diagnosis-review
+    max_rounds: 1
+    progress_artifact_path: ".dna/diagnosis-review/$ARGUMENTS.json"
+    roles:
+      diagnostician: diagnostician
+      diagnosis_reviewer: diagnosis_reviewer
+      manager_reviewer: manager_reviewer
+    stop_format: configured_stop_report

package/dist/templates/flutter-rewrite-fix-review-loop.dna.yaml

@@ -0,0 +1,260 @@
+# flutter-rewrite-fix-review-loop: diagnosis-backed fix, review, and verification loop
+# Source: extracted from Flutter rewrite dogfood fix workflow
+# Purpose: reuse the inner implementation/review/verify loop without adopting the full rewrite asset
+
+version: "0.1.0"
+id: template_flutter_rewrite_fix_review_loop
+name: Flutter Rewrite Fix Review Loop
+purpose: Run the smallest approved Flutter rewrite fix with independent review, fresh verification, and durable progress evidence.
+maturity: reviewed
+fit:
+  - Rewrite slices with an approved diagnosis and review verdict.
+  - Behavior-preserving fixes that need independent review before completion or rollout.
+not_for:
+  - Starting implementation without approved diagnosis.
+  - Broad refactors, opportunistic improvements, or self-approved fixes.
+inputs:
+  - approved diagnosis artifact
+  - diagnosis review verdict
+  - v1 behavior reference
+  - focused verification command
+outputs:
+  - scoped fix diff summary
+  - independent fix review verdict
+  - verification and progress evidence
+lineage:
+  source: Flutter rewrite dogfood fix-review-verify loop
+  reference: /Users/samuel/lawark/lwk_flutter_v2-rewrite/.dna/fix-progress
+type: project
+namespace: frfrl
+
+cascade:
+  inherits: ["species:default"]
+  priority: 100
+
+variables:
+  diagnosis_path:
+    description: "Approved diagnosis artifact path"
+    default: ".dna/specs/diagnosis-$ARGUMENTS.md"
+  diagnosis_review_path:
+    description: "Diagnosis review verdict path"
+    default: ".dna/specs/diagnosis-$ARGUMENTS.review.json"
+  progress_path:
+    description: "Module progress JSON path"
+    default: ".dna/fix-progress/$ARGUMENTS.json"
+  behavior_docs:
+    description: "Behavior evidence directory"
+    default: "docs/behavior"
+
+evidence:
+  - label: Flutter rewrite fix-loop progress
+    kind: reference
+    path: /Users/samuel/lawark/lwk_flutter_v2-rewrite/.dna/fix-progress
+    description: Module-level progress JSON and test logs showing the diagnosis-backed fix/review/verify loop.
+  - label: Flutter rewrite diagnosis specs
+    kind: reference
+    path: /Users/samuel/lawark/lwk_flutter_v2-rewrite/.dna/specs
+    description: Approved diagnosis and review artifacts consumed before implementation starts.
+
+genes:
+  approved_diagnosis_required:
+    description: Implementation can start only from an approved diagnosis and review verdict
+    codons:
+      - type: attract
+        target: reviewed_diagnosis
+      - type: repel
+        target: edit_without_diagnosis
+      - type: threshold
+        condition: "diagnosis_review_verdict == APPROVE"
+        action: block
+
+  behavior_equivalence:
+    description: Fixes preserve v1 behavior and prove equivalence with fresh evidence
+    codons:
+      - type: attract
+        target: v1_behavior_reference
+      - type: attract
+        target: logic_equivalence_check
+      - type: repel
+        target: opportunistic_improvement
+      - type: threshold
+        condition: "fresh_verification_evidence == true"
+        action: block
+
+  small_reversible_rounds:
+    description: Each fix round stays small, reviewable, and reversible
+    codons:
+      - type: attract
+        target: minimal_diff
+      - type: attract
+        target: after_change_verification
+      - type: repel
+        target: broad_refactor_batch
+      - type: threshold
+        condition: "files_changed_per_round <= 5"
+        action: escalate
+
+contexts: {}
+
+roles:
+  fixer:
+    description: Implements the smallest diagnosis-approved fix while preserving v1 behavior.
+    tool_permissions:
+      allow: [Read, Edit, Write, Grep, Glob, Bash]
+      deny: [NotebookEdit]
+    scope:
+      read: ["**/*", ".dna/**", "docs/**"]
+      write: ["lib/**", "v2/**", "test/**", ".dna/fix-progress/**"]
+    instructions:
+      - Read {{diagnosis_path}} and {{diagnosis_review_path}} before any Edit.
+      - Confirm the diagnosis review verdict is APPROVE before changing code.
+      - Read the relevant v1 source and behavior evidence before implementing.
+      - Fix only the approved breakpoint or missing implementation.
+      - Preserve behavior, including old edge cases and bugs, unless the approved diagnosis explicitly says otherwise.
+      - Keep the diff small and reversible; avoid unrelated cleanup, new abstractions, or broad refactors.
+      - Run focused verification after each meaningful change and record evidence.
+
+  fix_reviewer:
+    description: Reviews the fix against diagnosis, v1 behavior, and scope boundaries.
+    tool_permissions:
+      allow: [Read, Grep, Glob, Bash]
+      deny: [Edit, Write, NotebookEdit]
+    scope:
+      read: ["**/*", ".dna/**", "docs/**"]
+      write: []
+    instructions:
+      - Compare the diff to {{diagnosis_path}} and {{diagnosis_review_path}}.
+      - Verify every changed file is necessary for the approved diagnosis.
+      - Check for behavior drift, opportunistic improvement, unrelated refactor, or missing v1 reference.
+      - Reject the round if evidence is stale, missing, or too broad.
+      - "Produce a concise verdict: APPROVE, REQUEST_CHANGES, or BLOCKED."
+
+  verifier:
+    description: Runs focused verification and updates progress evidence for the module.
+    tool_permissions:
+      allow: [Read, Edit, Write, Grep, Glob, Bash]
+      deny: [NotebookEdit]
+    scope:
+      read: ["**/*", ".dna/**", "docs/**"]
+      write: [".dna/fix-progress/**"]
+    instructions:
+      - Run the smallest meaningful test/analyze/build command that proves the fix.
+      - Record command, result, evidence paths, remaining failures, and next focus in {{progress_path}}.
+      - If verification cannot run, record the blocker and required human/environment action.
+      - Do not claim completion without fresh evidence.
+
+  manager_reviewer:
+    description: Turns fix/review/verify results into a manager-readable route decision.
+    tool_permissions:
+      allow: [Read, Grep, Glob]
+      deny: [Edit, Write, Bash, NotebookEdit]
+    scope:
+      read: ["**/*", ".dna/**", "docs/**"]
+      write: []
+    instructions:
+      - Summarize whether the module is PASS, CONTINUE, REQUEST_CHANGES, or BLOCKED.
+      - Name the diagnosis, review verdict, test evidence, and progress artifact.
+      - If active work remains, route back to the fix loop or asset suggestions before sync/evolution.
+      - Keep Obsidian/wiki as internal memory only; use machine artifacts as workflow evidence.
+
+workflows:
+  fix-review-loop:
+    name: Fix Review Loop
+    description: Implement from approved diagnosis, independently review behavior equivalence, verify, and record manager-readable progress.
+    steps:
+      - id: fix
+        role: fixer
+        description: Implement the smallest diagnosis-approved behavior-preserving fix.
+        prompt: |
+          Fix $ARGUMENTS using {{diagnosis_path}} and {{diagnosis_review_path}}.
+          Confirm the review verdict is APPROVE, read v1 behavior references, then make the smallest necessary code/test changes.
+          Preserve v1 behavior and avoid unrelated refactors.
+        checkpoints:
+          - assert: diagnosis_review_verdict_present
+            command: "test -s \"{{diagnosis_review_path}}\""
+            message: "Diagnosis review verdict must exist before fixing."
+            action: block
+        handoff:
+          consumes:
+            - type: file
+              path: "{{diagnosis_path}}"
+              description: Approved diagnosis artifact.
+            - type: file
+              path: "{{diagnosis_review_path}}"
+              description: Diagnosis review verdict.
+          produces:
+            - type: summary
+              name: fix_diff_summary
+              description: Changed files, target diagnosis item, and verification commands run.
+      - id: review-fix
+        role: fix_reviewer
+        depends_on: [fix]
+        description: Review the fix against approved diagnosis and v1 behavior.
+        prompt: |
+          Review the current diff for $ARGUMENTS.
+          Check scope, v1 behavior equivalence, diagnosis alignment, and evidence freshness.
+          Return APPROVE, REQUEST_CHANGES, or BLOCKED with reasons.
+        handoff:
+          consumes:
+            - type: summary
+              name: fix_diff_summary
+              from: fix
+              description: Fix round summary.
+          produces:
+            - type: summary
+              name: fix_review_verdict
+              description: Independent review verdict for the fix round.
+      - id: verify
+        role: verifier
+        depends_on: [review-fix]
+        description: Run focused verification and update progress evidence.
+        prompt: |
+          Run focused verification for $ARGUMENTS after review.
+          Update {{progress_path}} with verdict, commands, evidence paths, remaining failures, and next focus.
+        checkpoints:
+          - assert: progress_artifact_written
+            command: "test -s \"{{progress_path}}\""
+            message: "Progress JSON must be written before manager route."
+            action: block
+        handoff:
+          consumes:
+            - type: summary
+              name: fix_review_verdict
+              from: review-fix
+              description: Fix review verdict.
+          produces:
+            - type: file
+              path: "{{progress_path}}"
+              description: Updated module progress evidence.
+      - id: manager-route
+        role: manager_reviewer
+        depends_on: [verify]
+        description: Produce manager-readable next action from progress evidence.
+        prompt: |
+          Read {{progress_path}}, {{diagnosis_path}}, and {{diagnosis_review_path}}.
+          State PASS, CONTINUE, REQUEST_CHANGES, or BLOCKED; include evidence paths and next command.
+        handoff:
+          consumes:
+            - type: file
+              path: "{{progress_path}}"
+              from: verify
+              description: Module progress evidence.
+          produces:
+            - type: summary
+              name: fix_loop_route
+              description: Manager-readable next action for the module.
+
+controllers:
+  fix-review-loop:
+    name: Fix Review Loop
+    description: "Run diagnosis-backed fix, independent review, verification, and manager route for one module or risky slice."
+    kind: sequential
+    workflow: fix-review-loop
+    max_rounds: 3
+    progress_artifact_path: ".dna/fix-progress/$ARGUMENTS.json"
+    roles:
+      fixer: fixer
+      fix_reviewer: fix_reviewer
+      verifier: verifier
+      manager_reviewer: manager_reviewer
+    stop_format: configured_stop_report