@united-workforce/cli 0.2.1-rc.9 → 0.4.0

package/dist/__tests__/pid-recycling.test.js

@@ -0,0 +1,271 @@
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { generateUlid } from "@united-workforce/util";
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { createMarker, getProcessStartTime, isMarkerValid, isThreadRunning, listRunningThreads, readMarker, } from "../background/index.js";
+import { createUwfStore } from "../store.js";
+// ── helpers ───────────────────────────────────────────────────────────────────
+async function makeUwfStore(storageRoot) {
+    const casDir = join(storageRoot, "cas");
+    await mkdir(casDir, { recursive: true });
+    process.env.OCAS_HOME = casDir;
+    return createUwfStore(storageRoot);
+}
+async function createTestWorkflow(uwf) {
+    const workflowPayload = {
+        name: "test-workflow",
+        roles: {
+            role1: {
+                goal: "test goal",
+                outputSchema: { type: "object", properties: {} },
+            },
+        },
+        graph: { start: "role1" },
+        conditions: {},
+    };
+    return await uwf.store.cas.put(uwf.schemas.workflow, workflowPayload);
+}
+// ── test setup ────────────────────────────────────────────────────────────────
+let tmpDir;
+beforeEach(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), "pid-recycling-test-"));
+});
+afterEach(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+});
+// ── Spec: thread-marker-process-identity ──────────────────────────────────────
+describe("marker records process start time", () => {
+    test("createMarker stores processStartTime in marker file", async () => {
+        const uwf = await makeUwfStore(tmpDir);
+        const workflowHash = await createTestWorkflow(uwf);
+        const threadId = generateUlid(Date.now());
+        const processStartTime = getProcessStartTime(process.pid);
+        await createMarker(tmpDir, {
+            thread: threadId,
+            workflow: workflowHash,
+            pid: process.pid,
+            startedAt: Date.now(),
+            processStartTime,
+        });
+        const marker = await readMarker(tmpDir, threadId);
+        expect(marker).not.toBeNull();
+        expect(marker.pid).toBe(process.pid);
+        expect(marker.processStartTime).toBe(processStartTime);
+    });
+    test("processStartTime is number on Linux when /proc is available", async () => {
+        const startTime = getProcessStartTime(process.pid);
+        // On Linux, this should be a number (clock ticks since boot)
+        // On non-Linux, it may be null
+        if (process.platform === "linux") {
+            expect(typeof startTime).toBe("number");
+            expect(startTime).toBeGreaterThan(0);
+        }
+        else {
+            // On non-Linux, null is acceptable
+            expect(startTime === null || typeof startTime === "number").toBe(true);
+        }
+    });
+    test("getProcessStartTime returns null for non-existent PID", () => {
+        // PID 99999999 is unlikely to exist
+        const startTime = getProcessStartTime(99999999);
+        expect(startTime).toBeNull();
+    });
+});
+// ── Spec: thread-marker-valid-process-still-blocked ───────────────────────────
+describe("valid marker still blocks execution", () => {
+    test("isMarkerValid returns true when PID alive and processStartTime matches", () => {
+        const processStartTime = getProcessStartTime(process.pid);
+        const marker = {
+            thread: "test-thread",
+            workflow: "test-workflow",
+            pid: process.pid,
+            startedAt: Date.now(),
+            processStartTime,
+        };
+        const valid = isMarkerValid(marker);
+        expect(valid).toBe(true);
+    });
+    test("isThreadRunning returns marker when PID alive and processStartTime matches", async () => {
+        const uwf = await makeUwfStore(tmpDir);
+        const workflowHash = await createTestWorkflow(uwf);
+        const threadId = generateUlid(Date.now());
+        const processStartTime = getProcessStartTime(process.pid);
+        await createMarker(tmpDir, {
+            thread: threadId,
+            workflow: workflowHash,
+            pid: process.pid,
+            startedAt: Date.now(),
+            processStartTime,
+        });
+        const result = await isThreadRunning(tmpDir, threadId);
+        expect(result).not.toBeNull();
+        expect(result.pid).toBe(process.pid);
+    });
+});
+// ── Spec: thread-exec-stale-marker-recovery ───────────────────────────────────
+describe("stale marker recovery on exec", () => {
+    test("isMarkerValid returns false when processStartTime does not match", () => {
+        // Create a marker with a mismatched processStartTime
+        const marker = {
+            thread: "test-thread",
+            workflow: "test-workflow",
+            pid: process.pid, // PID is alive (it's our own process)
+            startedAt: Date.now(),
+            processStartTime: 1, // Deliberately wrong start time
+        };
+        const valid = isMarkerValid(marker);
+        expect(valid).toBe(false);
+    });
+    test("isThreadRunning deletes stale marker and returns null when processStartTime mismatches", async () => {
+        const uwf = await makeUwfStore(tmpDir);
+        const workflowHash = await createTestWorkflow(uwf);
+        const threadId = generateUlid(Date.now());
+        // Write a marker with a deliberately wrong processStartTime
+        await createMarker(tmpDir, {
+            thread: threadId,
+            workflow: workflowHash,
+            pid: process.pid, // alive process
+            startedAt: Date.now(),
+            processStartTime: 1, // wrong start time - simulates PID recycling
+        });
+        // isThreadRunning should detect the stale marker and clean it up
+        const result = await isThreadRunning(tmpDir, threadId);
+        expect(result).toBeNull();
+        // Verify marker file was deleted
+        const markerAfter = await readMarker(tmpDir, threadId);
+        expect(markerAfter).toBeNull();
+    });
+    test("isMarkerValid returns false when PID is not alive (regardless of processStartTime)", () => {
+        const marker = {
+            thread: "test-thread",
+            workflow: "test-workflow",
+            pid: 99999999, // non-existent PID
+            startedAt: Date.now(),
+            processStartTime: 12345,
+        };
+        const valid = isMarkerValid(marker);
+        expect(valid).toBe(false);
+    });
+});
+// ── Spec: thread-list-stale-marker-cleanup ────────────────────────────────────
+describe("thread list filters stale markers", () => {
+    test("listRunningThreads excludes threads with mismatched processStartTime", async () => {
+        const uwf = await makeUwfStore(tmpDir);
+        const workflowHash = await createTestWorkflow(uwf);
+        // T1: stale marker (PID alive, but wrong processStartTime)
+        const threadId1 = generateUlid(Date.now());
+        await createMarker(tmpDir, {
+            thread: threadId1,
+            workflow: workflowHash,
+            pid: process.pid,
+            startedAt: Date.now(),
+            processStartTime: 1, // wrong — simulates PID recycling
+        });
+        // T2: valid marker (PID alive, correct processStartTime)
+        const threadId2 = generateUlid(Date.now() + 1);
+        const correctStartTime = getProcessStartTime(process.pid);
+        await createMarker(tmpDir, {
+            thread: threadId2,
+            workflow: workflowHash,
+            pid: process.pid,
+            startedAt: Date.now(),
+            processStartTime: correctStartTime,
+        });
+        const running = await listRunningThreads(tmpDir);
+        // Only T2 should be listed
+        expect(running.length).toBe(1);
+        expect(running[0].thread).toBe(threadId2);
+        // T1's marker should have been deleted
+        const markerT1 = await readMarker(tmpDir, threadId1);
+        expect(markerT1).toBeNull();
+    });
+    test("listRunningThreads deletes marker when PID is dead", async () => {
+        const uwf = await makeUwfStore(tmpDir);
+        const workflowHash = await createTestWorkflow(uwf);
+        const threadId = generateUlid(Date.now());
+        // Marker with a non-existent PID
+        await createMarker(tmpDir, {
+            thread: threadId,
+            workflow: workflowHash,
+            pid: 99999999,
+            startedAt: Date.now(),
+            processStartTime: 12345,
+        });
+        const running = await listRunningThreads(tmpDir);
+        expect(running.length).toBe(0);
+        // Marker should be deleted
+        const markerAfter = await readMarker(tmpDir, threadId);
+        expect(markerAfter).toBeNull();
+    });
+});
+// ── Spec: thread-stop-validates-process-identity ──────────────────────────────
+describe("thread stop validates process identity", () => {
+    test("isMarkerValid returns false for recycled PID (PID alive, wrong start time)", () => {
+        // Simulate: marker says processStartTime=100, but actual process started at a different time
+        const marker = {
+            thread: "test-thread",
+            workflow: "test-workflow",
+            pid: process.pid, // alive
+            startedAt: Date.now(),
+            processStartTime: 1, // wrong — this PID was recycled
+        };
+        expect(isMarkerValid(marker)).toBe(false);
+    });
+});
+// ── Spec: thread-cancel-validates-process-identity ────────────────────────────
+describe("thread cancel validates process identity", () => {
+    test("isMarkerValid correctly identifies stale markers for cancel scenario", () => {
+        const marker = {
+            thread: "test-thread",
+            workflow: "test-workflow",
+            pid: process.pid, // alive
+            startedAt: Date.now(),
+            processStartTime: 1, // wrong — this is a recycled PID
+        };
+        expect(isMarkerValid(marker)).toBe(false);
+    });
+});
+// ── Legacy marker compatibility ───────────────────────────────────────────────
+describe("backward compatibility with old markers", () => {
+    test("marker without processStartTime field is treated as stale when PID alive", async () => {
+        const uwf = await makeUwfStore(tmpDir);
+        const workflowHash = await createTestWorkflow(uwf);
+        const threadId = generateUlid(Date.now());
+        // Simulate an old-format marker (no processStartTime field)
+        const runningDir = join(tmpDir, "running");
+        await mkdir(runningDir, { recursive: true });
+        const markerPath = join(runningDir, `${threadId}.json`);
+        const oldMarker = {
+            thread: threadId,
+            workflow: workflowHash,
+            pid: process.pid,
+            startedAt: Date.now(),
+            // No processStartTime field
+        };
+        await writeFile(markerPath, JSON.stringify(oldMarker, null, 2), "utf8");
+        // Reading the marker should work (null processStartTime)
+        const marker = await readMarker(tmpDir, threadId);
+        expect(marker).not.toBeNull();
+        expect(marker.processStartTime).toBeNull();
+        // isMarkerValid should still accept it gracefully (null means can't verify — fallback to PID check only)
+        // But since we can't verify identity, we treat it as potentially stale
+        // The spec says: on non-Linux, processStartTime is null — same behavior
+        // When processStartTime is null in marker AND we can't read /proc (or it's null from getProcessStartTime too),
+        // we fall back to the PID-alive-only check for backward compat
+        const valid = isMarkerValid(marker);
+        // With null processStartTime in the marker, we can't verify identity,
+        // but the PID IS alive. For backward compat, this should be treated as valid
+        // (the new getProcessStartTime returns a real number on Linux, null if unavailable)
+        if (process.platform === "linux") {
+            // On Linux where we CAN get the actual start time but the marker has null,
+            // we cannot confirm identity — treat as potentially stale
+            // However for backward compat during transition, null in marker = skip identity check
+            expect(valid).toBe(true);
+        }
+        else {
+            expect(valid).toBe(true);
+        }
+    });
+});
+//# sourceMappingURL=pid-recycling.test.js.map

package/dist/__tests__/pid-recycling.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pid-recycling.test.js","sourceRoot":"","sources":["../../src/__tests__/pid-recycling.test.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/prompt.test.js

@@ -3,6 +3,7 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { describe, expect, test } from "vitest";
 const __dirname = dirname(fileURLToPath(import.meta.url));
+import { generateCliReference } from "@united-workforce/util";
 import { cmdPromptAdapterDeveloping, cmdPromptBootstrap, cmdPromptList, cmdPromptUsage, cmdPromptWorkflowAuthoring, } from "../commands/prompt.js";
 describe("prompt commands", () => {
     test("prompt list returns prompt names (no bootstrap)", () => {
@@ -31,6 +32,22 @@ describe("prompt commands", () => {
         expect(result).not.toContain("Adapter Developing Reference");
         expect(result.length).toBeGreaterThan(500);
     });
+    test("prompt usage describes .workflows/ auto-discovery", () => {
+        const result = cmdPromptUsage();
+        expect(result).toContain(".workflows/");
+        expect(result).toContain("uwf thread start solve-issue");
+        expect(result.toLowerCase()).toContain("auto-discover");
+        expect(result.toLowerCase()).toContain("recommended");
+    });
+    test("prompt cli-reference describes .workflows/ auto-discovery", () => {
+        const ref = generateCliReference();
+        expect(ref).toContain(".workflows/");
+        expect(ref.toLowerCase()).toContain("cwd upward");
+        expect(ref).toContain("workflow list");
+        expect(ref).toMatch(/CAS hash/i);
+        expect(ref).toMatch(/file path/i);
+        expect(ref).toMatch(/registry/i);
+    });
     test("prompt workflow-authoring returns non-empty markdown string with frontmatter", () => {
         const result = cmdPromptWorkflowAuthoring();
         expect(typeof result).toBe("string");
@@ -44,6 +61,36 @@ describe("prompt commands", () => {
         expect(result).toContain("version:");
         expect(result.length).toBeGreaterThan(500);
     });
+    test("prompt workflow-authoring documents .workflows/ Placement section", () => {
+        const result = cmdPromptWorkflowAuthoring();
+        expect(result).toContain("## Placement");
+        expect(result).toContain(".workflows/");
+        expect(result).toContain("solve-issue.yaml");
+        expect(result.toLowerCase()).toContain("auto-discover");
+        expect(result.toLowerCase()).toContain("no workflow add");
+        // Placement must appear before Self-Testing
+        expect(result.indexOf("## Placement")).toBeLessThan(result.indexOf("## Self-Testing"));
+    });
+    test("prompt workflow-authoring mentions .workflow/ as legacy fallback", () => {
+        const result = cmdPromptWorkflowAuthoring();
+        expect(result).toContain(".workflow/");
+        expect(result.toLowerCase()).toContain("legacy");
+    });
+    test("prompt workflow-authoring documents Liquid filters with join example", () => {
+        const result = cmdPromptWorkflowAuthoring();
+        expect(result).toContain("| join");
+        expect(result.toLowerCase()).toContain("filter");
+    });
+    test("prompt workflow-authoring documents Liquid loops with for example", () => {
+        const result = cmdPromptWorkflowAuthoring();
+        expect(result).toContain("{% for");
+        expect(result).toContain("{% endfor %}");
+    });
+    test("prompt workflow-authoring uses Liquid terminology with no Mustache remnants", () => {
+        const result = cmdPromptWorkflowAuthoring();
+        expect(result.toLowerCase()).not.toContain("mustache");
+        expect(result.toLowerCase()).toContain("liquid");
+    });
     test("prompt adapter-developing returns non-empty markdown string with frontmatter", () => {
         const result = cmdPromptAdapterDeveloping();
         expect(typeof result).toBe("string");
@@ -96,4 +143,278 @@ describe("prompt commands", () => {
         expect(output).not.toContain("usage-reference");
     });
 });
+describe("prompt adapter-developing — issue #214 v0.4 contract", () => {
+    const text = cmdPromptAdapterDeveloping();
+    const lower = text.toLowerCase();
+    // ── Item 1 — AgentOptions includes fork and cleanup ─────────────────
+    test("AgentOptions documents fork field with AgentForkFn | null", () => {
+        expect(text).toContain("AgentOptions");
+        expect(text).toMatch(/fork\s*:\s*AgentForkFn\s*\|\s*null/);
+        expect(text).toContain("AgentForkFn");
+    });
+    test("AgentOptions documents cleanup field with AgentCleanupFn | null", () => {
+        expect(text).toMatch(/cleanup\s*:\s*AgentCleanupFn\s*\|\s*null/);
+        expect(text).toContain("AgentCleanupFn");
+    });
+    test("explains that fork=null is acceptable for adapters that do not implement step ask", () => {
+        expect(lower).toMatch(/fork.*null.*(do(es)? not|no).*step ask|step ask.*fork.*null/);
+    });
+    test("explains that cleanup runs after the agent completes (success or failure)", () => {
+        expect(lower).toMatch(/cleanup.*(after|completes|invoked).*(release|i\/?o|resources|subprocess)/);
+    });
+    // ── Item 2 — Public helpers table is complete ───────────────────────
+    test("helpers table lists buildRolePrompt", () => {
+        expect(text).toContain("buildRolePrompt");
+    });
+    test("helpers table lists buildContinuationPrompt", () => {
+        expect(text).toContain("buildContinuationPrompt");
+    });
+    test("helpers table lists buildThreadProgress", () => {
+        expect(text).toContain("buildThreadProgress");
+    });
+    test("helpers table lists buildOutputFormatInstruction", () => {
+        expect(text).toContain("buildOutputFormatInstruction");
+    });
+    test("helpers table lists buildSuspendOutput", () => {
+        expect(text).toContain("buildSuspendOutput");
+    });
+    test("helpers table lists buildFrontmatterRetryPrompt", () => {
+        expect(text).toContain("buildFrontmatterRetryPrompt");
+    });
+    test("helpers table lists session-cache helpers", () => {
+        expect(text).toContain("getCachedSessionId");
+        expect(text).toContain("setCachedSessionId");
+        expect(text).toContain("getAskSessionId");
+        expect(text).toContain("setAskSessionId");
+    });
+    // ── Item 3 — $SUSPEND coroutine yield ───────────────────────────────
+    test("documents $SUSPEND as coroutine yield with reason", () => {
+        expect(text).toContain("$SUSPEND");
+        expect(lower).toContain("coroutine");
+        expect(lower).toMatch(/reason/);
+    });
+    test("documents buildSuspendOutput helper to emit a $SUSPEND output", () => {
+        expect(text).toContain("buildSuspendOutput");
+        expect(text).toMatch(/buildSuspendOutput\s*\(/);
+    });
+    test("documents trySuspendFastPath round-trip and SUSPEND_OUTPUT_SCHEMA", () => {
+        expect(text).toContain("trySuspendFastPath");
+        expect(text).toMatch(/SUSPEND_OUTPUT_SCHEMA|suspendOutput/);
+    });
+    test("explains engine intercepts $SUSPEND before the moderator", () => {
+        expect(lower).toMatch(/intercept.*moderator|before the moderator|engine.*suspend/);
+        expect(lower).toMatch(/(thread|state).*suspend/);
+    });
+    test("notes that $SUSPEND is reserved and may be emitted by any role regardless of declared output", () => {
+        expect(lower).toMatch(/(any role|every role|regardless).*\$?suspend|reserved/);
+    });
+    // ── Item 4 — step ask adapter contract ──────────────────────────────
+    test("documents step ask --mode fork CLI contract for adapters", () => {
+        expect(text).toContain("--mode fork");
+        expect(text).toContain("--session");
+        expect(lower).toMatch(/fork.*(stdout|prints|return).*session/);
+    });
+    test("documents step ask --mode ask CLI contract", () => {
+        expect(text).toContain("--mode ask");
+        expect(text).toContain("--prompt");
+    });
+    test("explains that fork: null adapters do not need to handle --mode fork/ask", () => {
+        expect(lower).toMatch(/fork\s*:\s*null.*(do(es)? not|no|not required).*(--mode|step ask)/);
+    });
+    test("documents the per-stepHash ask-session cache key", () => {
+        expect(text).toContain("getAskSessionId");
+        expect(lower).toMatch(/(<step ?hash>|stephash).*:ask|ask.*cache|forked.*session.*step/);
+    });
+    // ── Item 5 — Adapter-owned LLM config ───────────────────────────────
+    test("explains engine config.yaml is LLM-free (no providers/models)", () => {
+        expect(lower).toMatch(/engine.*(config|llm-free|llm free)/);
+        expect(lower).toMatch(/no.*(provider|model|api[- ]?key)/);
+    });
+    test("shows the adapter-owned config path convention ~/.uwf/agents/<name>.yaml", () => {
+        expect(text).toMatch(/~\/?\.uwf\/agents\/.+\.yaml/);
+    });
+    test("shows a concrete example with provider.baseUrl, provider.apiKey, model", () => {
+        expect(text).toContain("baseUrl");
+        expect(text).toContain("apiKey");
+        expect(text).toMatch(/^\s*model\s*:/m);
+    });
+    test("references storageRoot from AgentContext as the way to resolve the adapter config path", () => {
+        expect(text).toContain("storageRoot");
+        expect(lower).toMatch(/(storageroot|ctx\.storageroot).*(agents\/|config|yaml)/);
+    });
+    // ── Item 6 — previousAttempts and $status: error ────────────────────
+    test("documents the failed-step retry path with $status: error", () => {
+        expect(text).toMatch(/\$status\s*:\s*["']?error["']?/);
+        expect(text).toContain("ErrorOutputPayload");
+    });
+    test("documents previousAttempts as CAS refs to prior failed StepNodes", () => {
+        expect(text).toContain("previousAttempts");
+        expect(lower).toMatch(/previousattempts.*(failed|prior|retry).*step/);
+    });
+    test("explains thread head is NOT advanced on isError=true", () => {
+        expect(lower).toMatch(/(head|thread).*not.*advance|advance.*not|isError.*true/);
+    });
+    test("documents the @uwf/thread-failed variable for tracking failed attempts across runs", () => {
+        expect(text).toContain("@uwf/thread-failed/");
+    });
+    test("explains MAX_FRONTMATTER_RETRIES (2) before persisting the error step", () => {
+        expect(text).toMatch(/2\s*(retries?|attempts?|frontmatter)/i);
+    });
+    // ── Item 7 — Realistic run() skeleton ───────────────────────────────
+    test("Quick Start run() builds prompt via helpers (not empty comments)", () => {
+        expect(text).toMatch(/buildRolePrompt|buildContinuationPrompt|buildThreadProgress/);
+    });
+    test("Quick Start run() returns all 5 AgentRunResult fields", () => {
+        expect(text).toContain("assembledPrompt");
+        expect(text).toContain("usage");
+        expect(text).toContain("detailHash");
+        expect(text).toContain("sessionId");
+    });
+    test("documents Usage type fields turns/inputTokens/outputTokens/duration", () => {
+        expect(text).toContain("inputTokens");
+        expect(text).toContain("outputTokens");
+        expect(text).toMatch(/turns/);
+        expect(text).toContain("duration");
+    });
+    test("Quick Start example does NOT contain the placeholder stub `// 1. Build your prompt from ctx`", () => {
+        expect(text).not.toMatch(/\/\/\s*1\.\s*Build your prompt from ctx\b/);
+    });
+    // ── Item 8 — isFirstVisit ───────────────────────────────────────────
+    test("explains isFirstVisit semantics", () => {
+        expect(text).toContain("isFirstVisit");
+        expect(lower).toMatch(/isfirstvisit.*(true|false).*(role|appeared|run|history)/);
+    });
+    test("explains the first-visit / re-entry branching pattern", () => {
+        expect(lower).toMatch(/(first[- ]?visit|isfirstvisit)[\s\S]*(re-?entry|resume)/);
+    });
+    // ── Item 9 — Fast path jargon explained ─────────────────────────────
+    test("introduces frontmatter extraction concept before the symbol name", () => {
+        const idxConcept = lower.search(/frontmatter extraction|extract.*frontmatter|parse.*frontmatter/);
+        const idxSymbol = text.indexOf("tryFrontmatterFastPath");
+        if (idxSymbol !== -1) {
+            expect(idxConcept).toBeGreaterThanOrEqual(0);
+            expect(idxConcept).toBeLessThan(idxSymbol);
+        }
+    });
+    test("does not use the bare term 'fast path' without an explanation in the surrounding 200 chars", () => {
+        const re = /fast[- ]?path/gi;
+        let m = re.exec(text);
+        while (m !== null) {
+            const window = text.slice(Math.max(0, m.index - 200), m.index + 200).toLowerCase();
+            expect(window).toMatch(/extract|parse|attempt|try|interpret/);
+            m = re.exec(text);
+        }
+    });
+    // ── Item 10 — No undefined schema variables ─────────────────────────
+    test("does not reference an undefined `textSchema` in the code samples", () => {
+        const idx = text.indexOf("textSchema");
+        if (idx !== -1) {
+            const window = text.slice(Math.max(0, idx - 200), idx + 200);
+            expect(window).toMatch(/registerAgentSchemas|schemas\.text|putSchema|TEXT_SCHEMA/);
+        }
+    });
+    test("does not reference an undefined `detailSchema` in the code samples", () => {
+        const idx = text.indexOf("detailSchema");
+        if (idx !== -1) {
+            const window = text.slice(Math.max(0, idx - 200), idx + 200);
+            expect(window).toMatch(/registerAgentSchemas|schemas|putSchema/);
+        }
+    });
+    test("Storing Session Detail section uses real APIs (storeBuiltinDetail / storeClaudeCodeDetail or store.cas.put with a registered schema)", () => {
+        expect(text).toMatch(/store\.cas\.put|storeBuiltinDetail|storeClaudeCodeDetail|registerAgentSchemas/);
+    });
+    // ── Cross-cutting structural tests ──────────────────────────────────
+    test("AdapterOutput JSON envelope (not just step hash) is documented as the stdout contract", () => {
+        expect(text).toContain("AdapterOutput");
+        expect(lower).toMatch(/json.*stdout|stdout.*json/);
+        expect(text).toContain("isError");
+        expect(text).toContain("errorMessage");
+    });
+    test("documents AgentContext storageRoot and casDir fields", () => {
+        expect(text).toContain("storageRoot");
+        expect(text).toContain("casDir");
+    });
+    test("documents UWF_HOME / OCAS_HOME env propagation from CLI to adapter", () => {
+        expect(text).toContain("UWF_HOME");
+        expect(text).toContain("OCAS_HOME");
+    });
+    test("Existing Adapters table still lists hermes, builtin, claude-code", () => {
+        expect(text).toContain("uwf-hermes");
+        expect(text).toContain("uwf-builtin");
+        expect(text).toContain("uwf-claude-code");
+    });
+    test("Checklist now includes fork, cleanup, $SUSPEND, and adapter-owned LLM config items", () => {
+        const checklistIdx = text.search(/##\s+Checklist/);
+        expect(checklistIdx).toBeGreaterThan(-1);
+        const checklist = text.slice(checklistIdx);
+        expect(checklist).toContain("fork");
+        expect(checklist).toContain("cleanup");
+        expect(checklist).toContain("$SUSPEND");
+        expect(checklist.toLowerCase()).toMatch(/llm config|agents\/.+\.yaml|adapter-owned/);
+    });
+});
+describe("prompt workflow-authoring — issue #226 edge location field", () => {
+    const text = cmdPromptWorkflowAuthoring();
+    const lower = text.toLowerCase();
+    // ── Group 1 — Field documentation ───────────────────────────────────
+    test("documents the location field on graph edges", () => {
+        expect(text).toMatch(/^\s*\|\s*`?location`?\s*\|/m);
+        expect(text).toMatch(/location[\s\S]{0,200}(working directory|cwd)/i);
+    });
+    test("documents location as optional with null fallback", () => {
+        expect(lower).toMatch(/location[\s\S]{0,300}(null|omitted|optional|default|fall(s| ?back))/i);
+        expect(lower).toMatch(/(thread.*cwd|start.*cwd|creation cwd|thread['']?s cwd)/);
+    });
+    test("documents Liquid template support for location", () => {
+        expect(text).toMatch(/location[\s\S]{0,400}\{\{\s*[a-zA-Z_]\w*\s*\}\}/);
+        expect(lower).toMatch(/location[\s\S]{0,300}liquid/);
+    });
+    // ── Group 2 — Inheritance chain ─────────────────────────────────────
+    test("documents the cwd inheritance chain end-to-end", () => {
+        expect(text).toContain("--cwd");
+        expect(text).toMatch(/StartNodePayload\.cwd|start(\.|node\.)?cwd|thread start cwd/i);
+        expect(text).toMatch(/Target\.location|edge\s+location|location\s+(field|override)/i);
+        expect(text).toMatch(/StepRecord\.cwd|StepNodePayload\.cwd|step(\.|node\.)?cwd|step.*cwd/i);
+        const flagIdx = text.indexOf("--cwd");
+        const startIdx = text.search(/StartNodePayload\.cwd|start(\.|node\.)?cwd|thread start cwd/i);
+        const locIdx = text.search(/Target\.location|edge\s+location|location\s+(field|override)/i);
+        const stepIdx = text.search(/StepRecord\.cwd|StepNodePayload\.cwd|step(\.|node\.)?cwd/i);
+        expect(flagIdx).toBeGreaterThanOrEqual(0);
+        expect(startIdx).toBeGreaterThan(flagIdx);
+        expect(locIdx).toBeGreaterThan(startIdx);
+        expect(stepIdx).toBeGreaterThan(locIdx);
+    });
+    test("explains location override is per-step (not per-thread)", () => {
+        expect(lower).toMatch(/(each|per).?step|override.*per.*step|step['']?s (working|cwd)/);
+    });
+    // ── Group 3 — Realistic cross-cwd example ───────────────────────────
+    test("includes a YAML example showing location on an edge", () => {
+        const yamlBlocks = text.match(/```yaml[\s\S]*?```/g) ?? [];
+        const hasLocationEdge = yamlBlocks.some((b) => /graph\s*:/.test(b) && /^\s*location\s*:/m.test(b));
+        expect(hasLocationEdge).toBe(true);
+    });
+    test("example demonstrates cross-cwd execution with a Liquid-templated path", () => {
+        const yamlBlocks = text.match(/```yaml[\s\S]*?```/g) ?? [];
+        const hasCrossCwdExample = yamlBlocks.some((b) => /location\s*:\s*['"]?\{\{\s*[a-zA-Z_]\w*\s*\}\}/m.test(b));
+        expect(hasCrossCwdExample).toBe(true);
+    });
+    test("example narrates a realistic scenario", () => {
+        expect(lower).toMatch(/(clone|checkout|dispatch|cross[- ]repo|different (repo|directory|working directory|cwd))/);
+    });
+    // ── Group 4 — Structural placement ──────────────────────────────────
+    test("location documentation appears under the Graph Routing section", () => {
+        const graphIdx = text.indexOf("## Graph Routing");
+        expect(graphIdx).toBeGreaterThanOrEqual(0);
+        const after = text.slice(graphIdx);
+        const localLocIdx = after.search(/\blocation\b/i);
+        expect(localLocIdx).toBeGreaterThanOrEqual(0);
+        const nextHeadingIdx = after.slice(1).search(/\n## /);
+        expect(localLocIdx).toBeLessThan(nextHeadingIdx === -1 ? after.length : nextHeadingIdx + 1);
+    });
+    test("Target field table still includes role and prompt alongside location", () => {
+        expect(text).toMatch(/\|\s*`?role`?\s*\|/m);
+        expect(text).toMatch(/\|\s*`?prompt`?\s*\|/m);
+        expect(text).toMatch(/\|\s*`?location`?\s*\|/m);
+    });
+});
 //# sourceMappingURL=prompt.test.js.map