@yycholla/pi-dynamic-workflows 3.3.0

package/dist/workflow-paths.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Filesystem layout for pi-dynamic-workflows state.
+ *
+ * New writes live under the user's workflow home so projects do not get
+ * scattered `.pi/workflows` directories. Project-scoped state is still isolated
+ * by a stable cwd-derived namespace.
+ */
+export declare const WORKFLOW_HOME_RELATIVE_DIR = ".pi/workflows";
+export declare const WORKFLOW_PROJECTS_SUBDIR = "projects";
+export interface WorkflowProjectPaths {
+    key: string;
+    rootDir: string;
+    runsDir: string;
+    savedDir: string;
+    settingsPath: string;
+    legacyRunsDir: string;
+    legacySavedDir: string;
+}
+export declare function workflowHomeDir(): string;
+export declare function workflowUserSavedDir(): string;
+export declare function workflowProjectKey(cwd: string): string;
+export declare function workflowProjectPaths(cwd: string): WorkflowProjectPaths;

package/dist/workflow-paths.js

@@ -0,0 +1,46 @@
+/**
+ * Filesystem layout for pi-dynamic-workflows state.
+ *
+ * New writes live under the user's workflow home so projects do not get
+ * scattered `.pi/workflows` directories. Project-scoped state is still isolated
+ * by a stable cwd-derived namespace.
+ */
+import { createHash } from "node:crypto";
+import { homedir } from "node:os";
+import { basename, join, resolve } from "node:path";
+import { WORKFLOW_RUNS_DIR, WORKFLOW_SAVED_DIR } from "./config.js";
+export const WORKFLOW_HOME_RELATIVE_DIR = ".pi/workflows";
+export const WORKFLOW_PROJECTS_SUBDIR = "projects";
+export function workflowHomeDir() {
+    return join(homedir(), WORKFLOW_HOME_RELATIVE_DIR);
+}
+export function workflowUserSavedDir() {
+    return join(workflowHomeDir(), "saved");
+}
+export function workflowProjectKey(cwd) {
+    const projectPath = resolve(cwd);
+    const slug = sanitizePathSegment(basename(projectPath) || "project");
+    const hash = createHash("sha256").update(projectPath).digest("hex").slice(0, 12);
+    return `${slug}-${hash}`;
+}
+export function workflowProjectPaths(cwd) {
+    const key = workflowProjectKey(cwd);
+    const rootDir = join(workflowHomeDir(), WORKFLOW_PROJECTS_SUBDIR, key);
+    return {
+        key,
+        rootDir,
+        runsDir: join(rootDir, "runs"),
+        savedDir: join(rootDir, "saved"),
+        settingsPath: join(rootDir, "settings.json"),
+        legacyRunsDir: resolve(cwd, WORKFLOW_RUNS_DIR),
+        legacySavedDir: resolve(cwd, WORKFLOW_SAVED_DIR),
+    };
+}
+function sanitizePathSegment(value) {
+    const sanitized = value
+        .toLowerCase()
+        .replace(/[^a-z0-9._-]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 48);
+    return sanitized || "project";
+}

package/dist/workflow-release-gate.d.ts

@@ -0,0 +1,39 @@
+import { WorkflowReleaseDiagnosticCode } from "./enums.js";
+import { type WorkflowAuthoringCoverageEntry } from "./workflow-authoring-coverage.js";
+import { type CAPABILITY_PUBLICATION_PATHS } from "./workflow-authoring-reference.js";
+import { type WorkflowCapabilityDefinition } from "./workflow-capability-contract.js";
+/** Re-exported stable diagnostic codes for release automation. */
+export { WorkflowReleaseDiagnosticCode } from "./enums.js";
+/** One actionable release alignment error or warning. */
+export interface WorkflowReleaseDiagnostic {
+    code: WorkflowReleaseDiagnosticCode;
+    severity: "error" | "warning";
+    subject: string;
+    message: string;
+}
+type PublicationPath = (typeof CAPABILITY_PUBLICATION_PATHS)[number];
+/** Inputs and test overrides for the model-free workflow release gate. */
+export interface WorkflowReleaseCheckOptions {
+    root: string;
+    definition?: WorkflowCapabilityDefinition;
+    extensionVersion?: string;
+    skillVersion?: string;
+    publishableFiles: readonly string[];
+    publicationOverrides?: Readonly<Partial<Record<PublicationPath, string>>>;
+    contextMeasurement?: string;
+    guidanceBaseline?: string;
+    authoringCoverage?: readonly WorkflowAuthoringCoverageEntry[];
+    guidanceOverrides?: Readonly<Record<string, string>>;
+}
+/** Package-relative generated hash baseline for compact and detailed guidance. */
+export declare const WORKFLOW_GUIDANCE_BASELINE_PATH = "docs/workflow-guidance-baseline.json";
+/** Skill files that must be present in the publishable npm package. */
+export declare const REQUIRED_WORKFLOW_PACKAGE_RESOURCES: readonly ["skills/workflow-authoring/SKILL.md", ...string[]];
+/** Render deterministic hashes for provider-visible and on-demand guidance surfaces. */
+export declare function renderWorkflowGuidanceBaseline(root: string): string;
+/** Refresh the committed guidance hash baseline under root. */
+export declare function writeWorkflowGuidanceBaseline(root: string): void;
+/** Parse publishable paths from `npm pack --dry-run --json` without trusting external JSON shapes. */
+export declare function parseNpmPackFilePaths(output: string): string[];
+/** Return every model-free contract, package, documentation, and guidance alignment diagnostic. */
+export declare function checkWorkflowRelease(options: WorkflowReleaseCheckOptions): WorkflowReleaseDiagnostic[];

package/dist/workflow-release-gate.js

@@ -0,0 +1,309 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, normalize, relative } from "node:path";
+import packageJson from "../package.json" with { type: "json" };
+import { CapabilityClassification, CapabilitySupport, DiscoveryPlacement, WorkflowAuthoringProtection, WorkflowReleaseDiagnosticCode, } from "./enums.js";
+import { WORKFLOW_AUTHORING_COVERAGE, WORKFLOW_AUTHORING_FROZEN_FILES, WORKFLOW_AUTHORING_PATTERN_IDS, WORKFLOW_AUTHORING_RECIPE_IDS, WORKFLOW_COMPREHENSION_SCENARIO_IDS, } from "./workflow-authoring-coverage.js";
+import { checkWorkflowCapabilityPublications, } from "./workflow-authoring-reference.js";
+import { WORKFLOW_CAPABILITY_DEFINITION } from "./workflow-capability-contract.js";
+import { checkWorkflowContextMeasurement, WORKFLOW_CONTEXT_MEASUREMENT_PATH } from "./workflow-context-measurement.js";
+import { createWorkflowTool } from "./workflow-tool.js";
+/** Re-exported stable diagnostic codes for release automation. */
+export { WorkflowReleaseDiagnosticCode } from "./enums.js";
+const SKILL_ROOT = "skills/workflow-authoring";
+/** Package-relative generated hash baseline for compact and detailed guidance. */
+export const WORKFLOW_GUIDANCE_BASELINE_PATH = "docs/workflow-guidance-baseline.json";
+const FOCUSED_REFERENCES = [
+    "capabilities",
+    "capability-details",
+    "runtime",
+    "helpers",
+    "common-helpers",
+    "quality-helpers",
+    "retry-helper",
+    "specialized-helpers",
+    "lifecycle",
+    "versions",
+    "pattern-selection",
+    "focused-recipes",
+    "registry-ownership",
+    "review",
+    "debugging",
+];
+const PATTERNS = [
+    "classify-and-act",
+    "fan-out-and-synthesize",
+    "adversarial-verification",
+    "generate-and-filter",
+    "tournament",
+    "loop-until-done",
+];
+const RECIPES = ["phased-budgets", "saved-nested-workflows", "bounded-semantic-retry", "structured-output"];
+/** Skill files that must be present in the publishable npm package. */
+export const REQUIRED_WORKFLOW_PACKAGE_RESOURCES = [
+    `${SKILL_ROOT}/SKILL.md`,
+    ...FOCUSED_REFERENCES.map((name) => `${SKILL_ROOT}/references/${name}.md`),
+    ...PATTERNS.map((name) => `${SKILL_ROOT}/examples/${name}.js`),
+    ...RECIPES.map((name) => `${SKILL_ROOT}/examples/${name}.js`),
+];
+function diagnostic(code, subject, message, severity = "error") {
+    return { code, severity, subject, message };
+}
+function skillVersion(root) {
+    const skill = readFileSync(join(root, SKILL_ROOT, "SKILL.md"), "utf8");
+    return /^\s{2}version:\s*["']?([^"'\s]+)["']?\s*$/m.exec(skill)?.[1] ?? null;
+}
+function anchorExists(markdown, anchor) {
+    if (markdown.includes(`<a id="${anchor}"></a>`))
+        return true;
+    return markdown
+        .split("\n")
+        .filter((line) => /^#{1,6} /.test(line))
+        .map((line) => line
+        .replace(/^#{1,6} /, "")
+        .toLowerCase()
+        .replace(/[^a-z0-9 -]/g, "")
+        .trim()
+        .replace(/ +/g, "-"))
+        .includes(anchor);
+}
+function validateVersions(definition, extensionVersion, installedSkillVersion) {
+    const diagnostics = [];
+    const versions = [
+        ["contract extension", definition.versions.extension],
+        ["contract content", definition.versions.content.version],
+        ["installed skill", installedSkillVersion],
+    ];
+    for (const [subject, actual] of versions) {
+        if (actual !== extensionVersion) {
+            diagnostics.push(diagnostic(WorkflowReleaseDiagnosticCode.INCOMPATIBLE_VERSION, subject, `${subject} version ${actual ?? "<missing>"} must match extension version ${extensionVersion}.`));
+        }
+    }
+    if (definition.versions.format.kind !== "present-at" || !/^1(?:\.|$)/.test(definition.versions.format.version)) {
+        diagnostics.push(diagnostic(WorkflowReleaseDiagnosticCode.INCOMPATIBLE_VERSION, "contract format", `Contract format ${definition.versions.format.version} is incompatible with supported format major 1.`));
+    }
+    return diagnostics;
+}
+function validateCapabilityLinks(root, definition) {
+    const diagnostics = [];
+    for (const capability of definition.capabilities) {
+        if (capability.support === CapabilitySupport.SUPPORTED &&
+            capability.discovery !== DiscoveryPlacement.NONE &&
+            capability.behaviorEvidence.length === 0) {
+            diagnostics.push(diagnostic(WorkflowReleaseDiagnosticCode.MISSING_BEHAVIOR_EVIDENCE, capability.id, `Advertised capability ${capability.id} has no behavior-test evidence.`));
+        }
+        for (const evidence of capability.behaviorEvidence) {
+            if (!existsSync(join(root, evidence))) {
+                diagnostics.push(diagnostic(WorkflowReleaseDiagnosticCode.UNRESOLVED_BEHAVIOR_EVIDENCE, evidence, `Capability ${capability.id} references missing behavior test ${evidence}.`));
+            }
+        }
+        if (capability.staticReference) {
+            const { path, anchor } = capability.staticReference;
+            const absolute = join(root, path);
+            const subject = `${path}#${anchor}`;
+            if (!existsSync(absolute) || !anchorExists(readFileSync(absolute, "utf8"), anchor)) {
+                diagnostics.push(diagnostic(WorkflowReleaseDiagnosticCode.BROKEN_CONTRACT_REFERENCE, subject, `Capability ${capability.id} references unresolved installed documentation ${subject}.`));
+            }
+        }
+    }
+    return diagnostics;
+}
+function validateAuthoringCoverage(root, definition, coverage, guidanceOverrides = {}) {
+    const expectedIds = [
+        ...definition.capabilities
+            .filter(({ discovery, support }) => discovery !== DiscoveryPlacement.NONE && support !== CapabilitySupport.INTERNAL)
+            .map(({ id }) => id),
+        ...WORKFLOW_AUTHORING_PATTERN_IDS,
+        ...WORKFLOW_AUTHORING_RECIPE_IDS,
+    ];
+    const observed = new Set(coverage.map(({ id }) => id));
+    const diagnostics = expectedIds
+        .filter((id) => !observed.has(id))
+        .map((id) => diagnostic(WorkflowReleaseDiagnosticCode.MISSING_AUTHORING_COVERAGE, id, `Stable workflow authoring surface ${id} is absent from the capability coverage manifest.`));
+    const knownScenarioIds = new Set(WORKFLOW_COMPREHENSION_SCENARIO_IDS);
+    for (const entry of coverage.filter(({ protection }) => protection === WorkflowAuthoringProtection.BEHAVIORALLY_COVERED)) {
+        if (entry.comprehensionScenarios.length === 0 ||
+            entry.comprehensionScenarios.some((scenarioId) => !knownScenarioIds.has(scenarioId))) {
+            diagnostics.push(diagnostic(WorkflowReleaseDiagnosticCode.UNKNOWN_COMPREHENSION_SCENARIO, entry.id, `Behaviorally covered authoring surface ${entry.id} references a missing comprehension scenario.`));
+        }
+    }
+    for (const entry of coverage.filter(({ protection }) => protection === WorkflowAuthoringProtection.GUIDANCE_FROZEN)) {
+        if (entry.protectedGuidance.length === 0) {
+            diagnostics.push(diagnostic(WorkflowReleaseDiagnosticCode.UNPROTECTED_AUTHORING_GUIDANCE, entry.id, `Untested authoring surface ${entry.id} has no frozen guidance or routing pointer.`));
+            continue;
+        }
+        const drifted = entry.protectedGuidance.find(({ path, anchor, requiredText }) => {
+            const absolute = join(root, path);
+            if (!existsSync(absolute) && guidanceOverrides[path] === undefined)
+                return true;
+            const source = guidanceOverrides[path] ?? readFileSync(absolute, "utf8");
+            return ((anchor !== undefined && !anchorExists(source, anchor)) ||
+                (requiredText !== undefined && !source.includes(requiredText)));
+        });
+        if (drifted) {
+            const absolute = join(root, drifted.path);
+            const source = !existsSync(absolute) && guidanceOverrides[drifted.path] === undefined
+                ? null
+                : (guidanceOverrides[drifted.path] ?? readFileSync(absolute, "utf8"));
+            const failedChecks = [];
+            if (source === null) {
+                failedChecks.push("protected file");
+            }
+            if (source !== null && drifted.anchor !== undefined && !anchorExists(source, drifted.anchor)) {
+                failedChecks.push("required anchor");
+            }
+            if (source !== null && drifted.requiredText !== undefined && !source.includes(drifted.requiredText)) {
+                failedChecks.push("required text");
+            }
+            diagnostics.push(diagnostic(WorkflowReleaseDiagnosticCode.PROTECTED_GUIDANCE_DRIFT, entry.id, `Protected guidance for ${entry.id} no longer matches the ${failedChecks.join(" and ")} in ${drifted.path}. Restore it to undo an accidental change. For an intentional change, inspect the coverage manifest and relevant behavioral/provider evidence before deliberately updating the corresponding anchor/text in src/workflow-authoring-coverage.ts. See CONTRIBUTING.md#protected-workflow-authoring-guidance.`));
+        }
+    }
+    return diagnostics;
+}
+function validateFrozenGuidanceFiles(root, guidanceOverrides = {}) {
+    return WORKFLOW_AUTHORING_FROZEN_FILES.flatMap(({ path, sha256: expected }) => {
+        const absolute = join(root, path);
+        if (!existsSync(absolute) && guidanceOverrides[path] === undefined) {
+            return [
+                diagnostic(WorkflowReleaseDiagnosticCode.PROTECTED_GUIDANCE_DRIFT, path, `Protected workflow-authoring file is missing: ${path}. Restore an accidental deletion. An intentional removal requires review of the coverage manifest and relevant behavioral/provider evidence, followed by deliberate updates to authoring coverage and package resources. See CONTRIBUTING.md#protected-workflow-authoring-guidance.`),
+            ];
+        }
+        const source = guidanceOverrides[path] ?? readFileSync(absolute, "utf8");
+        return sha256(source) === expected
+            ? []
+            : [
+                diagnostic(WorkflowReleaseDiagnosticCode.PROTECTED_GUIDANCE_DRIFT, path, `Protected workflow-authoring file changed: ${path}. Its SHA-256 is an explicit review checkpoint for guidance with partial behavioral coverage. Revert accidental changes. For an intentional change, inspect the coverage manifest and relevant behavioral tests, plus provider evidence when needed, then run npm run guidance:accept -- ${path}. This updates the matching sha256 in WORKFLOW_AUTHORING_FROZEN_FILES (src/workflow-authoring-coverage.ts). See CONTRIBUTING.md#protected-workflow-authoring-guidance.`),
+            ];
+    });
+}
+function validateToolInputs(definition) {
+    const { parameters } = createWorkflowTool();
+    const properties = isRecord(parameters) && isRecord(parameters.properties) ? parameters.properties : {};
+    const observed = new Set(Object.keys(properties));
+    const declared = new Set(definition.capabilities
+        .filter((capability) => capability.classification === CapabilityClassification.WORKFLOW_TOOL_INPUT)
+        .map((capability) => capability.label));
+    const diagnostics = [];
+    for (const name of declared) {
+        if (!observed.has(name)) {
+            diagnostics.push(diagnostic(WorkflowReleaseDiagnosticCode.TOOL_INPUT_MISMATCH, name, `Declared workflow-tool input ${name} is absent from the runtime schema.`));
+        }
+    }
+    for (const name of observed) {
+        if (!declared.has(name)) {
+            diagnostics.push(diagnostic(WorkflowReleaseDiagnosticCode.TOOL_INPUT_MISMATCH, name, `Runtime schema exposes undeclared workflow-tool input ${name}.`));
+        }
+    }
+    const tokenBudget = definition.capabilities.find((capability) => capability.classification === CapabilityClassification.WORKFLOW_TOOL_INPUT && capability.label === "tokenBudget");
+    const tokenBudgetSchema = properties.tokenBudget;
+    const observedTokenBudget = isRecord(tokenBudgetSchema) && typeof tokenBudgetSchema.description === "string"
+        ? tokenBudgetSchema.description
+        : "";
+    const contractCallsSoft = tokenBudget?.constraints.some((constraint) => /soft/i.test(constraint)) ?? false;
+    const contractCallsHard = tokenBudget?.constraints.some((constraint) => /hard/i.test(constraint)) ?? false;
+    const proseCallsSoft = /soft/i.test(observedTokenBudget);
+    const proseCallsHard = /hard/i.test(observedTokenBudget);
+    if ((contractCallsSoft && proseCallsHard) || (contractCallsHard && proseCallsSoft)) {
+        diagnostics.push(diagnostic(WorkflowReleaseDiagnosticCode.RUNTIME_CONSTRAINT_DISAGREEMENT, "tokenBudget", `Contract constraints and provider-visible tool prose disagree about whether tokenBudget is a soft or hard gate. Contract: ${tokenBudget?.constraints.join("; ")}. Tool prose: ${observedTokenBudget}`));
+    }
+    return diagnostics;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function sha256(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+/** Render deterministic hashes for provider-visible and on-demand guidance surfaces. */
+export function renderWorkflowGuidanceBaseline(root) {
+    const tool = createWorkflowTool();
+    const compact = JSON.stringify({
+        description: tool.description,
+        parameters: tool.parameters,
+        promptSnippet: tool.promptSnippet,
+        promptGuidelines: tool.promptGuidelines,
+    });
+    const detailedPaths = [
+        `${SKILL_ROOT}/SKILL.md`,
+        ...FOCUSED_REFERENCES.filter((name) => name !== "capabilities" && name !== "capability-details").map((name) => `${SKILL_ROOT}/references/${name}.md`),
+    ];
+    const detailed = detailedPaths.map((path) => `${path}\n${readFileSync(join(root, path), "utf8")}`).join("\n");
+    return `${JSON.stringify({
+        formatVersion: 1,
+        algorithm: "sha256",
+        surfaces: {
+            compactGuidance: sha256(compact),
+            detailedProse: sha256(detailed),
+        },
+    }, null, 2)}\n`;
+}
+/** Refresh the committed guidance hash baseline under root. */
+export function writeWorkflowGuidanceBaseline(root) {
+    writeFileSync(join(root, WORKFLOW_GUIDANCE_BASELINE_PATH), renderWorkflowGuidanceBaseline(root));
+}
+function validateGuidanceBaseline(root, actual) {
+    const committed = actual ?? readFileSync(join(root, WORKFLOW_GUIDANCE_BASELINE_PATH), "utf8");
+    if (committed === renderWorkflowGuidanceBaseline(root))
+        return [];
+    return [
+        diagnostic(WorkflowReleaseDiagnosticCode.NON_CONTRACTUAL_PROSE_DRIFT, WORKFLOW_GUIDANCE_BASELINE_PATH, `Compact guidance or detailed hand-written prose changed; review intent and refresh ${WORKFLOW_GUIDANCE_BASELINE_PATH} if intentional.`, "warning"),
+    ];
+}
+function validatePackage(root, publishableFiles) {
+    const diagnostics = [];
+    const files = new Set(publishableFiles);
+    for (const resource of REQUIRED_WORKFLOW_PACKAGE_RESOURCES) {
+        if (!files.has(resource)) {
+            diagnostics.push(diagnostic(WorkflowReleaseDiagnosticCode.MISSING_PACKAGE_RESOURCE, resource, `Publishable package omitted required workflow resource ${resource}.`));
+        }
+    }
+    for (const sourcePath of publishableFiles.filter((path) => path.startsWith(`${SKILL_ROOT}/`) && path.endsWith(".md"))) {
+        const source = readFileSync(join(root, sourcePath), "utf8");
+        for (const match of source.matchAll(/\[[^\]]+\]\(([^)#]+)(?:#([^)]+))?\)/g)) {
+            const target = normalize(join(dirname(sourcePath), match[1]));
+            const anchor = match[2];
+            const outsidePackage = relative(".", target).startsWith("..");
+            const targetMissing = !files.has(target);
+            const targetSource = !targetMissing && anchor ? readFileSync(join(root, target), "utf8") : null;
+            if (outsidePackage || targetMissing || (anchor && targetSource !== null && !anchorExists(targetSource, anchor))) {
+                const subject = `${sourcePath} -> ${target}${anchor ? `#${anchor}` : ""}`;
+                diagnostics.push(diagnostic(WorkflowReleaseDiagnosticCode.BROKEN_PACKAGE_LINK, subject, `Packaged workflow skill link does not resolve: ${subject}.`));
+            }
+        }
+    }
+    return diagnostics;
+}
+/** Parse publishable paths from `npm pack --dry-run --json` without trusting external JSON shapes. */
+export function parseNpmPackFilePaths(output) {
+    const parsed = JSON.parse(output);
+    if (!Array.isArray(parsed)) {
+        return [];
+    }
+    const first = parsed[0];
+    if (!isRecord(first) || !Array.isArray(first.files)) {
+        return [];
+    }
+    return first.files.flatMap((file) => (isRecord(file) && typeof file.path === "string" ? [file.path] : []));
+}
+/** Return every model-free contract, package, documentation, and guidance alignment diagnostic. */
+export function checkWorkflowRelease(options) {
+    const definition = options.definition ?? WORKFLOW_CAPABILITY_DEFINITION;
+    const extensionVersion = options.extensionVersion ?? packageJson.version;
+    const installedSkillVersion = options.skillVersion ?? skillVersion(options.root);
+    const diagnostics = [
+        ...validateVersions(definition, extensionVersion, installedSkillVersion),
+        ...validateCapabilityLinks(options.root, definition),
+        ...validateAuthoringCoverage(options.root, definition, options.authoringCoverage ?? WORKFLOW_AUTHORING_COVERAGE, options.guidanceOverrides),
+        ...validateFrozenGuidanceFiles(options.root, options.guidanceOverrides),
+        ...validateToolInputs(definition),
+        ...validatePackage(options.root, options.publishableFiles),
+        ...validateGuidanceBaseline(options.root, options.guidanceBaseline),
+    ];
+    for (const path of checkWorkflowCapabilityPublications(options.root, options.publicationOverrides)) {
+        diagnostics.push(diagnostic(WorkflowReleaseDiagnosticCode.STALE_GENERATED_SURFACE, path, `Generated workflow capability publication is stale: ${path}.`));
+    }
+    if (!checkWorkflowContextMeasurement(options.root, options.contextMeasurement)) {
+        diagnostics.push(diagnostic(WorkflowReleaseDiagnosticCode.STALE_GENERATED_SURFACE, WORKFLOW_CONTEXT_MEASUREMENT_PATH, `Generated workflow context measurement is stale: ${WORKFLOW_CONTEXT_MEASUREMENT_PATH}.`));
+    }
+    return diagnostics;
+}

package/dist/workflow-saved.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Save and load reusable workflow commands.
+ */
+import { type PersistenceFsLayer } from "./fs-persistence.js";
+export interface SavedWorkflow {
+    /** Command name (filename without extension). */
+    name: string;
+    /** Human-readable description. */
+    description: string;
+    /** The workflow script. */
+    script: string;
+    /** Optional parameter schema for parameterized workflows. */
+    parameters?: Record<string, {
+        type: string;
+        description?: string;
+        required?: boolean;
+        default?: unknown;
+    }>;
+    /** Where this workflow is saved. */
+    location: "project" | "user";
+    /** Full file path. */
+    path: string;
+    /** When it was saved. */
+    savedAt: string;
+}
+export interface WorkflowStorage {
+    /** Save a workflow. */
+    save(workflow: Omit<SavedWorkflow, "path" | "savedAt">, location?: "project" | "user"): SavedWorkflow;
+    /** Load a workflow by name. */
+    load(name: string): SavedWorkflow | null;
+    /** List all saved workflows. */
+    list(): SavedWorkflow[];
+    /** Delete a saved workflow. */
+    delete(name: string, location?: "project" | "user"): boolean;
+}
+export declare function isSafeSavedWorkflowName(name: string): boolean;
+export declare function assertSafeSavedWorkflowName(name: string): void;
+export declare function createWorkflowStorage(cwd: string, fsOverride?: Partial<PersistenceFsLayer>): WorkflowStorage;

package/dist/workflow-saved.js

@@ -0,0 +1,126 @@
+/**
+ * Save and load reusable workflow commands.
+ */
+import { join } from "node:path";
+import { ensureDir as ensureDirFs, listJsonFilesSafe, readJsonWithBackupRecovery, resolvePersistenceFs, unlinkIfExistsSafe, writeJsonAtomicWithBackup, } from "./fs-persistence.js";
+import { workflowProjectPaths, workflowUserSavedDir } from "./workflow-paths.js";
+export function isSafeSavedWorkflowName(name) {
+    return (name.length > 0 &&
+        name.length <= 128 &&
+        name.trim() === name &&
+        name !== "." &&
+        name !== ".." &&
+        !/[/\\\0]/.test(name));
+}
+export function assertSafeSavedWorkflowName(name) {
+    if (!isSafeSavedWorkflowName(name)) {
+        throw new Error("Saved workflow name must be a non-empty path-safe name without slashes.");
+    }
+}
+export function createWorkflowStorage(cwd, fsOverride) {
+    const fs = resolvePersistenceFs(fsOverride);
+    const paths = workflowProjectPaths(cwd);
+    const projectDir = paths.savedDir;
+    const legacyProjectDir = paths.legacySavedDir;
+    const userDir = workflowUserSavedDir();
+    const ensureDir = (dir) => ensureDirFs(fs, dir);
+    const workflowPath = (name, location) => {
+        assertSafeSavedWorkflowName(name);
+        const dir = location === "project" ? projectDir : userDir;
+        return join(dir, `${name}.json`);
+    };
+    const legacyProjectWorkflowPath = (name) => {
+        assertSafeSavedWorkflowName(name);
+        return join(legacyProjectDir, `${name}.json`);
+    };
+    // Same atomic-write-with-backup + corrupt-file recovery contract as
+    // run-persistence.ts (see fs-persistence.ts) — a saved workflow is a
+    // user-authored artifact just as worth protecting from a crash mid-write
+    // or a truncated file as a run's resumable state is.
+    const loadFromFile = (path, location) => {
+        const data = readJsonWithBackupRecovery(fs, path);
+        if (!data || typeof data !== "object" || !isSafeSavedWorkflowName(data.name ?? "")) {
+            return null;
+        }
+        return {
+            ...data,
+            location,
+            path,
+        };
+    };
+    return {
+        save(workflow, location = "project") {
+            assertSafeSavedWorkflowName(workflow.name);
+            const dir = location === "project" ? projectDir : userDir;
+            ensureDir(dir);
+            const path = workflowPath(workflow.name, location);
+            const saved = {
+                ...workflow,
+                location,
+                path,
+                savedAt: new Date().toISOString(),
+            };
+            writeJsonAtomicWithBackup(fs, path, saved);
+            return saved;
+        },
+        load(name) {
+            if (!isSafeSavedWorkflowName(name))
+                return null;
+            // Project takes precedence over user
+            const projectPath = workflowPath(name, "project");
+            const project = loadFromFile(projectPath, "project");
+            if (project)
+                return project;
+            const legacyProject = loadFromFile(legacyProjectWorkflowPath(name), "project");
+            if (legacyProject)
+                return legacyProject;
+            const userPath = workflowPath(name, "user");
+            return loadFromFile(userPath, "user");
+        },
+        list() {
+            const workflows = [];
+            const seen = new Set();
+            const addDir = (dir, location) => {
+                // A missing or unreadable directory (not yet created, deleted
+                // mid-race, permission-denied) degrades to "no files" here — same
+                // guard run-persistence.ts's list() uses — rather than throwing and
+                // taking down the whole listing over one bad storage location.
+                for (const file of listJsonFilesSafe(fs, dir)) {
+                    const wf = loadFromFile(join(dir, file), location);
+                    if (wf && !seen.has(wf.name)) {
+                        seen.add(wf.name);
+                        workflows.push(wf);
+                    }
+                }
+            };
+            // Priority order mirrors load(): project > legacy project > user.
+            addDir(projectDir, "project");
+            addDir(legacyProjectDir, "project");
+            addDir(userDir, "user");
+            return workflows.sort((a, b) => a.name.localeCompare(b.name));
+        },
+        delete(name, location) {
+            if (!isSafeSavedWorkflowName(name))
+                return false;
+            const locations = location ? [location] : ["project", "user"];
+            let deleted = false;
+            for (const loc of locations) {
+                const path = workflowPath(name, loc);
+                // Clean up the .bak sidecar too, mirroring run-persistence.ts's delete()
+                // (sidecar cleanup does not by itself count as "deleted the workflow").
+                unlinkIfExistsSafe(fs, `${path}.bak`);
+                if (unlinkIfExistsSafe(fs, path)) {
+                    deleted = true;
+                }
+                if (loc === "project") {
+                    const legacyPath = legacyProjectWorkflowPath(name);
+                    unlinkIfExistsSafe(fs, `${legacyPath}.bak`);
+                    if (unlinkIfExistsSafe(fs, legacyPath)) {
+                        deleted = true;
+                    }
+                }
+            }
+            return deleted;
+        },
+    };
+}

package/dist/workflow-settings.d.ts

@@ -0,0 +1,70 @@
+/**
+ * User-level settings for pi-dynamic-workflows.
+ *
+ * Stored separately from Pi's own settings.json so extension preferences remain
+ * stable without depending on host-internal config shape.
+ */
+export interface WorkflowSettings {
+    keywordTriggerEnabled?: boolean;
+    /** Literal keyword that arms workflows mode from interactive input. */
+    keywordTriggerWord?: string;
+    defaultAgentTimeoutMs?: number | null;
+    /**
+     * Default hard token budget applied to runs that don't pass their own
+     * `tokenBudget` (#68). null explicitly means "no budget" (useful in a
+     * project override to cancel a global budget); omitted also means no budget.
+     */
+    defaultTokenBudget?: number | null;
+    /** Default max concurrent agents per run. Clamped to the runtime maximum. */
+    defaultConcurrency?: number;
+    /** Default retry attempts after recoverable agent failures. */
+    defaultAgentRetries?: number;
+    /** Bottom task-panel display mode: "compact" (default, one line per run) | "detailed". */
+    progressPanelMode?: "compact" | "detailed";
+    /** Max agents shown per phase in detailed progress mode (default 8). */
+    progressPanelMaxAgents?: number;
+    /**
+     * Persist each workflow subagent transcript as a real pi session file under
+     * the standard sessions directory (~/.pi/agent/sessions/<encoded-cwd>/),
+     * keyed by the project cwd. Default false: subagent sessions stay in-memory
+     * and only the compacted history embedded in the run JSON survives.
+     */
+    persistAgentSessions?: boolean;
+    /**
+     * Character cap on a delivered background-run result's JSON-dump fallback
+     * before truncation (default 400). String results and `verdict`/`report`/
+     * `summary`/`synthesis` fields are never truncated.
+     */
+    deliveredResultMaxChars?: number;
+    /**
+     * Extra tool names to deny in workflow subagent sessions, on top of the
+     * always-on `workflow`/`workflow_control` defaults (#107). Use it to block
+     * other recursive-orchestration tools you have installed (e.g. a pi-subagents
+     * tool) so a subagent can't fan out through them.
+     */
+    excludeSubagentTools?: string[];
+}
+export interface WorkflowSettingsStore {
+    load(): WorkflowSettings;
+    save(settings: WorkflowSettings): void;
+}
+export interface WorkflowSettingsOptions {
+    /** Explicit settings path, primarily for tests and migrations. */
+    settingsPath?: string;
+    /** Project cwd whose project-level settings should override global settings. */
+    cwd?: string;
+    /** Explicit project settings path, primarily for tests. */
+    projectSettingsPath?: string;
+    /** Save destination when using saveWorkflowSettings with cwd. Default: global. */
+    scope?: "global" | "project";
+}
+/** Path to the user-level workflow settings JSON file (~/.pi/workflows/settings.json). */
+export declare function getWorkflowSettingsPath(): string;
+/** Path to this project's optional workflow settings override. */
+export declare function getWorkflowProjectSettingsPath(cwd: string): string;
+/** Load settings from disk. Missing, corrupt, or invalid files resolve to {}. */
+export declare function loadWorkflowSettings(settingsPathOrOptions?: string | WorkflowSettingsOptions): WorkflowSettings;
+/** Merge known settings into the user-level settings file. */
+export declare function saveWorkflowSettings(settings: WorkflowSettings, settingsPathOrOptions?: string | WorkflowSettingsOptions): void;
+/** Save a global preference and update an existing project override if one is present. */
+export declare function saveWorkflowSettingsForCwd(settings: WorkflowSettings, cwd: string): void;