@vimhead.dev/norn-cli 0.1.0-tip.35359392805.1 → 0.1.0-tip.35390859630.1

package/assets/examples/worktree-development-loop/workflows/implementation/execute.ts

@@ -1,38 +1,39 @@
-import type { NornRunNext, NornRun } from "@vimhead.dev/norn";
-import { worktreeDevelopmentLoopManifest } from "../../manifest.ts";
+import { reviewWorkflow } from "../review/execute.ts";
+import type { WorkflowResult } from "@vimhead.dev/norn";
+import { developmentLoopScope } from "../../scope.ts";
+import { implementationArgsSchema } from "./schema.ts";
 import { ensureCommandSucceeded } from "../../shared/commands.ts";
-import { implementationAgentResponseSchema, type ImplementationParams } from "./schema.ts";
+import { implementationAgentResponseSchema } from "./schema.ts";
 
-export async function executeImplementationWorkflow(
-	run: NornRun,
-	params: ImplementationParams,
-): Promise<NornRunNext> {
-	const repositoryPath = await run.state.get(worktreeDevelopmentLoopManifest.states.developmentLoop.repositoryPath);
-	const planArtifact = await run.state.get(worktreeDevelopmentLoopManifest.states.planning.planArtifact);
-	const plan = await run.artifacts.read(planArtifact);
-	const previousReviewArtifact = await run.state.getOptional(worktreeDevelopmentLoopManifest.states.review.reviewArtifact);
-	const previousReview = previousReviewArtifact ? await run.artifacts.read(previousReviewArtifact) : undefined;
-	const implementation = await run.agents.prompt({
-		label: `implementation-${params.iteration}`,
-		cwd: repositoryPath,
-		tools: ["read", "grep", "find", "ls", "edit", "write", "bash"],
-		prompt: buildImplementationPrompt(params.task, plan, params.iteration, previousReview),
-		response: implementationAgentResponseSchema,
-	});
-	await run.state.set(worktreeDevelopmentLoopManifest.states.implementation.implementationSummary, implementation.summary);
-	const status = await run.commands.run({
-		label: `implementation-${params.iteration}-status`,
-		cwd: repositoryPath,
-		command: "git status --short",
-	});
-	await ensureCommandSucceeded(status);
-	const statusOutput = await run.logs.read(status.stdoutLog);
-	await run.artifacts.write(`implementation/iteration-${params.iteration}-status.txt`, statusOutput);
-	return worktreeDevelopmentLoopManifest.workflows.review({
-		task: params.task,
-		iteration: params.iteration,
-	});
-}
+export const implementationWorkflow = developmentLoopScope.workflow({
+	id: "implementation",
+	isEntrypoint: false,
+	instructions: "Apply one implementation pass in the current repository.",
+	args: implementationArgsSchema,
+	async execute({ args, run }): Promise<WorkflowResult> {
+		const repositoryPath = args.repositoryPath;
+		const planArtifact = args.planArtifact;
+		const plan = await run.artifacts.read(planArtifact);
+		const previousReviewArtifact = args.previousReviewArtifact;
+		const previousReview = previousReviewArtifact ? await run.artifacts.read(previousReviewArtifact) : undefined;
+		const implementation = await run.agents.prompt({
+			label: `implementation-${args.iteration}`,
+			cwd: repositoryPath,
+			tools: ["read", "grep", "find", "ls", "edit", "write", "bash"],
+			prompt: buildImplementationPrompt(args.task, plan, args.iteration, previousReview),
+			response: implementationAgentResponseSchema,
+		});
+		const status = await run.commands.run({
+			label: `implementation-${args.iteration}-status`,
+			cwd: repositoryPath,
+			command: "git status --short",
+		});
+		await ensureCommandSucceeded(status);
+		const statusOutput = await run.logs.read(status.stdoutLog);
+		await run.artifacts.write(`implementation/iteration-${args.iteration}-status.txt`, statusOutput);
+		return reviewWorkflow({ ...args, implementationSummary: implementation.summary });
+	}
+});
 
 function buildImplementationPrompt(task: string, plan: string, iteration: number, previousReview: string | undefined): string {
 	return [

package/assets/examples/worktree-development-loop/workflows/implementation/index.ts

@@ -1,3 +1,2 @@
-export { implementationWorkflow } from "./declaration.ts";
-export { executeImplementationWorkflow } from "./execute.ts";
-export { implementationAgentResponseSchema, implementationParamsSchema, type ImplementationParams } from "./schema.ts";
+export { implementationWorkflow } from "./execute.ts";
+export { implementationAgentResponseSchema, implementationArgsSchema, type ImplementationArgs } from "./schema.ts";

package/assets/examples/worktree-development-loop/workflows/implementation/schema.ts

@@ -1,12 +1,16 @@
+import { artifactRefSchema } from "@vimhead.dev/norn";
+import { planningArgsSchema } from "../planning/schema.ts";
 import { Type, type StaticDecode } from "typebox";
 
-export const implementationParamsSchema = Type.Object({
-	task: Type.String(),
+export const implementationArgsSchema = Type.Object({
+	...planningArgsSchema.properties,
 	iteration: Type.Integer({ minimum: 1 }),
+	planArtifact: artifactRefSchema,
+	previousReviewArtifact: Type.Optional(artifactRefSchema),
 });
 
 export const implementationAgentResponseSchema = Type.Object({
 	summary: Type.String(),
 });
 
-export type ImplementationParams = StaticDecode<typeof implementationParamsSchema>;
+export type ImplementationArgs = StaticDecode<typeof implementationArgsSchema>;

package/assets/examples/worktree-development-loop/workflows/planning/execute.ts

@@ -1,20 +1,27 @@
-import type { NornRunNext, NornRun } from "@vimhead.dev/norn";
-import { worktreeDevelopmentLoopManifest } from "../../manifest.ts";
-import { planningAgentResponseSchema, type PlanningParams } from "./schema.ts";
+import { implementationWorkflow } from "../implementation/execute.ts";
+import type { WorkflowResult } from "@vimhead.dev/norn";
+import { developmentLoopScope } from "../../scope.ts";
+import { planningArgsSchema } from "./schema.ts";
+import { planningAgentResponseSchema } from "./schema.ts";
 
-export async function executePlanningWorkflow(run: NornRun, params: PlanningParams): Promise<NornRunNext> {
-	const repositoryPath = await run.state.get(worktreeDevelopmentLoopManifest.states.developmentLoop.repositoryPath);
-	const planning = await run.agents.prompt({
-		label: "planning",
-		cwd: repositoryPath,
-		tools: ["read", "grep", "find", "ls"],
-		prompt: buildPlanningPrompt(params.task),
-		response: planningAgentResponseSchema,
-	});
-	const planArtifact = await run.artifacts.write("planning/plan.md", planning.plan);
-	await run.state.set(worktreeDevelopmentLoopManifest.states.planning.planArtifact, planArtifact);
-	return worktreeDevelopmentLoopManifest.workflows.implementation({ task: params.task, iteration: 1 });
-}
+export const planningWorkflow = developmentLoopScope.workflow({
+	id: "planning",
+	isEntrypoint: false,
+	instructions: "Create an implementation plan for a repository task.",
+	args: planningArgsSchema,
+	async execute({ args, run }): Promise<WorkflowResult> {
+		const repositoryPath = args.repositoryPath;
+		const planning = await run.agents.prompt({
+			label: "planning",
+			cwd: repositoryPath,
+			tools: ["read", "grep", "find", "ls"],
+			prompt: buildPlanningPrompt(args.task),
+			response: planningAgentResponseSchema,
+		});
+		const planArtifact = await run.artifacts.write("planning/plan.md", planning.plan);
+		return implementationWorkflow({ ...args, planArtifact, iteration: 1 });
+	}
+});
 
 function buildPlanningPrompt(task: string): string {
 	return [

package/assets/examples/worktree-development-loop/workflows/planning/index.ts

@@ -1,3 +1,2 @@
-export { planningWorkflow } from "./declaration.ts";
-export { executePlanningWorkflow } from "./execute.ts";
-export { planningAgentResponseSchema, planningParamsSchema, type PlanningParams } from "./schema.ts";
+export { planningWorkflow } from "./execute.ts";
+export { planningAgentResponseSchema, planningArgsSchema, type PlanningArgs } from "./schema.ts";

package/assets/examples/worktree-development-loop/workflows/planning/schema.ts

@@ -1,7 +1,9 @@
 import { Type, type StaticDecode } from "typebox";
 
-export const planningParamsSchema = Type.Object({
+export const planningArgsSchema = Type.Object({
 	task: Type.String(),
+	repositoryPath: Type.String(),
+	maxIterations: Type.Integer({ minimum: 1, maximum: 10 }),
 });
 
 export const planningAgentResponseSchema = Type.Object({
@@ -9,4 +11,4 @@ export const planningAgentResponseSchema = Type.Object({
 	summary: Type.String(),
 });
 
-export type PlanningParams = StaticDecode<typeof planningParamsSchema>;
+export type PlanningArgs = StaticDecode<typeof planningArgsSchema>;

package/assets/examples/worktree-development-loop/workflows/review/execute.ts

@@ -1,36 +1,45 @@
-import type { NornRunNext, NornRun } from "@vimhead.dev/norn";
-import { worktreeDevelopmentLoopManifest } from "../../manifest.ts";
+import { reviewRouterWorkflow } from "../review-router/execute.ts";
+import type { WorkflowResult } from "@vimhead.dev/norn";
+import { developmentLoopScope } from "../../scope.ts";
+import { reviewArgsSchema } from "./schema.ts";
 import { ensureCommandSucceeded } from "../../shared/commands.ts";
-import { reviewAgentResponseSchema, type ReviewParams } from "./schema.ts";
+import { reviewAgentResponseSchema } from "./schema.ts";
 
-export async function executeReviewWorkflow(run: NornRun, params: ReviewParams): Promise<NornRunNext> {
-	const repositoryPath = await run.state.get(worktreeDevelopmentLoopManifest.states.developmentLoop.repositoryPath);
-	const planArtifact = await run.state.get(worktreeDevelopmentLoopManifest.states.planning.planArtifact);
-	const implementationSummary = await run.state.get(worktreeDevelopmentLoopManifest.states.implementation.implementationSummary);
-	const plan = await run.artifacts.read(planArtifact);
-	const diff = await run.commands.run({
-		label: `review-${params.iteration}-diff`,
-		cwd: repositoryPath,
-		command: "git status --short && git diff --stat HEAD -- . && git diff HEAD -- .",
-	});
-	await ensureCommandSucceeded(diff);
-	const diffOutput = await run.logs.read(diff.stdoutLog);
-	await run.artifacts.write(`review/iteration-${params.iteration}-diff.txt`, diffOutput);
-	const review = await run.agents.prompt({
-		label: `review-${params.iteration}`,
-		cwd: repositoryPath,
-		tools: ["read", "grep", "find", "ls", "bash"],
-		prompt: buildReviewPrompt(params.task, plan, implementationSummary, diffOutput),
-		response: reviewAgentResponseSchema,
-	});
-	const automatedReviewArtifact = await run.artifacts.write(`review/iteration-${params.iteration}-automated.json`, JSON.stringify(review, null, 2));
-	return worktreeDevelopmentLoopManifest.workflows.reviewRouter({
-		iteration: params.iteration,
-		decision: review.decision,
-		summary: review.summary,
-		automatedReviewArtifact,
-	});
-}
+export const reviewWorkflow = developmentLoopScope.workflow({
+	id: "review",
+	isEntrypoint: false,
+	instructions: "Review the current repository boundary changes.",
+	args: reviewArgsSchema,
+	async execute({ args, run }): Promise<WorkflowResult> {
+		const repositoryPath = args.repositoryPath;
+		const planArtifact = args.planArtifact;
+		const implementationSummary = args.implementationSummary;
+		const plan = await run.artifacts.read(planArtifact);
+		const diff = await run.commands.run({
+			label: `review-${args.iteration}-diff`,
+			cwd: repositoryPath,
+			command: "git status --short && git diff --stat HEAD -- . && git diff HEAD -- .",
+		});
+		await ensureCommandSucceeded(diff);
+		const diffOutput = await run.logs.read(diff.stdoutLog);
+		await run.artifacts.write(`review/iteration-${args.iteration}-diff.txt`, diffOutput);
+		const review = await run.agents.prompt({
+			label: `review-${args.iteration}`,
+			cwd: repositoryPath,
+			tools: ["read", "grep", "find", "ls", "bash"],
+			prompt: buildReviewPrompt(args.task, plan, implementationSummary, diffOutput),
+			response: reviewAgentResponseSchema,
+		});
+		const automatedReviewArtifact = await run.artifacts.write(`review/iteration-${args.iteration}-automated.json`, JSON.stringify(review, null, 2));
+		return reviewRouterWorkflow({
+			...args,
+			iteration: args.iteration,
+			decision: review.decision,
+			summary: review.summary,
+			automatedReviewArtifact,
+		});
+	}
+});
 
 function buildReviewPrompt(task: string, plan: string, implementationSummary: string, diff: string): string {
 	return [

package/assets/examples/worktree-development-loop/workflows/review/index.ts

@@ -1,10 +1,9 @@
-export { reviewWorkflow } from "./declaration.ts";
-export { executeReviewWorkflow } from "./execute.ts";
+export { reviewWorkflow } from "./execute.ts";
 export {
 	reviewAgentResponseSchema,
 	reviewDecisionSchema,
-	reviewParamsSchema,
+	reviewArgsSchema,
 	storedReviewSchema,
-	type ReviewParams,
+	type ReviewArgs,
 	type StoredReview,
 } from "./schema.ts";

package/assets/examples/worktree-development-loop/workflows/review/schema.ts

@@ -1,11 +1,12 @@
+import { implementationArgsSchema } from "../implementation/schema.ts";
 import { artifactRefSchema } from "@vimhead.dev/norn";
 import { Type, type StaticDecode } from "typebox";
 
 export const reviewDecisionSchema = Type.Enum(["accept", "revise", "blocked"]);
 
-export const reviewParamsSchema = Type.Object({
-	task: Type.String(),
-	iteration: Type.Integer({ minimum: 1 }),
+export const reviewArgsSchema = Type.Object({
+	...implementationArgsSchema.properties,
+	implementationSummary: Type.String(),
 });
 
 export const reviewAgentResponseSchema = Type.Object({
@@ -19,5 +20,5 @@ export const storedReviewSchema = Type.Object({
 	reviewArtifact: artifactRefSchema,
 });
 
-export type ReviewParams = StaticDecode<typeof reviewParamsSchema>;
+export type ReviewArgs = StaticDecode<typeof reviewArgsSchema>;
 export type StoredReview = StaticDecode<typeof storedReviewSchema>;

package/assets/examples/worktree-development-loop/workflows/review-router/execute.ts

@@ -1,51 +1,56 @@
-import type { NornWorkflowExecutionResult, NornRun } from "@vimhead.dev/norn";
-import { worktreeDevelopmentLoopManifest } from "../../manifest.ts";
+import { implementationWorkflow } from "../implementation/execute.ts";
+import type { WorkflowResult } from "@vimhead.dev/norn";
+import { developmentLoopScope } from "../../scope.ts";
+import { reviewRouterArgsSchema } from "./schema.ts";
 import type { StoredReview } from "../review/schema.ts";
-import type { ReviewRouterParams } from "./schema.ts";
 
-export async function executeReviewRouterWorkflow(
-	run: NornRun,
-	params: ReviewRouterParams,
-): Promise<NornWorkflowExecutionResult> {
-	const repositoryPath = await run.state.get(worktreeDevelopmentLoopManifest.states.developmentLoop.repositoryPath);
-	const planArtifact = await run.state.get(worktreeDevelopmentLoopManifest.states.planning.planArtifact);
-	const currentIteration = await run.state.get(worktreeDevelopmentLoopManifest.states.developmentLoop.currentIteration);
-	const maxIterations = await run.state.get(worktreeDevelopmentLoopManifest.states.developmentLoop.maxIterations);
-	const task = await run.state.get(worktreeDevelopmentLoopManifest.states.developmentLoop.task);
-	const reviewArtifact = await run.artifacts.write(
-		`review/iteration-${params.iteration}-decision.json`,
-		JSON.stringify({ decision: params.decision, summary: params.summary, automatedReviewArtifact: params.automatedReviewArtifact }, null, 2),
-	);
-	const lastReview: StoredReview = { decision: params.decision, summary: params.summary, reviewArtifact };
+export const reviewRouterWorkflow = developmentLoopScope.workflow({
+	id: "reviewRouter",
+	isEntrypoint: false,
+	instructions: "Route implementation and review iterations based on the latest review decision.",
+	gate: {
+		enabled: true,
+		describe: ({ args }) => `Review iteration ${args.iteration}. Confirm or edit the automated decision before continuing. Plan: ${args.planArtifact.path}.`,
+		fields: ["decision", "summary"] as const,
+	},
+	args: reviewRouterArgsSchema,
+	async execute({ args, run }): Promise<WorkflowResult> {
+		const repositoryPath = args.repositoryPath;
+		const planArtifact = args.planArtifact;
+		const currentIteration = args.iteration;
+		const maxIterations = args.maxIterations;
+		const task = args.task;
+		const reviewArtifact = await run.artifacts.write(
+			`review/iteration-${args.iteration}-decision.json`,
+			JSON.stringify({ decision: args.decision, summary: args.summary, automatedReviewArtifact: args.automatedReviewArtifact }, null, 2),
+		);
+		const lastReview: StoredReview = { decision: args.decision, summary: args.summary, reviewArtifact };
 
-	await run.state.set(worktreeDevelopmentLoopManifest.states.review.reviewDecision, params.decision);
-	await run.state.set(worktreeDevelopmentLoopManifest.states.review.reviewArtifact, reviewArtifact);
+		if (args.decision === "accept") {
+			return run.complete({
+				summary: `Implementation accepted after ${currentIteration} iteration(s).`,
+				artifacts: { plan: planArtifact, review: reviewArtifact },
+				data: { status: "done", repositoryPath, iterations: currentIteration, lastReview },
+			});
+		}
 
-	if (params.decision === "accept") {
-		return run.complete({
-			summary: `Implementation accepted after ${currentIteration} iteration(s).`,
-			artifacts: { plan: planArtifact, review: reviewArtifact },
-			data: { status: "done", repositoryPath, iterations: currentIteration, lastReview },
-		});
-	}
+		if (args.decision === "blocked") {
+			return run.fail({
+				summary: args.summary,
+				artifacts: { plan: planArtifact, review: reviewArtifact },
+				data: { status: "blocked", repositoryPath, iterations: currentIteration, lastReview },
+			});
+		}
 
-	if (params.decision === "blocked") {
-		return run.fail({
-			summary: params.summary,
-			artifacts: { plan: planArtifact, review: reviewArtifact },
-			data: { status: "blocked", repositoryPath, iterations: currentIteration, lastReview },
-		});
-	}
+		if (currentIteration >= maxIterations) {
+			return run.fail({
+				summary: `Maximum iteration count reached after ${currentIteration} iteration(s).`,
+				artifacts: { plan: planArtifact, review: reviewArtifact },
+				data: { status: "needs-attention", repositoryPath, iterations: currentIteration, lastReview },
+			});
+		}
 
-	if (currentIteration >= maxIterations) {
-		return run.fail({
-			summary: `Maximum iteration count reached after ${currentIteration} iteration(s).`,
-			artifacts: { plan: planArtifact, review: reviewArtifact },
-			data: { status: "needs-attention", repositoryPath, iterations: currentIteration, lastReview },
-		});
+		const nextIteration = currentIteration + 1;
+		return implementationWorkflow({ task, repositoryPath, maxIterations, planArtifact, iteration: nextIteration, previousReviewArtifact: reviewArtifact });
 	}
-
-	const nextIteration = currentIteration + 1;
-	await run.state.set(worktreeDevelopmentLoopManifest.states.developmentLoop.currentIteration, nextIteration);
-	return worktreeDevelopmentLoopManifest.workflows.implementation({ task, iteration: nextIteration });
-}
+});

package/assets/examples/worktree-development-loop/workflows/review-router/index.ts

@@ -1,3 +1,2 @@
-export { reviewRouterWorkflow } from "./declaration.ts";
-export { executeReviewRouterWorkflow } from "./execute.ts";
-export { reviewRouterParamsSchema, type ReviewRouterParams } from "./schema.ts";
+export { reviewRouterWorkflow } from "./execute.ts";
+export { reviewRouterArgsSchema, type ReviewRouterArgs } from "./schema.ts";

package/assets/examples/worktree-development-loop/workflows/review-router/schema.ts

@@ -1,12 +1,13 @@
+import { implementationArgsSchema } from "../implementation/schema.ts";
 import { artifactRefSchema } from "@vimhead.dev/norn";
 import { Type, type StaticDecode } from "typebox";
 import { reviewDecisionSchema } from "../review/schema.ts";
 
-export const reviewRouterParamsSchema = Type.Object({
-	iteration: Type.Integer({ minimum: 1 }),
+export const reviewRouterArgsSchema = Type.Object({
+	...implementationArgsSchema.properties,
 	decision: reviewDecisionSchema,
 	summary: Type.String(),
 	automatedReviewArtifact: artifactRefSchema,
 });
 
-export type ReviewRouterParams = StaticDecode<typeof reviewRouterParamsSchema>;
+export type ReviewRouterArgs = StaticDecode<typeof reviewRouterArgsSchema>;

package/assets/package.json

@@ -1 +1 @@
-{"version":"0.1.0-tip.35359392805.1"}
+{"version":"0.1.0-tip.35390859630.1"}

package/assets/packages/cli/src/cli.ts

@@ -17,9 +17,9 @@ import { clearRunResumeRequest, readRunLaunchRequest, readRunResumeRequest, writ
 import { readRunMetrics } from "./internal/metrics.ts";
 import { getRunLeaseOwner, NornRunLease } from "./internal/run-lease.ts";
 import { generateRunName } from "./internal/run-names.ts";
-import { getRunInfo, listRuns, mergeInterruptedWorkflowParams, resolveRunRoot } from "./internal/run-state.ts";
+import { assertRunVersion, getRunInfo, listRuns, mergeInterruptedWorkflowArgs, resolveRunRoot } from "./internal/run-state.ts";
 import { NornRunStore } from "./internal/run-store.ts";
-import { discoverNornProject, findNornProject, inspectNornWorkflow, loadNornProject, NORN_PROJECT_FILE_NAME } from "./plugin-loader.ts";
+import { discoverNornProject, findNornProject, inspectNornWorkflow, loadNornProject, NORN_PROJECT_FILE_NAME } from "./workflow-loader.ts";
 
 const RUNS_ROOT = join(".norn", "runs");
 const RUN_WAIT_INTERVAL_MS = 1000;
@@ -110,9 +110,9 @@ const COMMANDS: readonly CliCommand[] = [
 	{
 		id: "project.inspect",
 		path: ["project", "inspect"],
-		description: "Use when discovering the active Norn project, plugins, and workflow sources.",
+		description: "Use when discovering the active Norn project, configuration, and workflow sources.",
 		usage: "norn project inspect",
-		output: "JSON object with project metadata under project, isComplete, and plugin diagnostics. Incomplete discovery does not permit execution.",
+		output: "JSON object with project metadata under project, isComplete, and registration diagnostics. Incomplete discovery does not permit execution.",
 		examples: ["norn project inspect"],
 		execute: async (args) => {
 			assertNoExtraArgs("project inspect", args);
@@ -125,17 +125,17 @@ const COMMANDS: readonly CliCommand[] = [
 		description: "Use when selecting a Norn workflow for a user task; defaults to entrypoint workflows.",
 		usage: "norn workflows list [--entrypoints|--all]",
 		options: ["--entrypoints: list entrypoint workflows", "--all: include internal workflow steps"],
-		output: "JSON object with workflow summaries under workflows, isComplete, and plugin diagnostics. Successful discovery can be incomplete; start/resume remain strict.",
+		output: "JSON object with workflow summaries under workflows, isComplete, and registration diagnostics. Successful discovery can be incomplete; start/resume remain strict.",
 		examples: ["norn workflows list", "norn workflows list --all"],
 		execute: listWorkflows,
 	},
 	{
 		id: "workflows.inspect",
 		path: ["workflows", "inspect"],
-		description: "Use when reading a workflow's instructions, params schema, gate contract, and source plugin before starting or editing it.",
+		description: "Use when reading a workflow's instructions, args schema, gate contract, and registration source before starting or editing it.",
 		usage: "norn workflows inspect <workflow-id>",
 		arguments: ["workflow-id: fully qualified workflow id"],
-		output: "JSON object with workflow details, isComplete, and plugin diagnostics. workflow is null if unavailable in an incomplete catalog or its schema cannot be inspected; an unknown id in a complete catalog is an error.",
+		output: "JSON object with workflow details, isComplete, and registration diagnostics. workflow is null if unavailable in an incomplete catalog or its schema cannot be inspected; an unknown id in a complete catalog is an error.",
 		examples: ["norn workflows inspect example.plan"],
 		execute: async (args) => {
 			const workflowId = requiredArg("workflows inspect", args, 0, "workflow id");
@@ -146,12 +146,12 @@ const COMMANDS: readonly CliCommand[] = [
 	{
 		id: "runs.start",
 		path: ["runs", "start"],
-		description: "Use when starting a Norn workflow run after the workflow id and params are known.",
+		description: "Use when starting a Norn workflow run after the workflow id and args are known.",
 		usage: "norn runs start <workflow-id>",
 		arguments: ["workflow-id: fully qualified workflow id to start"],
-		stdin: "Optional JSON object: {\"params\":{...},\"config\":{\"pluginId\":{...}}}.",
+		stdin: "Optional JSON object: {\"args\":{...},\"config\":{\"workflowOrScopeId\":{...}}}.",
 		output: "JSON object with started run info under run.",
-		examples: ["printf '{\"params\":{\"task\":\"Add tests\"}}' | norn runs start example.plan"],
+		examples: ["printf '{\"args\":{\"task\":\"Add tests\"}}' | norn runs start example.plan"],
 		execute: async (args) => {
 			const workflowId = requiredArg("runs start", args, 0, "workflow id");
 			await startRun(workflowId, args.slice(1));
@@ -163,9 +163,9 @@ const COMMANDS: readonly CliCommand[] = [
 		description: "Use when resuming an interrupted gate or a checkpoint restored for retry.",
 		usage: "norn runs resume <run>",
 		arguments: ["run: run id, generated name, or run path"],
-		stdin: "Optional JSON object: {\"params\":{...}}. Interrupted runs require a patch containing only editable gate fields; pending-resume runs do not accept params.",
+		stdin: "Optional JSON object: {\"args\":{...}}. Interrupted runs require a patch containing only editable gate fields; pending-resume runs do not accept args.",
 		output: "JSON object with resumed run info under run.",
-		examples: ["printf '{\"params\":{\"decision\":\"accept\"}}' | norn runs resume quiet-river-lantern"],
+		examples: ["printf '{\"args\":{\"decision\":\"accept\"}}' | norn runs resume quiet-river-lantern"],
 		execute: async (args) => {
 			const run = requiredArg("runs resume", args, 0, "run");
 			await resumeRun(run, args.slice(1));
@@ -753,7 +753,7 @@ async function initProject(): Promise<void> {
 	const projectPath = resolve(projectRoot, NORN_PROJECT_FILE_NAME);
 	if (await isFile(projectPath)) throw new Error(`Norn project already exists: ${projectPath}`);
 	await mkdir(resolve(projectRoot, RUNS_ROOT), { recursive: true });
-	await writeFile(projectPath, `${JSON.stringify({ version: 1, plugins: [], includes: [], config: {} }, null, 2)}\n`, "utf8");
+	await writeFile(projectPath, `${JSON.stringify({ version: 1, workflows: [], includes: [], config: {} }, null, 2)}\n`, "utf8");
 	await ensureGitignoreExcludesRunState(projectRoot);
 	writeJson({ project: { path: projectPath, root: projectRoot, runsRoot: resolve(projectRoot, RUNS_ROOT) } });
 }
@@ -768,21 +768,21 @@ async function inspectProject(): Promise<void> {
 	writeJson({ project, isComplete, diagnostics });
 }
 
-async function startRun(workflowId: string, args: readonly string[]): Promise<void> {
-	assertNoStructuredInputArgs("runs start", args);
+async function startRun(workflowId: string, commandArgs: readonly string[]): Promise<void> {
+	assertNoStructuredInputArgs("runs start", commandArgs);
 	const project = await loadNornProject(process.cwd());
 	const workflow = project.registry.workflowById(workflowId);
 	if (!workflow) throw new Error(`Unknown workflow: ${workflowId}`);
 	const input = parseStartRunInput(await readStdinJson());
-	const params = input.params === undefined ? {} : input.params;
-	Value.Decode(workflow.params, params);
+	const args = input.args === undefined ? {} : input.args;
+	Value.Decode(workflow.args, args);
 	const configOverride = input.config;
 	const id = randomUUID();
 	const name = generateRunName(new Set((await listRuns(project.projectRoot)).map((run) => run.name)));
 	const runRoot = resolve(project.projectRoot, RUNS_ROOT, id);
 	await mkdir(runRoot, { recursive: true });
 	const createdAt = new Date().toISOString();
-	await writeRunLaunchRequest(runRoot, { version: 1, type: "run", id, name, workflowId, params, configOverride, createdAt });
+	await writeRunLaunchRequest(runRoot, { version: 2, type: "run", id, name, workflowId, args, configOverride, createdAt });
 	await startDetachedExecuteRun(id, project.projectRoot);
 	writeJson({ run: startedRunInfo({ id, name, workflow, runRoot, createdAt }) });
 }
@@ -796,8 +796,9 @@ async function resumeRun(run: string, args: readonly string[]): Promise<void> {
 	let request: NornRunResumeRequest;
 	try {
 		const runInfo = await getRunInfo(runRoot);
-		const params = await parseResumeParams(runInfo, input.params);
-		request = { version: 1, type: "resume", id: runInfo.id, requestId: randomUUID(), params, createdAt: new Date().toISOString() };
+		assertRunVersion(runInfo.version);
+		const args = await parseResumeArgs(runInfo, input.args);
+		request = { version: 2, type: "resume", id: runInfo.id, requestId: randomUUID(), args, createdAt: new Date().toISOString() };
 		await writeRunResumeRequest(runRoot, request);
 	} finally {
 		await lease.release();
@@ -811,18 +812,18 @@ async function resumeRun(run: string, args: readonly string[]): Promise<void> {
 	writeJson({ run: await getRunInfo(runRoot) });
 }
 
-async function parseResumeParams(runInfo: NornRunInfo, params: unknown): Promise<unknown> {
+async function parseResumeArgs(runInfo: NornRunInfo, args: unknown): Promise<unknown> {
 	if (runInfo.status === "interrupted") {
-		if (params === undefined) throw new Error(`Interrupted workflow resume requires params: ${runInfo.name}`);
+		if (args === undefined) throw new Error(`Interrupted workflow resume requires args: ${runInfo.name}`);
 		if (!runInfo.currentWorkflowId) throw new Error(`Run has no current workflow: ${runInfo.name}`);
 		const project = await loadNornProject(process.cwd());
 		const workflow = project.registry.workflowById(runInfo.currentWorkflowId);
 		if (!workflow) throw new Error(`Unknown workflow for resumed run: ${runInfo.currentWorkflowId}`);
-		Value.Decode(workflow.params, mergeInterruptedWorkflowParams(runInfo.interruption?.params, params, runInfo.interruption?.fields));
-		return params;
+		Value.Decode(workflow.args, mergeInterruptedWorkflowArgs(runInfo.interruption?.args, args, runInfo.interruption?.fields));
+		return args;
 	}
 	if (runInfo.status === "pendingResume") {
-		if (params !== undefined) throw new Error(`Pending-resume workflows do not accept params: ${runInfo.name}`);
+		if (args !== undefined) throw new Error(`Pending-resume workflows do not accept args: ${runInfo.name}`);
 		return undefined;
 	}
 	throw new Error(`Run must be rolled back before resuming: ${runInfo.name}`);
@@ -900,11 +901,11 @@ async function executeRun(runId: string): Promise<void> {
 	try {
 		const project = await loadNornProject(process.cwd());
 		const engine = new NornEngine({ cwd: project.projectRoot, signal: abortController.signal, gateMode: "pause", config: project.projectConfig });
-		for (const plugin of project.plugins) engine.registerPlugin(plugin);
+		engine.registerWorkflows(project.definitions);
 		if (request.type === "run") {
 			const workflow = project.registry.workflowById(request.workflowId);
 			if (!workflow) throw new Error(`Unknown workflow: ${request.workflowId}`);
-			await engine.runWorkflow(workflow, request.params, { id: request.id, name: request.name, configOverride: request.configOverride });
+			await engine.runWorkflow(workflow, request.args, { id: request.id, name: request.name, configOverride: request.configOverride });
 		} else {
 			await engine.resumeRequestedWorkflow({ runRoot, request });
 		}
@@ -1006,7 +1007,7 @@ function startedRunInfo(input: {
 	readonly createdAt: string;
 }): NornRunInfo {
 	return {
-		version: 1,
+		version: 2,
 		id: input.id,
 		name: input.name,
 		path: input.runRoot,
@@ -1058,18 +1059,18 @@ async function readStdin(): Promise<string> {
 	});
 }
 
-function parseStartRunInput(value: unknown): { readonly params?: unknown; readonly config?: unknown } {
+function parseStartRunInput(value: unknown): { readonly args?: unknown; readonly config?: unknown } {
 	if (value === undefined) return {};
 	const input = parseStructuredInputObject("runs start", value);
-	assertStructuredInputKeys("runs start", input, ["params", "config"]);
-	return { params: input.params, config: input.config };
+	assertStructuredInputKeys("runs start", input, ["args", "config"]);
+	return { args: input.args, config: input.config };
 }
 
-function parseResumeRunInput(value: unknown): { readonly params?: unknown } {
+function parseResumeRunInput(value: unknown): { readonly args?: unknown } {
 	if (value === undefined) return {};
 	const input = parseStructuredInputObject("runs resume", value);
-	assertStructuredInputKeys("runs resume", input, ["params"]);
-	return { params: input.params };
+	assertStructuredInputKeys("runs resume", input, ["args"]);
+	return { args: input.args };
 }
 
 function parseStructuredInputObject(command: string, value: unknown): Record<string, unknown> {