intentdna 1.7.4 → 1.8.0

package/dist/schema/validators/controllers.js

@@ -54,12 +54,11 @@ function validateControllerPolicy(policy, path, errors) {
         errors.push({ path: `${path}.progress_provenance_failure`, message: "must be a non-empty string" });
     }
 }
-function validateControllerWorkflowRoles(workflow, requiredRoleKeys, roleMap, path, errors) {
+function validateControllerWorkflowRoles(workflow, roleEntries, path, errors) {
     if (!workflow)
         return;
     const workflowRoles = new Set(workflow.steps.map((step) => step.role));
-    for (const roleKey of requiredRoleKeys) {
-        const roleName = roleMap[roleKey];
+    for (const [roleKey, roleName] of roleEntries) {
         if (typeof roleName !== "string" || !roleName)
             continue;
         if (!workflowRoles.has(roleName)) {
@@ -91,32 +90,40 @@ export function validateController(controller, roleNames, workflows, path) {
     if (!Number.isInteger(controller.max_rounds) || controller.max_rounds < 1 || controller.max_rounds > 20) {
         errors.push({ path: `${path}.max_rounds`, message: "max_rounds must be an integer in 1..20" });
     }
-    const requiredStringFields = [
-        "progress_artifact_path",
-        "diagnosis_workflow",
-        "fix_workflow",
-        "diagnosis_artifact_path",
-        "diagnosis_review_artifact_path",
-        "review_artifact_path",
-    ];
+    const requiredStringFields = kindMetadata?.kind === "sequential"
+        ? ["progress_artifact_path", "workflow"]
+        : [
+            "progress_artifact_path",
+            "diagnosis_workflow",
+            "fix_workflow",
+            "diagnosis_artifact_path",
+            "diagnosis_review_artifact_path",
+            "review_artifact_path",
+        ];
     for (const field of requiredStringFields) {
         if (typeof controller[field] !== "string" || !controller[field]) {
             errors.push({ path: `${path}.${field}`, message: "must be a non-empty string" });
         }
     }
-    const artifactPathFields = [
-        "progress_artifact_path",
-        "diagnosis_artifact_path",
-        "diagnosis_review_artifact_path",
-        "review_artifact_path",
-    ];
+    const artifactPathFields = kindMetadata?.kind === "sequential"
+        ? ["progress_artifact_path"]
+        : [
+            "progress_artifact_path",
+            "diagnosis_artifact_path",
+            "diagnosis_review_artifact_path",
+            "review_artifact_path",
+        ];
     for (const field of artifactPathFields) {
         if (typeof controller[field] === "string" && !isSafeControllerArtifactPath(controller[field])) {
             errors.push({ path: `${path}.${field}`, message: "must be a relative .dna/ artifact template containing $ARGUMENTS without glob, brace, absolute, or parent traversal syntax" });
         }
     }
+    const workflow = controller.workflow ? workflows[controller.workflow] : undefined;
     const diagnosisWorkflow = controller.diagnosis_workflow ? workflows[controller.diagnosis_workflow] : undefined;
     const fixWorkflow = controller.fix_workflow ? workflows[controller.fix_workflow] : undefined;
+    if (controller.workflow && !workflow) {
+        errors.push({ path: `${path}.workflow`, message: `references unknown workflow '${controller.workflow}'` });
+    }
     if (controller.diagnosis_workflow && !diagnosisWorkflow) {
         errors.push({ path: `${path}.diagnosis_workflow`, message: `references unknown workflow '${controller.diagnosis_workflow}'` });
     }
@@ -128,8 +135,14 @@ export function validateController(controller, roleNames, workflows, path) {
     if (!roleMap || typeof roleMap !== "object") {
         errors.push({ path: `${path}.roles`, message: "controller requires roles" });
     }
+    else if (kindMetadata?.kind === "sequential" && Object.keys(roleMap).length === 0) {
+        errors.push({ path: `${path}.roles`, message: "sequential controller requires at least one workflow role" });
+    }
     else {
-        for (const roleKey of requiredRoles) {
+        const roleKeysToValidate = kindMetadata?.kind === "sequential"
+            ? Object.keys(roleMap)
+            : requiredRoles;
+        for (const roleKey of roleKeysToValidate) {
             const roleName = roleMap[roleKey];
             if (typeof roleName !== "string" || !roleName) {
                 errors.push({ path: `${path}.roles.${roleKey}`, message: "must be a non-empty role name" });
@@ -143,8 +156,13 @@ export function validateController(controller, roleNames, workflows, path) {
         }
     }
     if (roleMap && typeof roleMap === "object") {
-        validateControllerWorkflowRoles(diagnosisWorkflow, kindMetadata?.diagnosisRoleKeys ?? ["analyzer", "analysis_reviewer"], roleMap, `${path}.diagnosis_workflow`, errors);
-        validateControllerWorkflowRoles(fixWorkflow, kindMetadata?.fixRoleKeys ?? ["surgeon", "fix_reviewer", "test_runner"], roleMap, `${path}.fix_workflow`, errors);
+        if (kindMetadata?.kind === "sequential") {
+            validateControllerWorkflowRoles(workflow, Object.entries(roleMap), `${path}.workflow`, errors);
+        }
+        else {
+            validateControllerWorkflowRoles(diagnosisWorkflow, (kindMetadata?.diagnosisRoleKeys ?? ["analyzer", "analysis_reviewer"]).map((roleKey) => [roleKey, roleMap[roleKey]]), `${path}.diagnosis_workflow`, errors);
+            validateControllerWorkflowRoles(fixWorkflow, (kindMetadata?.fixRoleKeys ?? ["surgeon", "fix_reviewer", "test_runner"]).map((roleKey) => [roleKey, roleMap[roleKey]]), `${path}.fix_workflow`, errors);
+        }
     }
     if (controller.stop_format !== "configured_stop_report" && controller.stop_format !== "zh_three_part") {
         errors.push({ path: `${path}.stop_format`, message: "stop_format must be 'configured_stop_report' or legacy 'zh_three_part'" });

package/dist/schema/workflow-authoring-contract.d.ts

@@ -0,0 +1,29 @@
+export interface AuthoringFieldConstraint {
+    name: string;
+    required: boolean;
+    type: string;
+    allowed_values?: readonly string[];
+    notes?: string;
+}
+export declare const WORKFLOW_AUTHORING_SCHEMA: {
+    readonly source: "src/schema/workflow-authoring-contract.ts; field maps are exhaustive against src/schema/types.ts";
+    readonly workflow: readonly AuthoringFieldConstraint[];
+    readonly step: readonly AuthoringFieldConstraint[];
+    readonly role: readonly AuthoringFieldConstraint[];
+    readonly tool_permissions: readonly AuthoringFieldConstraint[];
+    readonly scope: readonly AuthoringFieldConstraint[];
+    readonly handoff_artifact: {
+        readonly fields: readonly AuthoringFieldConstraint[];
+        readonly type_values: readonly ["file", "directory", "test_result", "git_commit", "summary", "state"];
+        readonly required_fields: string[];
+        readonly optional_fields: string[];
+    };
+    readonly checkpoint: {
+        readonly fields: readonly AuthoringFieldConstraint[];
+        readonly required_fields: string[];
+        readonly optional_fields: string[];
+        readonly action_values: readonly ["block", "warn"];
+    };
+    readonly transition: readonly AuthoringFieldConstraint[];
+    readonly retry_policy: readonly AuthoringFieldConstraint[];
+};

package/dist/schema/workflow-authoring-contract.js

@@ -0,0 +1,109 @@
+import { CHECKPOINT_ACTION_VALUES, HANDOFF_TYPE_VALUES, RETRY_BACKOFF_VALUES, TRANSITION_CONDITION_VALUES, WORKFLOW_HANDOFF_EXHAUSTED_VALUES, WORKFLOW_ISOLATION_VALUES, WORKFLOW_MERGE_STRATEGY_VALUES, WORKFLOW_STEP_FAILURE_VALUES, } from "./types.js";
+function fieldsFrom(definitions) {
+    return Object.entries(definitions).map(([name, definition]) => ({
+        name,
+        ...definition,
+    }));
+}
+const WORKFLOW_FIELDS = {
+    name: { required: true, type: "string", notes: "Human-readable workflow name." },
+    description: { required: false, type: "string" },
+    steps: { required: true, type: "WorkflowStepDef[]", notes: "At least one step; ids must be unique within the workflow." },
+    transitions: { required: false, type: "TransitionDef[]" },
+    retry_policy: { required: false, type: "RetryPolicy" },
+    max_rounds: { required: false, type: "number", notes: "Alias for retry rounds when retry_policy is omitted." },
+    produces: { required: false, type: "HandoffArtifact[]" },
+    consumes: { required: false, type: "HandoffArtifact[]" },
+    default_isolation: { required: false, type: "WorkflowIsolation", allowed_values: WORKFLOW_ISOLATION_VALUES },
+    merge_strategy: { required: false, type: "WorkflowMergeStrategy", allowed_values: WORKFLOW_MERGE_STRATEGY_VALUES },
+};
+const STEP_FIELDS = {
+    id: { required: true, type: "string", notes: "Stable safe identifier, unique within the workflow." },
+    role: { required: true, type: "string", notes: "Must reference a declared role in the same asset." },
+    description: { required: false, type: "string" },
+    depends_on: { required: false, type: "string[]" },
+    optional: { required: false, type: "boolean" },
+    run_if: { required: false, type: "string" },
+    prompt: { required: false, type: "string" },
+    completion: { required: false, type: "CompletionCheck[]" },
+    checkpoints: { required: false, type: "StepCheckpoint[]" },
+    handoff: { required: false, type: "StepHandoff" },
+    isolation: { required: false, type: "WorkflowIsolation", allowed_values: WORKFLOW_ISOLATION_VALUES },
+    enforce: { required: false, type: "step-level enforcement object" },
+    max_attempts: { required: false, type: "number" },
+    on_fail: { required: false, type: "WorkflowStepFailureAction", allowed_values: WORKFLOW_STEP_FAILURE_VALUES },
+    handoff_to: { required: false, type: "string" },
+    max_handoffs: { required: false, type: "number" },
+    on_handoff_exhausted: { required: false, type: "WorkflowHandoffExhaustedAction", allowed_values: WORKFLOW_HANDOFF_EXHAUSTED_VALUES },
+    blocked_items_path: { required: false, type: "string" },
+};
+const ROLE_FIELDS = {
+    description: { required: true, type: "string" },
+    tool_permissions: { required: false, type: "ToolPermissions" },
+    scope: { required: false, type: "ScopeDef" },
+    output_schema: { required: false, type: "string|OutputSchema" },
+    model: { required: false, type: "string", notes: "Harness hint only; use human for an explicit user-owned gate or interactive for a main-session external-agent step." },
+    activates_genes: { required: false, type: "string[]" },
+    suppresses_genes: { required: false, type: "string[]" },
+    post_checks: { required: false, type: "string[]" },
+    instructions: { required: false, type: "string[]" },
+    success_criteria: { required: false, type: "string[]" },
+    failure_modes: { required: false, type: "string[]" },
+};
+const TOOL_PERMISSION_FIELDS = {
+    allow: { required: false, type: "string[]" },
+    deny: { required: false, type: "string[]" },
+};
+const SCOPE_FIELDS = {
+    read: { required: false, type: "string[]" },
+    write: { required: false, type: "string[]" },
+};
+const HANDOFF_FIELDS = {
+    type: { required: true, type: "HandoffType", allowed_values: HANDOFF_TYPE_VALUES },
+    path: { required: false, type: "string" },
+    name: { required: false, type: "string" },
+    artifact_id: { required: false, type: "string" },
+    from: { required: false, type: "string" },
+    required: { required: false, type: "boolean", notes: "Defaults to true." },
+    description: { required: true, type: "string" },
+};
+const CHECKPOINT_FIELDS = {
+    assert: { required: true, type: "string" },
+    command: { required: false, type: "string", notes: "Required for custom assertions that are not built-ins." },
+    message: { required: true, type: "string" },
+    action: { required: false, type: "CheckpointAction", allowed_values: CHECKPOINT_ACTION_VALUES, notes: "Defaults to block." },
+};
+const TRANSITION_FIELDS = {
+    from: { required: true, type: "string" },
+    to: { required: true, type: "string" },
+    condition: { required: true, type: "TransitionCondition", allowed_values: TRANSITION_CONDITION_VALUES },
+};
+const RETRY_POLICY_FIELDS = {
+    max_retries: { required: true, type: "number", notes: "Must be zero or greater." },
+    retry_from: { required: false, type: "string", notes: "Must reference an existing step when present." },
+    backoff: { required: false, type: "RetryBackoff", allowed_values: RETRY_BACKOFF_VALUES },
+};
+const handoffFields = fieldsFrom(HANDOFF_FIELDS);
+const checkpointFields = fieldsFrom(CHECKPOINT_FIELDS);
+export const WORKFLOW_AUTHORING_SCHEMA = {
+    source: "src/schema/workflow-authoring-contract.ts; field maps are exhaustive against src/schema/types.ts",
+    workflow: fieldsFrom(WORKFLOW_FIELDS),
+    step: fieldsFrom(STEP_FIELDS),
+    role: fieldsFrom(ROLE_FIELDS),
+    tool_permissions: fieldsFrom(TOOL_PERMISSION_FIELDS),
+    scope: fieldsFrom(SCOPE_FIELDS),
+    handoff_artifact: {
+        fields: handoffFields,
+        type_values: HANDOFF_TYPE_VALUES,
+        required_fields: handoffFields.filter((field) => field.required).map((field) => field.name),
+        optional_fields: handoffFields.filter((field) => !field.required).map((field) => field.name),
+    },
+    checkpoint: {
+        fields: checkpointFields,
+        required_fields: checkpointFields.filter((field) => field.required).map((field) => field.name),
+        optional_fields: checkpointFields.filter((field) => !field.required).map((field) => field.name),
+        action_values: CHECKPOINT_ACTION_VALUES,
+    },
+    transition: fieldsFrom(TRANSITION_FIELDS),
+    retry_policy: fieldsFrom(RETRY_POLICY_FIELDS),
+};

package/dist/schema/yaml-parser.js

@@ -224,6 +224,24 @@ function parseScalar(s) {
     // Inline empty object: {}
     if (s === "{}")
         return {};
+    // Inline object: { key: value, other: "quoted" }
+    if (s.startsWith("{") && s.endsWith("}")) {
+        const inner = s.slice(1, -1).trim();
+        if (inner === "")
+            return {};
+        const result = {};
+        for (const entry of splitInlineArray(inner)) {
+            const colonIdx = findKeyColon(entry);
+            if (colonIdx <= 0)
+                return s;
+            const key = entry.slice(0, colonIdx).trim().replace(/^["']|["']$/g, "");
+            const value = entry.slice(colonIdx + 1).trim();
+            if (!key)
+                return s;
+            result[key] = parseScalar(value);
+        }
+        return result;
+    }
     // Quoted string
     if ((s.startsWith('"') && s.endsWith('"')) || (s.startsWith("'") && s.endsWith("'"))) {
         return s.slice(1, -1).replace(/\\"/g, '"').replace(/\\'/g, "'").replace(/\\\\/g, "\\");

package/dist/templates/api-backend.dna.yaml

@@ -5,6 +5,25 @@
 version: "0.1.0"
 id: template_api_backend
 name: API Backend Standards
+purpose: Provide a backend API baseline for security, quality, database safety, and reviewable implementation.
+maturity: draft
+fit:
+  - Node.js, Python, or service API projects that need a local governance baseline.
+  - Teams starting from API standards before authoring a richer workflow asset.
+not_for:
+  - Replacing endpoint-specific design, tests, or threat modeling.
+  - Online execution, cloud deployment, or database mutation by the template itself.
+inputs:
+  - API task scope
+  - endpoint and data model context
+  - security and database constraints
+outputs:
+  - backend development guardrails
+  - API quality review notes
+  - database safety reminders
+lineage:
+  source: built-in backend standards template
+  reference: src/templates/api-backend.dna.yaml
 type: project
 namespace: be
 

package/dist/templates/brainstorming-first.dna.yaml

@@ -6,6 +6,25 @@
 version: "0.1.0"
 id: template_brainstorming_first
 name: Brainstorming First
+purpose: Force design, Socratic refinement, and task decomposition before implementation starts.
+maturity: draft
+fit:
+  - Early-stage tasks where requirements, tradeoffs, or implementation chunks are unclear.
+  - Planning work that should produce small verifiable steps before coding.
+not_for:
+  - Already approved implementation slices with clear acceptance criteria.
+  - Letting brainstorming replace tests, review, or delivery evidence.
+inputs:
+  - raw idea or task request
+  - known constraints and open questions
+  - desired outcome or decision point
+outputs:
+  - refined requirements
+  - decomposed task plan
+  - implementation readiness notes
+lineage:
+  source: brainstorming and writing-plans workflow shape
+  reference: src/templates/brainstorming-first.dna.yaml
 type: project
 namespace: bs
 

package/dist/templates/code-cleanup.dna.yaml

@@ -1,6 +1,25 @@
 version: "0.1.0"
 id: template_code_cleanup
 name: Code Cleanup (Regression-Safe)
+purpose: Clean code in small behavior-preserving passes with tests between each smell-focused edit.
+maturity: reviewed
+fit:
+  - Refactors or cleanup where existing behavior must stay stable.
+  - Reducing dead code, duplication, naming issues, or local complexity under test coverage.
+not_for:
+  - Mixing feature work into cleanup.
+  - Large unverified rewrites or cleanup without regression checks.
+inputs:
+  - cleanup scope
+  - current tests or behavior evidence
+  - identified smell category
+outputs:
+  - scoped cleanup diff
+  - regression verification evidence
+  - remaining cleanup risk notes
+lineage:
+  source: built-in regression-safe cleanup workflow
+  reference: docs/archive/fix-notes/refactoring-workflow-principles.md
 type: project
 namespace: cc
 

package/dist/templates/code-review-pipeline.dna.yaml

@@ -5,6 +5,24 @@
 version: "0.1.0"
 id: template_code_review_pipeline
 name: Code Review Pipeline
+purpose: Run structured implementation review with actionable findings, tests, and follow-up fixes before merge or adoption.
+maturity: reviewed
+fit:
+  - Pull request or patch review that needs explicit PASS/FAIL evidence.
+  - Separating reviewer feedback from implementation fixes.
+not_for:
+  - Rubber-stamp approval.
+  - Replacing targeted tests or security checks with prose.
+inputs:
+  - changed files
+  - task specification
+  - test results
+outputs:
+  - review findings with code references
+  - required fixes
+  - re-review verdict
+lineage:
+  source: requesting-code-review and receiving-code-review workflow shape
 type: project
 namespace: crp
 

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