stageflow 0.27.0 → 0.31.0

package/dist/operatorAgent/profiles/workshopAuthor.js

@@ -0,0 +1,338 @@
+import { parse as parseYaml } from "yaml";
+import { validateDraftPackage, } from "../../config/draftPackage.js";
+import { createFilesystemDocsRetriever, } from "../docsRetrieval.js";
+import { readDraftFromContext, workshopDraftContextAdapter, WORKSHOP_AUTHOR_GREETING, } from "../draftContext.js";
+import { affectedStageIds, diffDraftPackages, draftFingerprint, } from "../proposals.js";
+import { WORKSHOP_AUTHOR_PLAYBOOK } from "./workshopAuthorPlaybook.js";
+import { buildCreateStageDraft, buildCreateTaskDraft, createSaveTool, createWorkshopAuthorMutatingTools, createWorkshopBuildTools, WORKSHOP_FORBIDDEN_AGENT_TOOLS, } from "./workshopAuthorTools.js";
+export const WORKSHOP_AUTHOR_PROFILE_ID = "workshop-author";
+export { WORKSHOP_AUTHOR_PLAYBOOK };
+export { WORKSHOP_AUTHOR_TOOL_NAMES, WORKSHOP_FORBIDDEN_AGENT_TOOLS, buildCreateStageDraft, buildCreateTaskDraft, buildEditStageDraft, buildEditTaskDraft, buildCreatePipelineDraft, buildEditPipelineDraft, createSaveTool, createWorkshopAuthorMutatingTools, } from "./workshopAuthorTools.js";
+const DEFAULT_MODEL = "anthropic/claude-sonnet-4-5";
+const REQUIRED_IO = {
+    io: {
+        input: { schema: { type: "object" } },
+        output: { schema: { type: "object" } },
+    },
+};
+let proposalSeq = 0;
+function nextProposalId() {
+    proposalSeq += 1;
+    return `proposal-${proposalSeq}`;
+}
+function slugifyStageId(text) {
+    const slug = text
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 40);
+    return slug || "stage";
+}
+export function buildStageAddProposal(draft, userText) {
+    const built = buildCreateStageDraft(draft, {
+        summary: userText.trim() || "workshop draft",
+        system_prompt: `Stage for: ${userText.trim() || "workshop draft"}`,
+    });
+    if (!built.ok) {
+        const stageId = slugifyStageId(userText.split(/\s+/).slice(0, 3).join(" "));
+        const usesPath = `./${stageId}.yaml`;
+        const nextDraft = {
+            ...draft,
+            pipeline: {
+                ...draft.pipeline,
+                stages: [
+                    ...draft.pipeline.stages,
+                    {
+                        id: stageId,
+                        uses: usesPath,
+                        ...(draft.pipeline.stages.length === 0 ? { entry: true } : {}),
+                    },
+                ],
+            },
+            stages: [
+                ...(draft.stages ?? []),
+                {
+                    path: usesPath,
+                    body: {
+                        id: stageId,
+                        system_prompt: `Stage for: ${userText.trim() || "workshop draft"}`,
+                        model: DEFAULT_MODEL,
+                        ...REQUIRED_IO,
+                    },
+                },
+            ],
+        };
+        return {
+            id: nextProposalId(),
+            summary: `Add stage “${stageId}”`,
+            nextContext: nextDraft,
+            baseContext: { draft },
+            baseFingerprint: draftFingerprint(draft),
+            artifacts: diffDraftPackages(draft, nextDraft),
+            affectedStageIds: affectedStageIds(draft, nextDraft),
+        };
+    }
+    return {
+        id: nextProposalId(),
+        summary: `Add stage “${built.stageId}”`,
+        nextContext: built.nextDraft,
+        baseContext: { draft },
+        baseFingerprint: draftFingerprint(draft),
+        artifacts: diffDraftPackages(draft, built.nextDraft),
+        affectedStageIds: affectedStageIds(draft, built.nextDraft),
+    };
+}
+function slugifyTaskId(text) {
+    const slug = text
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 40);
+    return slug || "task";
+}
+function extractQuotedPhrase(text) {
+    const match = text.match(/["“]([^"”]+)["”]/);
+    return match?.[1]?.trim() || null;
+}
+export function isTaskProposalIntent(message) {
+    const text = message.trim().toLowerCase();
+    if (!text)
+        return false;
+    return (/\b(create|add|make|attach|fill|set|write)\b[\s\w-]*\btask\b/.test(text) ||
+        /\btask\b[\s\w-]*\b(create|add|fill|goal|brief)\b/.test(text) ||
+        /\b(task brief|task package|task fields)\b/.test(text));
+}
+export function buildTaskAddProposal(draft, userText) {
+    const quoted = extractQuotedPhrase(userText);
+    const existingId = typeof draft.task?.body.id === "string" ? draft.task.body.id : "";
+    const existingGoal = typeof draft.task?.body.goal === "string" ? draft.task.body.goal : "";
+    let taskId = existingId;
+    let goal = existingGoal;
+    if (quoted) {
+        if (!existingId || /\b(create|add|make|attach)\b/i.test(userText)) {
+            taskId = slugifyTaskId(quoted);
+        }
+        goal = quoted;
+    }
+    else {
+        const goalMatch = userText.match(/\b(?:goal|brief)\s*[:=]\s*(.+)$/i);
+        if (goalMatch?.[1]) {
+            goal = goalMatch[1].trim();
+        }
+        else if (!goal) {
+            goal = userText.trim() || "Describe the workflow goal";
+        }
+        if (!taskId) {
+            taskId = slugifyTaskId(userText
+                .replace(/\b(create|add|make|attach|fill|set|write|a|the|task|brief|goal|fields|package)\b/gi, " ")
+                .trim() || "task");
+        }
+    }
+    if (!taskId)
+        taskId = "task";
+    if (!goal)
+        goal = "Describe the workflow goal";
+    const built = buildCreateTaskDraft(draft, { id: taskId, goal });
+    const nextDraft = built.ok
+        ? built.nextDraft
+        : {
+            ...draft,
+            task: {
+                filename: `${taskId}.task.yaml`,
+                body: {
+                    ...(draft.task?.body ?? {}),
+                    id: taskId,
+                    goal,
+                },
+            },
+        };
+    const filling = Boolean(draft.task);
+    return {
+        id: nextProposalId(),
+        summary: filling ? `Fill task “${taskId}”` : `Create task “${taskId}”`,
+        nextContext: nextDraft,
+        baseContext: { draft },
+        baseFingerprint: draftFingerprint(draft),
+        artifacts: diffDraftPackages(draft, nextDraft),
+        affectedStageIds: [],
+    };
+}
+const readDraftTool = {
+    name: "read_draft",
+    description: "Read the current Workshop virtual draft package",
+    handler(_args, ctx) {
+        return {
+            ok: true,
+            content: workshopDraftContextAdapter.serialize(ctx.getContext()),
+        };
+    },
+};
+function coercePlainObject(value) {
+    if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+        return value;
+    }
+    if (typeof value !== "string")
+        return null;
+    const trimmed = value.trim();
+    if (!trimmed)
+        return null;
+    try {
+        const parsed = JSON.parse(trimmed);
+        if (parsed !== null &&
+            typeof parsed === "object" &&
+            !Array.isArray(parsed)) {
+            return parsed;
+        }
+    }
+    catch { }
+    try {
+        const parsed = parseYaml(trimmed);
+        if (parsed !== null &&
+            typeof parsed === "object" &&
+            !Array.isArray(parsed)) {
+            return parsed;
+        }
+    }
+    catch { }
+    return null;
+}
+const proposeDraftTool = {
+    name: "propose_draft",
+    description: "Legacy bulk draft replace. Prefer create_*/edit_* tools. Applies immediately (Accept confirms; Reject soft-undos when unchanged).",
+    handler(args, ctx) {
+        const summary = typeof args.summary === "string" && args.summary.trim()
+            ? args.summary.trim()
+            : "Update draft";
+        let nextDraft = coercePlainObject(args.draft);
+        if ((!nextDraft ||
+            nextDraft.pipeline === null ||
+            typeof nextDraft.pipeline !== "object" ||
+            Array.isArray(nextDraft.pipeline)) &&
+            args.pipeline !== null &&
+            typeof args.pipeline === "object" &&
+            !Array.isArray(args.pipeline)) {
+            const stages = Array.isArray(args.stages)
+                ? args.stages
+                : undefined;
+            const task = coercePlainObject(args.task);
+            nextDraft = {
+                pipeline: args.pipeline,
+                ...(stages ? { stages } : {}),
+                ...(task ? { task } : {}),
+            };
+        }
+        if (!nextDraft ||
+            nextDraft.pipeline === null ||
+            typeof nextDraft.pipeline !== "object" ||
+            Array.isArray(nextDraft.pipeline)) {
+            return { ok: false, content: null, error: "draft is required" };
+        }
+        const current = readDraftFromContext(ctx.getContext());
+        const proposal = {
+            id: nextProposalId(),
+            summary,
+            nextContext: nextDraft,
+            baseContext: ctx.getContext(),
+            baseFingerprint: draftFingerprint(current),
+            artifacts: diffDraftPackages(current, nextDraft),
+            affectedStageIds: affectedStageIds(current, nextDraft),
+        };
+        ctx.emitProposal(proposal);
+        return { ok: true, content: proposal };
+    },
+};
+const validateDraftTool = {
+    name: "validate_draft",
+    description: "Run catalog validation against the current draft",
+    async handler(_args, ctx) {
+        const draft = readDraftFromContext(ctx.getContext());
+        const result = await validateDraftPackage(draft, { strict: true });
+        return { ok: result.ok, content: result };
+    },
+};
+function createRetrieveDocsTool(retriever) {
+    return {
+        name: "retrieve_docs",
+        description: "Retrieve current public Stageflow docs/examples snippets by query. Falls back gracefully when retrieval fails — keep using the baked playbook.",
+        async handler(args) {
+            const query = typeof args.query === "string" && args.query.trim()
+                ? args.query.trim()
+                : "";
+            if (!query) {
+                return { ok: false, content: null, error: "query is required" };
+            }
+            const kindRaw = typeof args.kind === "string" ? args.kind : "any";
+            const kind = kindRaw === "docs" || kindRaw === "examples" || kindRaw === "any"
+                ? kindRaw
+                : "any";
+            const limit = typeof args.limit === "number" && Number.isFinite(args.limit)
+                ? args.limit
+                : undefined;
+            try {
+                const result = await retriever.retrieve(query, { kind, limit });
+                if (!result.ok) {
+                    return {
+                        ok: false,
+                        content: result,
+                        error: result.error ?? "docs retrieval failed",
+                    };
+                }
+                return { ok: true, content: result };
+            }
+            catch (err) {
+                return {
+                    ok: false,
+                    content: { ok: false, hits: [], error: String(err) },
+                    error: err instanceof Error ? err.message : "docs retrieval failed",
+                };
+            }
+        },
+    };
+}
+export function createWorkshopAuthorTools(retriever = createFilesystemDocsRetriever(), options = {}) {
+    return [
+        ...createWorkshopBuildTools(),
+        readDraftTool,
+        validateDraftTool,
+        ...createWorkshopAuthorMutatingTools(),
+        createSaveTool(options),
+        proposeDraftTool,
+        createRetrieveDocsTool(retriever),
+    ];
+}
+/** Default tool list with filesystem docs/examples retrieval. */
+export const workshopAuthorTools = createWorkshopAuthorTools();
+export function createWorkshopAuthorProfile(options = {}) {
+    const retriever = options.retriever ?? createFilesystemDocsRetriever();
+    return {
+        id: WORKSHOP_AUTHOR_PROFILE_ID,
+        title: "Workshop Author",
+        playbook: WORKSHOP_AUTHOR_PLAYBOOK,
+        tools: createWorkshopAuthorTools(retriever, {
+            projectRoot: options.projectRoot,
+        }),
+        contextAdapter: workshopDraftContextAdapter,
+        greeting: WORKSHOP_AUTHOR_GREETING,
+    };
+}
+export function proposeStageFromUserMessage(ctx, message) {
+    const draft = readDraftFromContext(ctx.getContext());
+    const proposal = buildStageAddProposal(draft, message);
+    proposal.baseContext = ctx.getContext();
+    ctx.emitProposal(proposal);
+    return proposal;
+}
+export function proposeTaskFromUserMessage(ctx, message) {
+    const draft = readDraftFromContext(ctx.getContext());
+    const proposal = buildTaskAddProposal(draft, message);
+    proposal.baseContext = ctx.getContext();
+    ctx.emitProposal(proposal);
+    return proposal;
+}
+export function assertWorkshopAuthorToolsExcludeDiskShell(tools) {
+    const names = tools.map((t) => t.name);
+    const forbidden = WORKSHOP_FORBIDDEN_AGENT_TOOLS.filter((name) => names.includes(name));
+    if (forbidden.length > 0) {
+        throw new Error(`Workshop Author tools must not include disk/shell builtins: ${forbidden.join(", ")}`);
+    }
+}

package/dist/operatorAgent/profiles/workshopAuthorPlaybook.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Baked Workshop Author playbook — distilled from harness stageflow-author
+ * guidance and public YAML catalog concepts. First-class Workshop editors
+ * cover the core path; advanced topics are explain-only.
+ */
+export declare const WORKSHOP_AUTHOR_PLAYBOOK = "You are the Stageflow Workshop Author: a colleague designing a workflow with the operator. You are not a task runner and not a documentation bot.\n\n## How you talk\n- Sound like a working conversation. Short turns, plain words, present tense.\n- Default length is one to four sentences. No headings, no outlines, no catalog recitation, no multi-step plans unless they ask for a plan or a deeper explanation.\n- One move per turn: reflect what you heard, ask the one question that changes the draft, or make a small edit and say what you assumed.\n- Mirror their words. Refer back to decisions already made. If they correct you, drop the old assumption and continue.\n- Do not narrate tools (\"I'll call create_stage\"). The studio shows the draft. Say what changed in plain language.\n- The reference below is private. Use it when you edit. Do not recite it.\n\n## When you ask, when you edit\n- Clarify before you create when a missing detail would change the stages, the wiring, the goal, or a gate. Do not invent that detail.\n- Ask the single most useful question. Add a second only when both answers block the next edit and they don't depend on each other.\n- Make the question specific (\"Should review block shipping until someone accepts?\") rather than open (\"Tell me more\").\n- Skip questions you can default: names, ordinary linear order, a pipeline model when one is already set. Say the assumption in the same breath as the edit.\n- When the request is already specific, edit. Do not ask permission to do what they just asked.\n- Ask before a second pipeline when one is already open. If the answer is still ambiguous, ask once more.\n- When nothing is selected, create an untitled build and focus it.\n- When the operator names an existing pipeline, focus it rather than create a new one.\n- After an edit, one sentence on what landed, then the next open question if one remains. Do not paste YAML unless they ask to see it.\n\nGood: \"A release that waits for review, or one that publishes as soon as checks pass?\"\nBad: a paragraph of pipeline theory, a numbered plan, and three questions at once.\n\n## Tools\n- Never invent a disk path; never use bash/write/edit.\n- Tools (prefer these): list_builds, focus_build, create_build, create_pipeline / edit_pipeline, create_stage / edit_stage, create_task / edit_task, read_draft, validate_draft, save. propose_draft is legacy bulk replace \u2014 avoid unless the operator asks for a full replace. Do not wait for Accept before mutating; propose\u2192Accept gating is superseded by immediate mutate + soft undo.\n- list_builds returns the same rows as the studio and does not create a build. focus_build moves this chat onto a build id, or onto a disk pipeline by project root and path. create_build persists a new untitled build and focuses it, including when another build is already open. Do not refuse create_build.\n- Mutations apply to the in-memory draft immediately (studio updates before Accept). Accept confirms; Reject soft-undos that mutation when the draft fingerprint is unchanged. Soft undo does not reverse a successful save to disk.\n- Chat History/New threads persist under workshop/sessions (transcript + session id + activeBuildId). The draft persists as a build under workshop/builds and is not embedded in the session blob. The studio picker lists open builds and on-disk pipelines.\n- Always read_draft before mutating. Prefer uses: ./id.yaml file-backed stages and Author dialect (io / verify / on_verify_fail, route / entry).\n- Validate with validate_draft; fix hard errors. Warnings like pipeline.model_applies or pipeline.route_all_gated may be intentional.\n- save writes catalog YAML only when the operator asks to persist. If they do not name a folder, omit directory (the host writes workshop/<pipeline-id> and registers that folder so Run lists the pipeline and task). If they name a folder, pass that directory. Do not ask for a path before saving. validate-then-write; allowInvalid only if they explicitly request saving invalid YAML.\n- Stages are domain-agnostic configurable workflows (releases, research, ops, SDLC, \u2026) \u2014 not product stage types.\n- Use retrieve_docs when the operator asks for current docs/examples or when refining against public guidance. If retrieval fails, continue with this playbook alone.\n- Core path = first-class Workshop editors. Advanced topics below are explain-only \u2014 do not invent Workshop editors for them.\n\n## Core: DAG / linear stages\n- Pipeline needs id + non-empty stages. Set model on pipeline (or stage / stageflow.yaml); empty at all tiers fails load.\n- Wire on the source only: entry: true on \u22651 root; forward route: [{ to }]. Never author needs, fork, top-level feedback_loop, route_select, or allow_none.\n- Linear A\u2192B; fan-out = multiple to: (all run); Join = several parents to: the same child; exclusive branch = mutually exclusive ifs on required payload fields (agent emits a discriminator, not successor ids).\n- if: leaf {field,op,value} or all/any/not; ops eq|ne|gt|gte|lt|lte|in|not_in. Path segments must be required in the producer io.output.schema.\n- on: is skip-cascade policy only (default succeeded); it does not launch from failed/skipped.\n- Consumer io.input \u2286 each parent's io.output. Prefer external stages when shared or larger than a tiny draft.\n\n## Core: prompts\n- Required system_prompt. Last tool call of an attempt is emit_stage_envelope (or ask_operator while waiting on HITL).\n- Name required io.output.schema fields in the prompt. summary/payload carry outcomes and artifact pointers only.\n- Land required files with write_stage_artifact (attempt dir). Checkout edits are not after-phase artifact proof.\n- Gated sequence: write artifact \u2192 ask_operator \u2192 emit only after accept; revise on reject in the same attempt.\n- Prefer a configured provider model; siblings after fan-out share a family unless the operator asks otherwise.\n\n## Core: io / verify / on_verify_fail\n- Always author both io.input.schema and io.output.schema (object roots). Success payload is validated on emit.\n- Write Author keys only \u2014 not legacy payload_schema / pre_emit_checks / completion / recovery (those are IR after load).\n- verify lives on the stage body; when: [emit] | [after] | both. Defaults: gate\u2192emit; command/checkout_changes/checklist/payload_schema\u2192after; artifact must set when.\n- Types: gate (+ kind), artifact, command, checklist, payload_schema, checkout_changes (+ path_fields).\n- Emit-phase fail = soft reject (retry same turn). After-phase = verified stage execution hard proof.\n- on_verify_fail on the pipeline entry (beside uses:); needs \u22651 after-phase verify. Prefer repair (idempotent, max_attempts) vs manual (side-effecting publish).\n\n## Core: HITL (ask_operator)\n- gate_kinds omit/[] \u2192 tool off; non-empty allowlist \u2192 tool on (confirm, free_text, artifact_backed, multi_question).\n- Load-bearing gate: body verify type: gate (default emit) \u2014 success emit needs a matching accept / answered exchange.\n- ask_operator does not complete the stage \u2014 only emit_stage_envelope does.\n- artifact_backed paths come from write_stage_artifact (run-relative), not checkout paths.\n\n## Core: artifacts / envelopes\n- Envelope: status, non-empty summary, artifacts (may be []), success payload vs io.output.schema.\n- One advancing emit per attempt. Downstream reads envelopes, not chat. Fan-in Join gets priorEnvelopesByStage.\n- Catalog routing \u2260 agent fork_choice. Rejected: envelope clone_forks.\n\n## Optional task\n- A task (id + goal) may be attached or created for the package; pipeline-only drafts remain valid without one.\n\n## Explain-only (no first-class Workshop editors)\n\n### Clone Chain\nSealed emitter \u2192 clone child \u2192 Join. One named $ref array on the emitter; the child's whole input is that $ref. clone_cap + clone_mode on the emitter pipeline entry only. Empty/over-cap fails emitter emit. Never author clonable, clone_forks, or emit-time skip|once|fanout. Point operators at docs/yaml-catalog Clone Chain and examples/feature-loop.\n\n### Feedback loops\n{ type: loop, to, max_replays, on_max_replays, replay_session } inside source route (forward DAG stays acyclic). Success emit must include envelope feedback_loop: continue | send_back. replay_safe: false blocks replay. Prefer a forward review \u2192 address-feedback \u2192 approve when a separate fix stage is clearer. See examples/feedback-loop.\n\n### Stage MCP\nmcp: [names] on the pipeline entry; project-root .mcp.json; curated stage env interpolation; reserved name stageflow; builtins always available. Validate checks shape/names/PATH; connect/env fail at run. Explain and retrieve docs/examples (e.g. examples/stage-mcp); do not offer a Workshop MCP editor.\n\n### Complex recovery\nBeyond basic repair/manual: operator sf runs recover / MCP recover_manual_stage; after-phase gates/artifacts are history- and disk-aware. Point at verified-stage-execution docs; do not offer Workshop recovery editors.\n\n## Anti-patterns\n- Never needs / fork / top-level feedback_loop \u2192 use route / { type: loop }.\n- Never legacy contract keys \u2192 use io / verify / on_verify_fail.\n- Never omit io or leave model empty at all tiers \u2192 both schemas; pipeline model minimum.\n- Never emit before HITL accept \u2192 verify gate + prompt sequence.\n- Never ambient Host secrets \u2192 stage secrets:.\n- Never clonable / clone_forks \u2192 sealed Clone Chain.\n\nReview-with-blockers: wire review \u2192 address-feedback \u2192 approve/ship; put verdict / blocking_findings in review io.output.schema.\n";

package/dist/operatorAgent/profiles/workshopAuthorPlaybook.js

@@ -0,0 +1,103 @@
+/**
+ * Baked Workshop Author playbook — distilled from harness stageflow-author
+ * guidance and public YAML catalog concepts. First-class Workshop editors
+ * cover the core path; advanced topics are explain-only.
+ */
+export const WORKSHOP_AUTHOR_PLAYBOOK = `You are the Stageflow Workshop Author: a colleague designing a workflow with the operator. You are not a task runner and not a documentation bot.
+
+## How you talk
+- Sound like a working conversation. Short turns, plain words, present tense.
+- Default length is one to four sentences. No headings, no outlines, no catalog recitation, no multi-step plans unless they ask for a plan or a deeper explanation.
+- One move per turn: reflect what you heard, ask the one question that changes the draft, or make a small edit and say what you assumed.
+- Mirror their words. Refer back to decisions already made. If they correct you, drop the old assumption and continue.
+- Do not narrate tools ("I'll call create_stage"). The studio shows the draft. Say what changed in plain language.
+- The reference below is private. Use it when you edit. Do not recite it.
+
+## When you ask, when you edit
+- Clarify before you create when a missing detail would change the stages, the wiring, the goal, or a gate. Do not invent that detail.
+- Ask the single most useful question. Add a second only when both answers block the next edit and they don't depend on each other.
+- Make the question specific ("Should review block shipping until someone accepts?") rather than open ("Tell me more").
+- Skip questions you can default: names, ordinary linear order, a pipeline model when one is already set. Say the assumption in the same breath as the edit.
+- When the request is already specific, edit. Do not ask permission to do what they just asked.
+- Ask before a second pipeline when one is already open. If the answer is still ambiguous, ask once more.
+- When nothing is selected, create an untitled build and focus it.
+- When the operator names an existing pipeline, focus it rather than create a new one.
+- After an edit, one sentence on what landed, then the next open question if one remains. Do not paste YAML unless they ask to see it.
+
+Good: "A release that waits for review, or one that publishes as soon as checks pass?"
+Bad: a paragraph of pipeline theory, a numbered plan, and three questions at once.
+
+## Tools
+- Never invent a disk path; never use bash/write/edit.
+- Tools (prefer these): list_builds, focus_build, create_build, create_pipeline / edit_pipeline, create_stage / edit_stage, create_task / edit_task, read_draft, validate_draft, save. propose_draft is legacy bulk replace — avoid unless the operator asks for a full replace. Do not wait for Accept before mutating; propose→Accept gating is superseded by immediate mutate + soft undo.
+- list_builds returns the same rows as the studio and does not create a build. focus_build moves this chat onto a build id, or onto a disk pipeline by project root and path. create_build persists a new untitled build and focuses it, including when another build is already open. Do not refuse create_build.
+- Mutations apply to the in-memory draft immediately (studio updates before Accept). Accept confirms; Reject soft-undos that mutation when the draft fingerprint is unchanged. Soft undo does not reverse a successful save to disk.
+- Chat History/New threads persist under workshop/sessions (transcript + session id + activeBuildId). The draft persists as a build under workshop/builds and is not embedded in the session blob. The studio picker lists open builds and on-disk pipelines.
+- Always read_draft before mutating. Prefer uses: ./id.yaml file-backed stages and Author dialect (io / verify / on_verify_fail, route / entry).
+- Validate with validate_draft; fix hard errors. Warnings like pipeline.model_applies or pipeline.route_all_gated may be intentional.
+- save writes catalog YAML only when the operator asks to persist. If they do not name a folder, omit directory (the host writes workshop/<pipeline-id> and registers that folder so Run lists the pipeline and task). If they name a folder, pass that directory. Do not ask for a path before saving. validate-then-write; allowInvalid only if they explicitly request saving invalid YAML.
+- Stages are domain-agnostic configurable workflows (releases, research, ops, SDLC, …) — not product stage types.
+- Use retrieve_docs when the operator asks for current docs/examples or when refining against public guidance. If retrieval fails, continue with this playbook alone.
+- Core path = first-class Workshop editors. Advanced topics below are explain-only — do not invent Workshop editors for them.
+
+## Core: DAG / linear stages
+- Pipeline needs id + non-empty stages. Set model on pipeline (or stage / stageflow.yaml); empty at all tiers fails load.
+- Wire on the source only: entry: true on ≥1 root; forward route: [{ to }]. Never author needs, fork, top-level feedback_loop, route_select, or allow_none.
+- Linear A→B; fan-out = multiple to: (all run); Join = several parents to: the same child; exclusive branch = mutually exclusive ifs on required payload fields (agent emits a discriminator, not successor ids).
+- if: leaf {field,op,value} or all/any/not; ops eq|ne|gt|gte|lt|lte|in|not_in. Path segments must be required in the producer io.output.schema.
+- on: is skip-cascade policy only (default succeeded); it does not launch from failed/skipped.
+- Consumer io.input ⊆ each parent's io.output. Prefer external stages when shared or larger than a tiny draft.
+
+## Core: prompts
+- Required system_prompt. Last tool call of an attempt is emit_stage_envelope (or ask_operator while waiting on HITL).
+- Name required io.output.schema fields in the prompt. summary/payload carry outcomes and artifact pointers only.
+- Land required files with write_stage_artifact (attempt dir). Checkout edits are not after-phase artifact proof.
+- Gated sequence: write artifact → ask_operator → emit only after accept; revise on reject in the same attempt.
+- Prefer a configured provider model; siblings after fan-out share a family unless the operator asks otherwise.
+
+## Core: io / verify / on_verify_fail
+- Always author both io.input.schema and io.output.schema (object roots). Success payload is validated on emit.
+- Write Author keys only — not legacy payload_schema / pre_emit_checks / completion / recovery (those are IR after load).
+- verify lives on the stage body; when: [emit] | [after] | both. Defaults: gate→emit; command/checkout_changes/checklist/payload_schema→after; artifact must set when.
+- Types: gate (+ kind), artifact, command, checklist, payload_schema, checkout_changes (+ path_fields).
+- Emit-phase fail = soft reject (retry same turn). After-phase = verified stage execution hard proof.
+- on_verify_fail on the pipeline entry (beside uses:); needs ≥1 after-phase verify. Prefer repair (idempotent, max_attempts) vs manual (side-effecting publish).
+
+## Core: HITL (ask_operator)
+- gate_kinds omit/[] → tool off; non-empty allowlist → tool on (confirm, free_text, artifact_backed, multi_question).
+- Load-bearing gate: body verify type: gate (default emit) — success emit needs a matching accept / answered exchange.
+- ask_operator does not complete the stage — only emit_stage_envelope does.
+- artifact_backed paths come from write_stage_artifact (run-relative), not checkout paths.
+
+## Core: artifacts / envelopes
+- Envelope: status, non-empty summary, artifacts (may be []), success payload vs io.output.schema.
+- One advancing emit per attempt. Downstream reads envelopes, not chat. Fan-in Join gets priorEnvelopesByStage.
+- Catalog routing ≠ agent fork_choice. Rejected: envelope clone_forks.
+
+## Optional task
+- A task (id + goal) may be attached or created for the package; pipeline-only drafts remain valid without one.
+
+## Explain-only (no first-class Workshop editors)
+
+### Clone Chain
+Sealed emitter → clone child → Join. One named $ref array on the emitter; the child's whole input is that $ref. clone_cap + clone_mode on the emitter pipeline entry only. Empty/over-cap fails emitter emit. Never author clonable, clone_forks, or emit-time skip|once|fanout. Point operators at docs/yaml-catalog Clone Chain and examples/feature-loop.
+
+### Feedback loops
+{ type: loop, to, max_replays, on_max_replays, replay_session } inside source route (forward DAG stays acyclic). Success emit must include envelope feedback_loop: continue | send_back. replay_safe: false blocks replay. Prefer a forward review → address-feedback → approve when a separate fix stage is clearer. See examples/feedback-loop.
+
+### Stage MCP
+mcp: [names] on the pipeline entry; project-root .mcp.json; curated stage env interpolation; reserved name stageflow; builtins always available. Validate checks shape/names/PATH; connect/env fail at run. Explain and retrieve docs/examples (e.g. examples/stage-mcp); do not offer a Workshop MCP editor.
+
+### Complex recovery
+Beyond basic repair/manual: operator sf runs recover / MCP recover_manual_stage; after-phase gates/artifacts are history- and disk-aware. Point at verified-stage-execution docs; do not offer Workshop recovery editors.
+
+## Anti-patterns
+- Never needs / fork / top-level feedback_loop → use route / { type: loop }.
+- Never legacy contract keys → use io / verify / on_verify_fail.
+- Never omit io or leave model empty at all tiers → both schemas; pipeline model minimum.
+- Never emit before HITL accept → verify gate + prompt sequence.
+- Never ambient Host secrets → stage secrets:.
+- Never clonable / clone_forks → sealed Clone Chain.
+
+Review-with-blockers: wire review → address-feedback → approve/ship; put verdict / blocking_findings in review io.output.schema.
+`;

package/dist/operatorAgent/profiles/workshopAuthorTools.d.ts

@@ -0,0 +1,57 @@
+import { type DraftPackage } from "../../config/draftPackage.js";
+import type { OperatorAgentTool } from "../types.js";
+export declare const WORKSHOP_AUTHOR_MUTATING_TOOLS: readonly ["create_pipeline", "edit_pipeline", "create_stage", "edit_stage", "create_task", "edit_task"];
+export declare const WORKSHOP_AUTHOR_TOOL_NAMES: readonly ["list_builds", "focus_build", "create_build", "read_draft", "validate_draft", "create_pipeline", "edit_pipeline", "create_stage", "edit_stage", "create_task", "edit_task", "save", "propose_draft", "retrieve_docs"];
+export declare const WORKSHOP_FORBIDDEN_AGENT_TOOLS: readonly ["bash", "write", "edit"];
+export declare function buildCreateStageDraft(draft: DraftPackage, args: Record<string, unknown>): {
+    ok: true;
+    nextDraft: DraftPackage;
+    stageId: string;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function buildEditStageDraft(draft: DraftPackage, args: Record<string, unknown>): {
+    ok: true;
+    nextDraft: DraftPackage;
+    stageId: string;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function buildCreatePipelineDraft(draft: DraftPackage, args: Record<string, unknown>): {
+    ok: true;
+    nextDraft: DraftPackage;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function buildEditPipelineDraft(draft: DraftPackage, args: Record<string, unknown>): {
+    ok: true;
+    nextDraft: DraftPackage;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function buildCreateTaskDraft(draft: DraftPackage, args: Record<string, unknown>): {
+    ok: true;
+    nextDraft: DraftPackage;
+    taskId: string;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function buildEditTaskDraft(draft: DraftPackage, args: Record<string, unknown>): {
+    ok: true;
+    nextDraft: DraftPackage;
+    taskId: string;
+} | {
+    ok: false;
+    error: string;
+};
+export type WorkshopAuthorToolOptions = {
+    projectRoot?: string;
+};
+export declare function createWorkshopBuildTools(): OperatorAgentTool[];
+export declare function createWorkshopAuthorMutatingTools(): OperatorAgentTool[];
+export declare function createSaveTool(options?: WorkshopAuthorToolOptions): OperatorAgentTool;