intentdna 1.7.5 → 1.8.0

package/dist/workflow/authoring-packet.js

@@ -0,0 +1,218 @@
+import { readFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { WORKFLOW_AUTHORING_SCHEMA } from "../schema/workflow-authoring-contract.js";
+import { parseYAML } from "../schema/yaml-parser.js";
+import { calculateTemplateContentHash, findTemplateCatalogEntry } from "../templates/catalog.js";
+export const AUTHORING_PACKET_SCHEMA_VERSION = "intentdna.authoring_packet.v1";
+const DEFAULT_EXAMPLES = [
+    {
+        name: "code-review-pipeline",
+        annotation: "Shows a multi-role review pipeline with scoped permissions, dependency ordering, checkpoints, and review handoffs.",
+    },
+    {
+        name: "qa-loop",
+        annotation: "Shows a bounded generate-run-analyze-fix QA loop with explicit retry behavior and verification evidence.",
+    },
+];
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function stringArray(value) {
+    return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
+}
+function objectKeys(value) {
+    return isRecord(value) ? Object.keys(value) : [];
+}
+function c1Metadata(parsed) {
+    return {
+        id: parsed.id,
+        name: parsed.name,
+        version: parsed.version,
+        purpose: parsed.purpose,
+        maturity: parsed.maturity,
+        fit: stringArray(parsed.fit),
+        not_for: stringArray(parsed.not_for),
+        inputs: stringArray(parsed.inputs),
+        outputs: stringArray(parsed.outputs),
+        lineage: isRecord(parsed.lineage) ? parsed.lineage : undefined,
+    };
+}
+function workflowKeys(parsed) {
+    if (isRecord(parsed.workflows))
+        return Object.keys(parsed.workflows);
+    return isRecord(parsed.workflow) ? ["workflow"] : [];
+}
+function exampleAnnotation(name) {
+    return DEFAULT_EXAMPLES.find((example) => example.name === name)?.annotation
+        ?? "Complete C1 workflow asset loaded from the real template catalog at packet generation time.";
+}
+async function loadExampleTemplate(name, projectDir) {
+    const entry = await findTemplateCatalogEntry(name, { projectDir });
+    if (!entry)
+        throw new Error(`Authoring packet example template not found: ${name}`);
+    const yaml = await readFile(entry.path, "utf-8");
+    const parsed = parseYAML(yaml);
+    const record = isRecord(parsed) ? parsed : {};
+    return {
+        name: entry.name,
+        display_name: entry.displayName,
+        source_path: entry.path,
+        content_hash: calculateTemplateContentHash(yaml),
+        annotation: exampleAnnotation(name),
+        c1_metadata: c1Metadata(record),
+        workflow_keys: workflowKeys(record),
+        role_keys: objectKeys(record.roles),
+        yaml,
+    };
+}
+function shellQuote(value) {
+    return `'${value.replace(/'/g, `'"'"'`)}'`;
+}
+export async function buildAuthoringPacket(options = {}) {
+    const generatedAt = options.generatedAt ?? new Date().toISOString();
+    const projectDir = resolve(options.projectDir ?? process.cwd());
+    const exampleNames = options.exampleTemplates ?? DEFAULT_EXAMPLES.map((example) => example.name);
+    const examples = await Promise.all(exampleNames.map((name) => loadExampleTemplate(name, projectDir)));
+    const projectFlag = `--project-dir ${shellQuote(projectDir)}`;
+    const authoringCommand = options.goal !== undefined
+        ? `dna workflow authoring-packet ${shellQuote(options.goal)} --json ${projectFlag}`
+        : `dna workflow authoring-packet --json ${projectFlag}`;
+    const candidatePath = join(projectDir, ".dna", "authoring", "<asset>.candidate.dna.yaml");
+    const savedPath = join(projectDir, ".dna", "templates", "<asset>.dna.yaml");
+    return {
+        schema_version: AUTHORING_PACKET_SCHEMA_VERSION,
+        generated_at: generatedAt,
+        network_performed: false,
+        mutation_performed: false,
+        runtime_authority: false,
+        project_context: {
+            root: projectDir,
+            handling: "local_path_only",
+            explicitly_requested: options.projectDir !== undefined,
+        },
+        ...(options.goal !== undefined ? {
+            goal_context: {
+                raw: options.goal,
+                handling: "opaque_context_only",
+                goal_modeling_performed: false,
+            },
+        } : {}),
+        asset_contract: {
+            source: "docs/architecture/c1-asset-format.md",
+            required_fields: ["id", "name", "version", "purpose", "maturity"],
+            recommended_fields: ["fit", "not_for", "inputs", "outputs", "roles", "workflow|workflows", "boundaries", "evidence", "lineage"],
+            validation_required_fields: ["version", "id", "name", "type", "cascade"],
+            validation_notes: [
+                "Use type project for a project-local authored workflow unless a different cascade layer is explicitly intended.",
+                "Include genes: {} and contexts: {} when the workflow adds no policy genes or context modifiers.",
+                "Use exactly one of workflow or workflows, never both.",
+                "Start authored assets at maturity: draft until a human reviews or adopts them.",
+            ],
+            directory_protocol: {
+                builtin_templates: "src/templates/*.dna.yaml",
+                project_templates: ".dna/templates/*.dna.yaml",
+                candidate_staging: ".dna/authoring/*.candidate.dna.yaml",
+            },
+            compatibility: [
+                "Built-in and project-local workflow assets use the same C1 shape.",
+                "Existing x_intentdna fields remain compatibility metadata and should not be deleted just to adopt C1.",
+                "Do not delete existing JSON or YAML fields when revising an older asset; deprecate or mirror them when needed.",
+            ],
+        },
+        schema_constraints: WORKFLOW_AUTHORING_SCHEMA,
+        red_lines: [
+            "Do not loosen Species or Enterprise thresholds; lower layers may only tighten inherited red lines.",
+            "Declare boundaries for runtime authority, write scope, evidence authority, and adoption whenever they apply.",
+            "Do not claim Online, marketplace, Supabase, or MCP executes the workflow or makes allow/warn/block/validate decisions.",
+            "Do not store service-role keys, token peppers, user JWTs, raw API tokens, or secrets in browser-facing or committed YAML.",
+            "Do not bypass dna validate, asset inspection, human review, or explicit sync/adoption commands.",
+            "Do not derive policy from evidence automatically; evidence can produce suggestions only after human review.",
+            "Do not call an LLM, model user intent, rank workflow shapes, or generate YAML inside dna; creation belongs to the external agent.",
+        ],
+        examples,
+        interview_protocol: [
+            {
+                id: "goal",
+                question: "What repeated work method should this asset make easier or safer?",
+                required_output: "One concrete workflow purpose and a short success definition.",
+            },
+            {
+                id: "steps",
+                question: "What are the real steps, in order or DAG form, from intake to verified handoff?",
+                required_output: "Step ids, owners/roles, dependencies, prompts, and produced/consumed artifacts.",
+            },
+            {
+                id: "roles",
+                question: "Who or which agent role is allowed to read, write, run commands, and review?",
+                required_output: "Role definitions with minimal tool permissions and read/write scopes.",
+            },
+            {
+                id: "verification",
+                question: "What evidence proves the workflow did the right thing?",
+                required_output: "Checkpoints, completion checks, command evidence, handoff artifacts, and reviewer criteria.",
+            },
+            {
+                id: "boundaries",
+                question: "What must this workflow never do, mutate, expose, or claim?",
+                required_output: "not_for plus runtime-authority, write-scope, evidence-authority, adoption, secret, and escalation boundaries.",
+            },
+            {
+                id: "failure",
+                question: "How should failure, retry, blocked scope, or human escalation work?",
+                required_output: "retry_policy, transitions, blocked item recording, and human review gates.",
+            },
+        ],
+        validate_loop: [
+            {
+                step: `Generate one C1 YAML candidate at ${candidatePath} from the interview answers and packet examples.`,
+                owner: "external_agent",
+                writes: true,
+            },
+            {
+                step: "Validate the candidate YAML with dna; do not treat prose review as validation.",
+                command: `dna validate ${shellQuote(candidatePath)}`,
+                owner: "dna",
+                writes: false,
+                repeat_until: "exit code 0 and no error diagnostics",
+            },
+            {
+                step: "Revise only the candidate YAML needed to satisfy diagnostics and the stated human intent, then run validation again.",
+                owner: "external_agent",
+                writes: true,
+                repeat_until: "dna validate passes",
+            },
+            {
+                step: `After explicit human confirmation, save the exact validated YAML at ${savedPath}; packet generation itself does not perform this write.`,
+                owner: "human",
+                writes: true,
+            },
+            {
+                step: "Confirm catalog visibility before any init, adoption, binding, or sync.",
+                command: `dna assets show <asset> ${projectFlag} && dna assets inspect <asset> ${projectFlag}`,
+                owner: "dna",
+                writes: false,
+            },
+            {
+                step: "Preview both supported harness sync surfaces after the saved asset validates.",
+                command: `dna sync ${projectFlag} --dry-run && dna sync ${projectFlag} --codex --dry-run`,
+                owner: "dna",
+                writes: false,
+            },
+        ],
+        handoff_boundary: [
+            "The external agent authors YAML only; it does not adopt, bind, sync, upload, deploy, or make runtime decisions.",
+            "Human save/adoption decisions are explicit and separate from packet generation.",
+            "The packet contains no instruction to auto-execute a mutation command; it names the reviewed save destination only.",
+            "dna validates, catalogs, compiles, syncs, and records local runtime evidence deterministically after explicit commands.",
+            "Online may later present this packet, but Online still does not execute workflows or own runtime authority.",
+        ],
+        next_commands: [
+            authoringCommand,
+            `dna validate ${shellQuote(savedPath)}`,
+            `dna assets show <asset> ${projectFlag}`,
+            `dna assets inspect <asset> ${projectFlag}`,
+            `dna sync ${projectFlag} --dry-run`,
+            `dna sync ${projectFlag} --codex --dry-run`,
+        ],
+    };
+}

package/dist/workflow/draft.d.ts

@@ -0,0 +1,159 @@
+export type WorkflowDraftExampleId = "dev_pipeline" | "evidence_review" | "rewrite_governance";
+export type HandoffType = "file" | "directory" | "test_result" | "git_commit" | "summary" | "state";
+export interface HandoffArtifact {
+    type: HandoffType;
+    path?: string;
+    name?: string;
+    from?: string;
+    required?: boolean;
+    description: string;
+}
+export interface WorkflowStepDef {
+    id: string;
+    role: string;
+    description?: string;
+    depends_on?: string[];
+    prompt?: string;
+    checkpoints?: Array<{
+        assert: string;
+        message: string;
+        action?: "block" | "warn";
+    }>;
+    handoff?: {
+        consumes?: HandoffArtifact[];
+        produces?: HandoffArtifact[];
+    };
+}
+export interface WorkflowDraftDef {
+    name: string;
+    description?: string;
+    steps: WorkflowStepDef[];
+    retry_policy?: {
+        max_retries: number;
+        retry_from?: string;
+        backoff?: "none" | "linear" | "exponential";
+    };
+}
+export interface WorkflowDraftInput {
+    exampleId: WorkflowDraftExampleId;
+    goal: string;
+    strictness: "standard" | "high";
+}
+export interface WorkflowDraftValidation {
+    ok: boolean;
+    messages: Array<{
+        severity: "error" | "warning" | "info";
+        path: string;
+        message: string;
+    }>;
+    preview: {
+        step_count: number;
+        parallel_groups: string[][];
+        retry_max: number;
+        write_path: "draft_only";
+    };
+}
+export interface WorkflowDraft {
+    mode: "draft_only";
+    generated_at: string;
+    input: WorkflowDraftInput;
+    scaffold?: {
+        kind: "example_clone_scaffold";
+        source_example: WorkflowDraftExampleId;
+        positioning: string;
+        deprecated_primary_creation_path: "dna workflow authoring-packet";
+    };
+    workflow: WorkflowDraftDef;
+    design_packet: WorkflowDesignPacket;
+    yaml: string;
+    validation: WorkflowDraftValidation;
+    safe_flow: string[];
+    forbidden: string[];
+}
+export type WorkflowEditOperation = "insert_step" | "add_verifier" | "tighten_boundary" | "split_step" | "replace_role";
+export interface WorkflowEditPlanInput extends WorkflowDraftInput {
+    operation: WorkflowEditOperation;
+    instruction: string;
+    targetStep?: string;
+    role?: string;
+    source?: string;
+    inference?: {
+        operation?: "explicit" | "inferred";
+        targetStep?: "explicit" | "inferred" | "default";
+        role?: "explicit" | "inferred" | "default";
+        confidence: "low" | "medium" | "high";
+        reasons: string[];
+    };
+}
+export interface WorkflowEditPlan {
+    mode: "edit_plan_only";
+    generated_at: string;
+    input: WorkflowEditPlanInput;
+    base_workflow: WorkflowDraftDef;
+    proposed_workflow: WorkflowDraftDef;
+    design_packet: WorkflowDesignPacket;
+    operations: Array<{
+        operation: WorkflowEditOperation;
+        target: string;
+        summary: string;
+        human_review_required: true;
+    }>;
+    yaml: string;
+    validation: WorkflowDraftValidation;
+    safe_flow: string[];
+    forbidden: string[];
+}
+export interface WorkflowDesignPacket {
+    workflow: string;
+    goal: string;
+    stepCount: number;
+    editableOperations: WorkflowEditOperation[];
+    reviewCommands: string[];
+    adoptionCommands: string[];
+    mutationBoundary: string;
+    userPrompt: string;
+}
+export interface WorkflowTemplateEvidenceLink {
+    label: string;
+    path: string;
+    kind: "doc" | "dogfood" | "reference";
+    description?: string;
+}
+export interface WorkflowTemplateLineage {
+    generatedFrom?: string;
+    sourceAsset?: string;
+    sourceCandidate?: string;
+    sourceSuggestion?: string;
+    sourceEvidence?: string;
+}
+export interface WorkflowTemplateContext {
+    workflowId?: string;
+    workflows?: Record<string, WorkflowDraftDef>;
+    roles?: Record<string, unknown>;
+    controllers?: Record<string, unknown>;
+    extraSections?: Record<string, unknown>;
+}
+export interface WorkflowDraftExample {
+    id: WorkflowDraftExampleId;
+    label: string;
+    summary: string;
+    workflow: WorkflowDraftDef;
+}
+export declare function workflowDraftToYaml(workflow: WorkflowDraftDef): string;
+export declare function workflowDraftToTemplateYaml(params: {
+    templateName: string;
+    workflow: WorkflowDraftDef;
+    generatedAt?: string;
+    lineage?: WorkflowTemplateLineage;
+    evidence?: readonly WorkflowTemplateEvidenceLink[];
+    templateContext?: WorkflowTemplateContext;
+}): string;
+export declare function workflowDraftExamples(): WorkflowDraftExample[];
+export declare function buildWorkflowDesignPacket(params: {
+    workflow: WorkflowDraftDef;
+    goal: string;
+    templateName?: string;
+}): WorkflowDesignPacket;
+export declare function createWorkflowDraft(input: WorkflowDraftInput, generatedAt?: string): WorkflowDraft;
+export declare function createWorkflowEditPlanFromWorkflow(baseWorkflow: WorkflowDraftDef, input: WorkflowEditPlanInput, generatedAt?: string): WorkflowEditPlan;
+export declare function createWorkflowEditPlan(input: WorkflowEditPlanInput, generatedAt?: string): WorkflowEditPlan;