@vimhead.dev/norn-cli 0.1.0-tip.35570530940.1 → 0.1.0-tip.35611592848.1

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

@@ -4,6 +4,21 @@ The Norn SDK is the TypeScript interface for building reusable workflows. A work
 
 Start with the complete [minimal workflow](../examples/minimal-workflow/plugin.ts) and its [write/run/change exercise](../examples/minimal-workflow/README.md).
 
+## Develop agent workflows through execution
+
+For agent-driven workflows, trial and error in native Norn runs is the default development method, starting with the first runnable step—not a final smoke test after implementation:
+
+**Author → execute real agents → inspect saved evidence → repair → rollback and restore a valid checkpoint → resume → repeat.**
+
+| Decision | GOOD | BAD |
+|---|---|---|
+| IF a workflow depends on agent behavior, THEN execute it early and frequently through Norn with bounded, representative inputs, using the loop above as the primary development process. ELSE deterministic workflows and helpers can be developed and validated with automated tests. | Exercise a real agent step before building the remaining orchestration; retain unit tests for scoring mathematics. | Build the whole agent workflow around mocked responses and postpone actual execution until the end. |
+| IF inspecting an agent run, THEN compare retained outputs and evidence against the task requirements. ELSE do not claim the workflow works from status or test results alone. | Check a generated report against its source evidence and requested deliverable. | Treat `completed`, schema-valid JSON, or a passing deterministic suite as proof of task correctness. |
+| IF repairing or iterating on an agent workflow, THEN use rollback, checkpoint restoration, and resume frequently to exercise the changed step while preserving valid earlier work. ELSE retain the inspected run as evidence for the unchanged behavior. | Restore the boundary after a valid assessment, repair delivery, and verify the assessment survives the resumed execution. | Restart every agent from scratch, simulate recovery only in tests, or assume restored files are correct without inspecting them. |
+| IF credentials, inputs, access, or authorization block native execution, THEN report the blocker and mark agent behavior unvalidated. ELSE report the actual runs, inspected artifacts, and recovery exercised. | Distinguish passing deterministic checks from a blocked live agent run. | Substitute mocked success for execution or imply an unperformed recovery cycle passed. |
+
+Use [source repair and rollback](recovery.md#source-repair-and-rollback) for checkpoint selection and external-effect precautions. The [agent → saved file → analysis repair exercise](../examples/agent-then-analysis/README.md#repair-only-the-analysis-step) demonstrates this loop with a real agent result retained across failure and recovery.
+
 ## Define a workflow
 
 `workflow` declares a complete, typed callable workflow:

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: "Check an outline for exact, case-sensitive '## heading' lines from requiredHeadings. Pass outline, requiredHeadings, and missingHeadings to the caller-selected next workflow. Reports heading presence only, not content quality; no model or external service is used.",
+	},
+	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: "Append one empty level-two Markdown section named heading to outline, then pass the revised outline to the caller-selected next workflow. Does not assess the outline or select further work; no model or external service is used.",
+	},
+	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/package.json

@@ -1 +1 @@
-{"version":"0.1.0-tip.35570530940.1"}
+{"version":"0.1.0-tip.35611592848.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.35570530940.1",
-  "commit": "48ecaf47ae0e82e17970db9465497a4e1ad5ff10",
+  "version": "0.1.0-tip.35611592848.1",
+  "commit": "ece526887ef7a821f5e08062d1553e8a5273bd86",
   "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.35570530940.1";
-    readonly commit: "48ecaf47ae0e82e17970db9465497a4e1ad5ff10";
+    readonly version: "0.1.0-tip.35611592848.1";
+    readonly commit: "ece526887ef7a821f5e08062d1553e8a5273bd86";
     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.35570530940.1",
-  "commit": "48ecaf47ae0e82e17970db9465497a4e1ad5ff10",
+  "version": "0.1.0-tip.35611592848.1",
+  "commit": "ece526887ef7a821f5e08062d1553e8a5273bd86",
   "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.35570530940.1",
+  "version": "0.1.0-tip.35611592848.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.35570530940.1"
+    "@vimhead.dev/norn": "0.1.0-tip.35611592848.1"
   },
   "scripts": {
     "build": "node ../../scripts/build-package.ts"