@vimhead.dev/norn-cli 0.1.0-tip.35586725577.1 → 0.1.0-tip.35614826665.1

package/assets/README.md

@@ -21,7 +21,7 @@ through the CLI from any harness. Agents run on the bundled
    const summarize = workflow({
      name: "summarize",
      entrypoint: {
-       instructions: "Summarize staged and unstaged tracked changes relative to HEAD in an absolute repositoryPath. Requires Git and an existing commit; untracked files are excluded. Saves workspace-relative summaryPath and retains the diff log. A nonempty diff is sent to the configured model; an empty diff needs no model call.",
+       instructions: "Use when you need a saved summary of staged and unstaged tracked changes in a Git repository before review or handoff. Compares against HEAD, excludes untracked files, and does not edit the repository. Requires an existing commit and model access for nonempty diffs.",
      },
      args: Type.Object({ repositoryPath: Type.String({ minLength: 1 }) }),
      async execute({ args, paths, commands, logs, agents, run }) {

package/assets/docs/README.md

@@ -14,7 +14,7 @@ Norn capabilities are ordinary TypeScript workflows: an agent can write one duri
 | Supply tools or tool wrappers to agents | [Custom tools](agents.md#custom-tools) | [Explicit shared state](../examples/shared-state/README.md) |
 | Persist application state or coordinate concurrent mutations | [Workflow-owned storage](persistence.md#workflow-owned-storage) | [Explicit shared state](../examples/shared-state/README.md), [Example-local work queue](../examples/coordinating-multiple-agents/README.md) |
 | Retain evidence or choose a filesystem boundary | [Persistence, files, and workspaces](persistence.md) | [Norn agent → saved file → analysis](../examples/agent-then-analysis/README.md) |
-| Reuse a workflow with a caller-selected continuation | [Composition](composition.md) | [Caller-selected continuation](../examples/caller-selected-continuation/README.md) |
+| Reuse workflows with caller-selected continuations and routing policy | [Composition](composition.md) | [Caller-selected continuation](../examples/caller-selected-continuation/README.md), [Caller-owned routing](../examples/caller-owned-routing/README.md) |
 | Repair a failed run without repeating earlier work | [Recovery and gates](recovery.md) | [Analysis-only repair](../examples/agent-then-analysis/README.md#repair-only-the-analysis-step) |
 
 [Public types](../packages/sdk/src/api.ts) define the Norn SDK's authoring interface. CLI discovery exposes the currently loaded project, not a documentation-time workflow catalogue. See [installation](../README.md#installation) for runtime setup.

package/assets/docs/composition.md

@@ -70,6 +70,21 @@ Contributions must be JSON objects matching the declared input type. Object-valu
 
 When passing a reference as input to another workflow, supply its JSON form shown above, not the function received in `args.next`.
 
+## Caller-owned routing policy
+
+A continuation can be a caller-owned router rather than the final consumer. The
+[caller-owned routing example](../examples/caller-owned-routing/README.md) combines
+assessment and revision workflows: assessment reports findings, revision produces
+an updated outline, and the router owns the acceptance threshold, next action,
+and iteration limit. Neither reusable capability knows the caller's policy.
+
+Task-level findings and run-level completion are separate: a caller may accept
+some findings, request more work, or fail when its revision budget is exhausted.
+
+| Decision | GOOD | BAD |
+|---|---|---|
+| IF callers need different acceptance or follow-up policies, THEN supply a caller-owned router as the continuation. ELSE use a direct continuation. | Route the same assessment to completion or revision using caller thresholds. | Embed one caller's revision budget in a reusable assessment, or add a router to unconditional delivery. |
+
 ## Multiple outcomes and direct targets
 
 References can be nested under ordinary author-selected names with independent contribution schemas:

package/assets/docs/workflows.md

@@ -29,7 +29,7 @@ import { Type } from "typebox";
 
 export const greet = workflow({
   name: "greet",
-  entrypoint: { instructions: "Return a greeting for the supplied name." },
+  entrypoint: { instructions: "Use when you need a personalized greeting returned as the run summary, without writing a file or calling a model." },
   args: Type.Object({ name: Type.String() }),
   execute({ args, run }) {
     return run.complete({ summary: `Hello, ${args.name}!` });
@@ -43,7 +43,13 @@ Supply `name`, `args`, `entrypoint`, and `execute` explicitly. Use `entrypoint:
 
 Workflow and scope names must be nonempty and cannot contain dots. A standalone workflow's ID is its name; a scoped workflow's ID is `<scope name>.<workflow name>`. Declarations expose the resolved `id`; CLI commands, references, and `run.next` use that exact ID, without implicit scope lookup.
 
-`entrypoint.instructions` describe selection, inputs, effects, and outputs. They are neither a Norn agent system prompt nor a gate decision. Declare args and config with [TypeBox schemas](schemas.md). Workflow inputs must be JSON data; `execute` receives the values after schema defaults and conversions. Public schemas must support `workflows inspect`.
+`entrypoint.instructions` is a short capability-selection description, like a skill's short description—not an execution plan, a Norn agent system prompt, or a gate decision.
+
+| Decision | GOOD | BAD |
+|---|---|---|
+| IF exposing an entrypoint, THEN lead with “Use when…” and the caller's need, followed by the useful result and only prerequisites, effects, or limits that affect selection. ELSE keep the step internal with `entrypoint: false`. | “Use when you need a source-grounded summary checked for unsupported claims. Saves a draft and an assessment; completion does not imply approval. Requires model access.” | “Call the draft agent, write JSON, then invoke the analysis workflow.” |
+
+Declare args and config with [TypeBox schemas](schemas.md) rather than listing their fields in the description. Workflow inputs must be JSON data; `execute` receives the values after schema defaults and conversions. Public schemas must support `workflows inspect`.
 
 Destructure the properties needed by the step from `execute(context)`. Gate descriptions receive the same inferred context:
 

package/assets/examples/agent-then-analysis/plugin.ts

@@ -24,7 +24,7 @@ const analysisSchema = Type.Object({
 const scope = workflowScope({ name: "sourceSummary" });
 export const draft = scope.workflow({
 	name: "draft",
-	entrypoint: { instructions: "Summarize a supplied source, save the draft, and independently assess its support and omissions. Returns workspace-relative draftPath and analysisPath plus an assessment; needs-revision is a completed assessment, not an approved summary." },
+	entrypoint: { instructions: "Use when you need a source-grounded summary checked for unsupported claims and omitted qualifications. Saves the draft and an independent assessment; a completed run may still report needs-revision. Requires model access." },
 	args: Type.Object({ source: Type.String({ minLength: 1 }) }),
 	async execute({ args, paths, agents }) {
 		const draft = await agents.prompt({

package/assets/examples/caller-owned-routing/README.md

@@ -0,0 +1,105 @@
+# Caller-owned routing
+
+Combine reusable assessment and revision workflows without making either own the
+caller's acceptance threshold or iteration limit. This code-only example checks
+Markdown outline headings, not prose quality. No model, credentials, local
+dependencies, or compilation step is required.
+
+Start with [caller-selected continuation](../caller-selected-continuation/README.md)
+for reference inputs and forwarded arguments. Here, the supplied continuation is
+a router rather than a delivery step:
+
+```text
+assessOutline → routeAssessment → complete
+                    │          → fail (revision limit)
+                    ↓
+               appendHeading → assessOutline → routeAssessment → …
+```
+
+## Capability versus caller policy
+
+- [assessment.ts](assessment.ts) reports which required headings are missing. It
+  does not decide whether those findings are acceptable or whether to revise.
+- [revision.ts](revision.ts) appends one requested heading and contributes the
+  revised outline. It knows neither the assessment workflow nor the router.
+- [router.ts](router.ts) owns acceptance, heading selection, the revision budget,
+  and the revision → reassessment → router chain. It saves the latest assessed
+  outline as workspace-relative `outline.md`, including on budget exhaustion.
+- [contracts.ts](contracts.ts) declares the contribution schemas shared by callers
+  and capabilities; [norn.project.json](norn.project.json) registers all three workflows.
+- [input.json](input.json) selects the router and captures its policy parameters
+  through `next.forwardArgs`, starting with `revisionsUsed: 0`.
+
+The router accepts an assessment with at most `maxMissingHeadings` findings.
+Otherwise it requests one revision, unless `maxRevisions` has been reached, in
+which case the run fails. Acceptance is checked first: the final allowed revision
+can still succeed. `maxRevisions` is bounded to 100 for this example.
+
+Only the router imports both capabilities. Their `next` references could instead
+select other registered consumers without changing either capability. The nested
+references in the router are ordinary JSON inputs: revision contributes `outline`
+to assessment; assessment contributes its findings back to the router. The
+[composition reference](../../docs/composition.md) owns reference semantics.
+
+## Inspect and run
+
+[Select the matching runtime](../../docs/cli.md#select-the-runtime), copy this
+entire directory into a writable task directory, and `cd` into the copy.
+
+```bash
+norn project inspect
+norn workflows list --all
+norn workflows inspect assessOutline
+norn workflows inspect appendHeading
+norn workflows inspect routeAssessment
+norn runs start assessOutline < input.json
+```
+
+Discovery should report `isComplete: true`. Copy the returned `run.id`:
+
+```bash
+RUN=<returned-run-id>
+norn runs wait "$RUN"
+norn runs inspect "$RUN"
+norn runs checkpoints "$RUN"
+```
+
+Expected results:
+
+- `run.status: completed`, `run.health: healthy`, and
+  `run.outcome.workflowId: routeAssessment`.
+- Outcome metadata `data` contains `outlinePath: "outline.md"`,
+  `missingHeadings: []`, and `revisionsUsed: 2`.
+- Transition checkpoints show assessment → router, then two repetitions of
+  router → revision → assessment → router.
+
+Read `outline.md` in the inspected `run.paths.workspace`:
+
+```markdown
+# Release notes
+
+## Summary
+
+## Changes
+
+## Verification
+```
+
+These are empty sections, not a completed release note. The example's contract is
+heading presence only; an actual content assessment needs a different capability.
+
+## Change only the caller's policy
+
+For each case, edit `args.next.forwardArgs` in `input.json`, start a **new** run,
+and inspect that run and its `outline.md`. Leave both capability modules unchanged.
+
+| `maxMissingHeadings` | `maxRevisions` | Expected result |
+|---|---|---|
+| `2` | `0` | Completes immediately with two missing headings and `revisionsUsed: 0`; no revision transition. |
+| `1` | `2` | Completes after one revision, with only `Verification` missing. |
+| `0` | `1` | Fails in the router after one revision, with `Verification` still missing; retained outline includes `Changes`. |
+| `0` | `0` | Fails immediately with both headings missing; no revision transition. |
+
+Keep `revisionsUsed: 0` for each fresh run. In the failure cases, the router reports
+that the revision limit was reached rather than completing below the requested
+threshold. A successful `runs wait` command alone does not imply workflow success.

package/assets/examples/caller-owned-routing/assessment.ts

@@ -0,0 +1,22 @@
+import { workflow, workflowRefSchema } from "@vimhead.dev/norn";
+import { Type } from "typebox";
+import { assessmentContributionSchema, headingsSchema, outlineContributionSchema } from "./contracts.ts";
+
+export const assessOutline = workflow({
+	name: "assessOutline",
+	entrypoint: {
+		instructions: "Use when you need to identify missing level-two headings in a Markdown outline before deciding whether to accept or revise it. Reports missing required headings to your continuation using exact, case-sensitive line matching; does not assess prose quality or decide acceptance.",
+	},
+	args: Type.Object({
+		...outlineContributionSchema.properties,
+		requiredHeadings: headingsSchema,
+		next: workflowRefSchema({ args: assessmentContributionSchema }),
+	}),
+	execute({ args }) {
+		const lines = new Set(args.outline.split(/\r?\n/));
+		const missingHeadings = args.requiredHeadings.filter(heading => !lines.has(`## ${heading}`));
+		return args.next({ outline: args.outline, requiredHeadings: args.requiredHeadings, missingHeadings });
+	},
+});
+
+export default [assessOutline];

package/assets/examples/caller-owned-routing/contracts.ts

@@ -0,0 +1,10 @@
+import { Type } from "typebox";
+
+export const headingSchema = Type.String({ minLength: 1, pattern: "^[^\\r\\n]+$" });
+export const headingsSchema = Type.Array(headingSchema, { uniqueItems: true });
+export const outlineContributionSchema = Type.Object({ outline: Type.String() });
+export const assessmentContributionSchema = Type.Object({
+	...outlineContributionSchema.properties,
+	requiredHeadings: headingsSchema,
+	missingHeadings: headingsSchema,
+});

package/assets/examples/caller-owned-routing/input.json

@@ -0,0 +1,14 @@
+{
+  "args": {
+    "outline": "# Release notes\n\n## Summary\n",
+    "requiredHeadings": ["Summary", "Changes", "Verification"],
+    "next": {
+      "workflow": "routeAssessment",
+      "forwardArgs": {
+        "maxMissingHeadings": 0,
+        "maxRevisions": 2,
+        "revisionsUsed": 0
+      }
+    }
+  }
+}

package/assets/examples/caller-owned-routing/norn.project.json

@@ -0,0 +1,4 @@
+{
+  "version": 1,
+  "workflows": ["./assessment.ts", "./revision.ts", "./router.ts"]
+}

package/assets/examples/caller-owned-routing/revision.ts

@@ -0,0 +1,20 @@
+import { workflow, workflowRefSchema } from "@vimhead.dev/norn";
+import { Type } from "typebox";
+import { headingSchema, outlineContributionSchema } from "./contracts.ts";
+
+export const appendHeading = workflow({
+	name: "appendHeading",
+	entrypoint: {
+		instructions: "Use when a Markdown outline needs one additional empty section before further processing. Appends the requested level-two heading and passes the revised outline to your continuation; does not write section content or assess the result.",
+	},
+	args: Type.Object({
+		...outlineContributionSchema.properties,
+		heading: headingSchema,
+		next: workflowRefSchema({ args: outlineContributionSchema }),
+	}),
+	execute({ args }) {
+		return args.next({ outline: `${args.outline.trimEnd()}\n\n## ${args.heading}\n` });
+	},
+});
+
+export default [appendHeading];

package/assets/examples/caller-owned-routing/router.ts

@@ -0,0 +1,49 @@
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { workflow, type WorkflowResult } from "@vimhead.dev/norn";
+import { Type } from "typebox";
+import { assessOutline } from "./assessment.ts";
+import { assessmentContributionSchema } from "./contracts.ts";
+import { appendHeading } from "./revision.ts";
+
+export const routeAssessment = workflow({
+	name: "routeAssessment",
+	entrypoint: false,
+	args: Type.Object({
+		...assessmentContributionSchema.properties,
+		maxMissingHeadings: Type.Integer({ minimum: 0 }),
+		maxRevisions: Type.Integer({ minimum: 0, maximum: 100 }),
+		revisionsUsed: Type.Integer({ minimum: 0, maximum: 100 }),
+	}),
+	async execute({ args, paths, run }): Promise<WorkflowResult> {
+		const outlinePath = "outline.md";
+		await writeFile(join(paths.workspace, outlinePath), args.outline);
+		const data = { outlinePath, missingHeadings: args.missingHeadings, revisionsUsed: args.revisionsUsed };
+		if (args.missingHeadings.length <= args.maxMissingHeadings) {
+			return run.complete({ summary: "Outline meets the caller's heading threshold.", data });
+		}
+		if (args.revisionsUsed >= args.maxRevisions) {
+			return run.fail({ summary: "Revision limit reached before the outline met the caller's heading threshold.", data });
+		}
+		return appendHeading({
+			outline: args.outline,
+			heading: args.missingHeadings[0],
+			next: {
+				workflow: assessOutline.id,
+				forwardArgs: {
+					requiredHeadings: args.requiredHeadings,
+					next: {
+						workflow: routeAssessment.id,
+						forwardArgs: {
+							maxMissingHeadings: args.maxMissingHeadings,
+							maxRevisions: args.maxRevisions,
+							revisionsUsed: args.revisionsUsed + 1,
+						},
+					},
+				},
+			},
+		});
+	},
+});
+
+export default [routeAssessment];

package/assets/examples/caller-selected-continuation/producer.ts

@@ -11,7 +11,7 @@ export const greetingContributionSchema = Type.Object({
 const scope = workflowScope({ name: "greetingProducer" });
 export const write = scope.workflow({
 	name: "write",
-	entrypoint: { instructions: "Write a greeting file for name, then invoke the caller-selected next workflow with workspace-relative resultPath and summary. The continuation owns completion; no model or external service is used." },
+	entrypoint: { instructions: "Use when a later workflow needs a personalized greeting file and should decide what happens next. Passes the workspace-relative file path and summary to your continuation instead of completing the run." },
 	args: Type.Object({
 		name: Type.String({ minLength: 1 }),
 		next: workflowRefSchema({ args: greetingContributionSchema }),

package/assets/examples/coordinating-multiple-agents/plugin.ts

@@ -13,7 +13,7 @@ const workerReportSchema = Type.Object({ status: Type.Enum(["acknowledged", "idl
 const scope = workflowScope({ name: "coordinatingAgents" });
 export const start = scope.workflow({
 	name: "start",
-	entrypoint: { instructions: "Summarize 2–12 supplied notes using two concurrent Norn agents and a shared leased work queue. Checkpoint completed rounds, verify every persisted result and exact source quotation, and return workspace-relative summariesPath for summaries.json. Requires configured Norn agent authentication; modifies only this run's logs and workspace." },
+	entrypoint: { instructions: "Use when you need separate summaries of 2–12 notes processed concurrently with saved progress for recovery. Saves each summary with a checked verbatim source quotation; this checks quotation fidelity, not summary quality. Requires model access." },
 	args: inputSchema,
 	async execute({ args, paths }) {
 		const queue = await openQueue({ workspace: paths.workspace, create: true });

package/assets/examples/getting-started/plugin.ts

@@ -5,7 +5,7 @@ import { Type } from "typebox";
 
 export const summarize = workflow({
 	name: "summarize",
-	entrypoint: { instructions: "Summarize staged and unstaged tracked changes relative to HEAD in an absolute repositoryPath. Requires Git and an existing commit; untracked files are excluded. Saves workspace-relative summaryPath and retains the diff log. A nonempty diff is sent to the configured model; an empty diff needs no model call." },
+	entrypoint: { instructions: "Use when you need a saved summary of staged and unstaged tracked changes in a Git repository before review or handoff. Compares against HEAD, excludes untracked files, and does not edit the repository. Requires an existing commit and model access for nonempty diffs." },
 	args: Type.Object({ repositoryPath: Type.String({ minLength: 1 }) }),
 	async execute({ args, paths, commands, logs, agents, run }) {
 		const diff = await commands.run({

package/assets/examples/minimal-workflow/plugin.ts

@@ -5,7 +5,7 @@ import { Type } from "typebox";
 
 export const write = workflow({
 	name: "greet",
-	entrypoint: { instructions: "Write a greeting file for the supplied name. Returns the greeting text and its workspace-relative greetingPath; no agent or external service is used." },
+	entrypoint: { instructions: "Use when you need a personalized greeting saved as a local file with no model or external service. Completes with the greeting text and workspace-relative file path." },
 	args: Type.Object({ name: Type.Decode(Type.String({ pattern: "\\S" }), value => value.trim()) }),
 	async execute({ args, paths, run }) {
 		const greeting = `Hello, ${args.name}!`;

package/assets/examples/shared-state/plugin.ts

@@ -11,7 +11,7 @@ const copyField = { id: "copiedText", schema: Type.String() };
 
 export const copy = copyScope.workflow({
 	name: "copy",
-	entrypoint: { instructions: "A Norn agent reads explicitly shared source and writes a copy, then a separate workflow verifies exact equality from a workspace SQLite database." },
+	entrypoint: { instructions: "Use when you need to exercise an agent's access to explicitly shared state by copying a short string exactly. Saves a verified copy or fails on mismatch. Requires model access; not intended as a replacement for ordinary file copying." },
 	args: Type.Object({ source: Type.String({ minLength: 1, maxLength: 500 }) }),
 	async execute({ args, paths, agents }) {
 		const state = await SharedState.open({ path: join(paths.workspace, "state.sqlite"), create: true });

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

@@ -6,7 +6,7 @@ import { materializeWorkspaceRepository } from "./repository.ts";
 
 export const developmentLoopWorkflow = developmentLoopScope.workflow({
 	name: "developmentLoop",
-	entrypoint: { instructions: "Plan once, then loop implementation and review in a workspace repository copy. Call this when a repository task should run through planning, implementation, and review." },
+	entrypoint: { instructions: "Use when you want a repository task planned, implemented, and reviewed in a separate clone with a caller approval gate. Starts from committed content and retains changes for inspection without automatically merging or pushing results back. Requires Git, Bash, and model access." },
 	args: developmentLoopArgsSchema,
 	async execute({ args, scope, paths, commands }): Promise<WorkflowResult> {
 		const repositoryPath = await materializeWorkspaceRepository({ commands, paths, repositoryRoot: scope.config.repositoryRoot, baseRef: args.baseRef });

package/assets/package.json

@@ -1 +1 @@
-{"version":"0.1.0-tip.35586725577.1"}
+{"version":"0.1.0-tip.35614826665.1"}

package/assets/packages/cli/src/generated-build-info.ts

@@ -2,8 +2,8 @@ import type { NornBuildInfo } from "./build-info.ts";
 
 export const NORN_GENERATED_BUILD_INFO = {
   "kind": "npm-registry",
-  "version": "0.1.0-tip.35586725577.1",
-  "commit": "9f57baea28085673cd562990813d8b2a2efa02c4",
+  "version": "0.1.0-tip.35614826665.1",
+  "commit": "286e68533b1d26b5afbb0cba9d75f857fb85dc53",
   "packageSpec": "@vimhead.dev/norn-cli@tip",
   "upgrade": {
     "supported": false,

package/dist/generated-build-info.d.ts

@@ -1,7 +1,7 @@
 export declare const NORN_GENERATED_BUILD_INFO: {
     readonly kind: "npm-registry";
-    readonly version: "0.1.0-tip.35586725577.1";
-    readonly commit: "9f57baea28085673cd562990813d8b2a2efa02c4";
+    readonly version: "0.1.0-tip.35614826665.1";
+    readonly commit: "286e68533b1d26b5afbb0cba9d75f857fb85dc53";
     readonly packageSpec: "@vimhead.dev/norn-cli@tip";
     readonly upgrade: {
         readonly supported: false;

package/dist/generated-build-info.js

@@ -1,8 +1,8 @@
 // src/generated-build-info.ts
 var NORN_GENERATED_BUILD_INFO = {
   "kind": "npm-registry",
-  "version": "0.1.0-tip.35586725577.1",
-  "commit": "9f57baea28085673cd562990813d8b2a2efa02c4",
+  "version": "0.1.0-tip.35614826665.1",
+  "commit": "286e68533b1d26b5afbb0cba9d75f857fb85dc53",
   "packageSpec": "@vimhead.dev/norn-cli@tip",
   "upgrade": {
     "supported": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vimhead.dev/norn-cli",
-  "version": "0.1.0-tip.35586725577.1",
+  "version": "0.1.0-tip.35614826665.1",
   "description": "Harness-agnostic runtime for agent-driven and code-driven workflows, built primarily for agents.",
   "type": "module",
   "license": "MIT",
@@ -43,7 +43,7 @@
     "@earendil-works/pi-coding-agent": "0.85.1",
     "jiti": "^2.7.0",
     "typebox": "^1.3.34",
-    "@vimhead.dev/norn": "0.1.0-tip.35586725577.1"
+    "@vimhead.dev/norn": "0.1.0-tip.35614826665.1"
   },
   "scripts": {
     "build": "node ../../scripts/build-package.ts"