@iowarp/clio-coder 0.3.1 → 0.3.3

package/skills/workflow/workflow-distiller/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: workflow-distiller
+description: Use when a workflow that just happened should become reusable, when the user says "make this a skill", "package what we just did", "turn this into a workflow", or when the same multi-step process has been repeated across sessions. Reconstructs the workflow from the session record, interviews, checks overlap with installed skills, gates on approval, then writes the SKILL.md following skill-craft. Not for authoring a skill from scratch with no prior workflow; write the SKILL.md directly following skill-craft. Not for distilling into an agent recipe; propose that as a follow-up when the workflow is dispatch-shaped.
+version: 0.2.1
+license: Apache-2.0
+allowed-tools:
+  - read
+  - grep
+  - find
+  - ls
+  - context
+  - write
+  - ask_user
+requires:
+  - skill:skill-craft
+clio:
+  registry-id: iowarp/clio-coder
+  source-url: https://github.com/iowarp/clio-coder/tree/main/skills/workflow/workflow-distiller
+  audit: pass
+  provenance: designed
+  eval-status: smoke-checked
+  model-size: large
+---
+
+# Workflow Distiller
+
+Turn a workflow that actually ran into a reusable skill. The distiller's
+identity is runtime truth: it reconstructs what happened from the visible
+session record, not from anyone's memory of it. Skip the ceremony when there
+is no prior workflow; a from-scratch skill is a SKILL.md written directly,
+following skill-craft. skill-craft also governs how every skill this
+distiller produces is written: description, body, and pruning rules live
+there, not here.
+
+## Phase 1 - Reconstruct From Evidence
+
+Before asking anything, list the concrete steps that visibly executed in this
+session, in order: tools called, commands run, files touched, dispatches made,
+skills activated. Cite the conversation record for each step. Anything the
+user describes that did not visibly run is tagged `assumption` and becomes an
+interview question. This grounding step is mandatory and comes first; when the
+reconstruction and the user's memory disagree, the reconstruction wins and the
+disagreement is worth a question.
+
+## Phase 2 - Interview
+
+Use `ask_user` with `mode: "single_question"`, one question per round, bounded
+rounds (default 8, max 12), following the grill-me operating contract:
+recommended answer first when options are natural, stop signals ("stop",
+"enough", "later", cancel) respected immediately, answers translated into
+compact decisions. Question bank, roots before leaves:
+
+1. Confirm the reconstruction and resolve tagged assumptions.
+2. Inputs and outputs: what varies between runs, what is fixed.
+3. Recurrence: how often has this actually happened? A workflow that ran once
+   is usually not worth a skill; ask early and offer to stop.
+4. Per-step rigidity: must-match versus any-reasonable-approach.
+5. Failure behavior per step: ask the user, retry an alternative, or fail
+   loudly.
+6. Scope cuts: what the skill should refuse to do.
+7. Name (lowercase-hyphen).
+
+## Phase 3 - Overlap Check
+
+Call `context(scope="skills")` with no name to list installed skills. Judge
+overlap per step, not per workflow: if an installed skill's triggers cover a
+step, that step is referenced by name in the new skill body, never
+reimplemented, with a one-line rationale for the dependency. A different end
+goal does not excuse reimplementing a covered step. Record each reference as
+a `requires: [skill:<name>]` entry in the generated skill's frontmatter in
+Phase 5, so the loader warns when the dependency is missing.
+
+## Phase 4 - Design Gate
+
+Present a compact design summary and wait for explicit approval:
+
+```markdown
+## Skill Design - <name>
+Description draft: <triggers only, third person>
+Steps: <step, rigidity, on-failure> per line
+References: <skill:<name>, why> or none
+Scope: project | user (user only if the workflow crosses repositories)
+Validation scenario: <prompt, expected observable behavior>
+```
+
+No skill file is written before the user approves. "Looks fine, but change X"
+means revise and re-present.
+
+## Phase 5 - Create
+
+Write `SKILL.md` under `.clio-coder/skills/<approved-name>/`, following skill-craft
+for the frontmatter contract, a triggers-only third-person description, and
+the pruning pass, with `requires: [skill:<name>]` for every skill the overlap
+check referenced. Confirm it loads with `clio-coder skills validate`. Scope
+defaults to project; use the user skill store only when the user said the
+workflow crosses repositories. Placeholders replace every session-specific
+path, name, and value; distill the pattern, not the incident. Keep the
+generated skill under 120 lines; reference instead of inlining. If
+the session repeatedly dispatched the same worker pattern, also offer a recipe
+sketch for the agents surface, but do not write recipe files.
+
+## Phase 6 - Validate
+
+Record one RED-GREEN scenario agreed with the user: the prompt, and the
+observable behavior that distinguishes with-skill from without. Run it once if
+cheap (a single small headless run); otherwise record it in the skill body's
+example section as the standing validation obligation.
+
+## Worked Example
+
+Session: the user fetched a CSV export, normalized column names with a small
+script, and verified row counts against the source, three sessions in a row.
+
+1. Reconstruct: `bash curl ...` (ran), `write normalize.py` + `bash python3
+   normalize.py` (ran), `bash wc -l` comparison (ran). User also mentions "and
+   I always spot-check five rows" - not visible this session, tagged
+   assumption.
+2. Interview: confirms reconstruction; spot-check confirmed as a real step;
+   recurrence "weekly"; normalization must-match, fetch any-approach; failure
+   on row-count mismatch must fail loudly; name `csv-ingest`.
+3. Overlap: the `context(scope="skills")` listing shows no fetch or CSV skill
+   installed; no references.
+4. Gate: summary presented; user approves after tightening the description.
+5. Create: write `.clio-coder/skills/csv-ingest/SKILL.md`, placeholders for the
+   export URL and column map; `clio-coder skills validate` passes.
+6. Validate: scenario "ingest this month's export" must show fetch,
+   normalize, count-verify, spot-check in that order; recorded in the body.
+
+## Red Flags
+
+- Writing any skill before the design gate is approved.
+- A reconstruction that lists steps nothing in the session shows.
+- Reimplementing an installed skill's job instead of referencing it.
+- Session-specific paths or values surviving into the generated skill.
+- Batching interview questions or ignoring a stop signal.
+- Distilling a one-off without asking about recurrence.

package/skills/workflow/workflow-distiller/evals.md

@@ -0,0 +1,107 @@
+# Evals - workflow-distiller
+
+Baseline scenarios (run a subagent WITHOUT the skill to capture the gap, then
+WITH the skill to confirm it closes). Rubric is pass/fail per bullet.
+
+## S1 - "make what we just did a skill"
+
+Setup: Make what we just did a skill. For the record, this session we ran
+the release-notes workflow end to end: pulled the merged PR titles since
+the last tag with gh, grouped them by conventional-commit type, rewrote
+each group into user-facing bullets, and verified every PR number in the
+draft against the gh list before saving docs/release-notes.md. I also
+mentioned we sometimes ping the release channel afterwards, but we did not
+do that here.
+
+Expected:
+
+- Reconstructs the executed steps from the session record, in order, before
+  asking any question; unobserved steps the user mentions are tagged as
+  assumptions.
+- Interviews via `ask_user` with `mode: "single_question"`, one question per
+  round, bounded rounds.
+- Lists installed skills via `context(scope="skills")` with no name before
+  designing.
+- Presents a compact design summary and waits for explicit approval.
+- Writes the SKILL.md only after approval, with session-specific values
+  replaced by placeholders.
+- Records a RED-GREEN validation scenario.
+
+## S2 - overlap with an installed skill
+
+Setup: the workflow's retrieval step is already covered by an installed skill
+(for example arxiv-literature for paper retrieval).
+
+Expected:
+
+- The overlap check finds the installed skill.
+- The generated skill references it by name instead of reimplementing the
+  step, with a one-line rationale in the body.
+- The generated frontmatter carries `requires: [skill:<name>]` so the loader's
+  unmet-dependency warning arms when the referenced skill is absent.
+
+## S3 - no recurrence
+
+Setup: mid-interview the user admits the workflow has only ever run once and
+may not recur.
+
+Expected:
+
+- Questions whether distillation is worth it and offers to stop.
+- Does not press on to create a skill for a one-off by default.
+
+## S4 - anti-trigger: brand-new skill
+
+Setup: user asks for a new skill for something never done in any session.
+
+Expected:
+
+- Skips the distiller ceremony and points at writing the SKILL.md directly,
+  following skill-craft.
+
+## Baseline failure modes to watch for (RED)
+
+- Writes a vague skill immediately from the user's description, no grounding
+  in what actually ran.
+- No overlap check; reimplements an installed skill's behavior.
+- No approval gate; the skill file appears before the user saw a design.
+- Session-specific paths, URLs, and values baked into the skill body.
+- Multi-question interviewing or an unbounded question stream.
+
+## Observed results
+
+Runs 2026-07-02, headless `clio-coder run --skill`. `ask_user` is not registered in
+headless runs, so interviews were exercised with pre-supplied decisions in the
+prompt; the phases still had to run in order.
+
+- Six-phase walk (CSV header normalization fixture): the workflow visibly ran
+  (write plus execute normalize.py, row-count check), Phase 1 cited exactly
+  those steps, Phase 2 applied the pre-supplied decisions question by
+  question, Phase 3 listed installed skills with no name, Phase 4 presented
+  the summary and stopped for approval even though pre-approval was offered
+  (the strict reading of the gate), and after an explicit approval turn Phase
+  5's skill-creation call landed a loadable project skill that `clio-coder skills
+  inspect` resolves, with placeholders instead of session paths. Phase 6
+  recorded the validation scenario in the body.
+- S2 RED (no distiller, arxiv-literature installed): the baseline created the
+  skill immediately with no overlap check against the installed-skill
+  listing, no gate, and a body that reimplements the fetch step. Gap
+  confirmed.
+- S2 GREEN: with the shipped per-step overlap wording, the design references
+  `arxiv-literature` with a rationale instead of reimplementing retrieval.
+  Two earlier drafts missed this: workflow-level overlap judgment and a
+  fixture prompt that prescribed the fetch mechanism both masked the
+  behavior; the wording now says a different end goal does not excuse
+  reimplementing a covered step. At the time of that run the skill-creation
+  tool could not emit `requires` frontmatter, so the skill handed the user
+  the line to add; `requires: [skill:arxiv-literature]` on the generated
+  skill was verified to produce the loader's "requires skill ... which is not
+  available" warning when the dependency is absent. 2026-07-02: skill
+  creation moved to writing SKILL.md directly (the artifact tool's skill kind
+  was removed); Phase 5 now writes the `requires` entries into the
+  frontmatter itself.
+
+## Smoke record (2026-08-13)
+
+One representative scenario via `clio-coder skills eval` against Nemo-3.5-Lightning
+(30B local, llamacpp on mini), full-auto sandbox. PASS. Inline session-trace setup engaged; judge 5/6.

package/src/cli/acp.ts

@@ -1,4 +1,6 @@
+import { realpathSync } from "node:fs";
 import path from "node:path";
+import { MAX_TIMER_DELAY_MS } from "../core/timers.js";
 import { runClioCommand } from "./clio.js";
 import { restoreStdout, takeOverStdout, writeRawStdout } from "./output-guard.js";
 import { printError } from "./shared.js";
@@ -9,7 +11,7 @@ Serve Clio Coder as an Agent Client Protocol v1 agent over stdio.
 
   --cwd PATH               Workspace root the server boots in and opens sessions at.
   --permission-timeout MS  How long a mediated permission request may wait for the
-                           client before it is denied. Defaults to the configured
+                           client before the prompt expires. Defaults to the configured
                            delegation.defaults.permissionTimeoutMs.
 
 This command is intended for ACP frontends to spawn. Interactive delegation remains
@@ -35,7 +37,9 @@ function parseAcpFlags(args: ReadonlyArray<string>): AcpFlags | string {
 		}
 		if (arg === "--permission-timeout") {
 			const ms = value === undefined ? Number.NaN : Number(value);
-			if (!Number.isInteger(ms) || ms <= 0) return "--permission-timeout needs a positive whole number of milliseconds";
+			if (!Number.isInteger(ms) || ms <= 0 || ms > MAX_TIMER_DELAY_MS) {
+				return `--permission-timeout needs a whole number from 1 to ${MAX_TIMER_DELAY_MS} milliseconds`;
+			}
 			flags.permissionTimeoutMs = ms;
 			index += 1;
 			continue;
@@ -45,6 +49,19 @@ function parseAcpFlags(args: ReadonlyArray<string>): AcpFlags | string {
 	return flags;
 }
 
+/**
+ * The workspace root the server is pinned to, resolved and then canonicalized
+ * through the filesystem. A symlinked launch path is the reason: `process.cwd()`
+ * reports the physical path after chdir, so a session request carrying the same
+ * string the process was launched with used to be refused as a different
+ * workspace. One canonical form on both sides removes that class of mismatch.
+ * Throws when the path cannot be resolved, which the caller reports as an
+ * unusable `--cwd`.
+ */
+export function resolveAcpCwd(value: string): string {
+	return realpathSync(path.resolve(value));
+}
+
 export async function runAcpCommand(
 	args: ReadonlyArray<string>,
 	options: { apiKey?: string; noContextFiles?: boolean; noSkills?: boolean; skillPaths?: ReadonlyArray<string> } = {},
@@ -62,9 +79,11 @@ export async function runAcpCommand(
 	// Boot has to happen in the workspace the sessions will use: settings
 	// resolution, project context, and the session ledger all read process.cwd(),
 	// and the server refuses a session whose cwd is not the one it booted in.
+	// The path is canonicalized before the chdir so the launch root and every
+	// later comparison against process.cwd() speak the same physical path.
 	if (flags.cwd !== undefined) {
 		try {
-			process.chdir(flags.cwd);
+			process.chdir(resolveAcpCwd(flags.cwd));
 		} catch {
 			printError(`--cwd is not a directory this process can enter: ${flags.cwd}`);
 			return 2;
@@ -78,7 +97,15 @@ export async function runAcpCommand(
 			...(options.noSkills ? { noSkills: true } : {}),
 			...(options.skillPaths && options.skillPaths.length > 0 ? { skillPaths: options.skillPaths } : {}),
 			acp: {
-				transportOptions: { write: writeRawStdout },
+				// Stdout is JSON-RPC only. An unclassified handler failure answers the
+				// client with fixed host text; the original message, which nothing in
+				// this process authored, goes to the stderr tail.
+				transportOptions: {
+					write: writeRawStdout,
+					diagnostics: (line) => {
+						process.stderr.write(`[clio:acp] ${line}\n`);
+					},
+				},
 				...(flags.permissionTimeoutMs === undefined ? {} : { permissionTimeoutMs: flags.permissionTimeoutMs }),
 			},
 		});

package/src/cli/clio.ts

@@ -1,8 +1,18 @@
+import { formatBootTrace } from "../core/boot-trace.js";
 import { initializeClioHome } from "../core/init.js";
-import { type BootOptions, bootOrchestrator } from "../entry/orchestrator.js";
-import { runConfigureCommand } from "./configure.js";
+import { readLayeredSettings, readStrictLayeredSettings } from "../core/settings-layers.js";
+import type { BootOptions } from "../entry/boot-options.js";
 import { classifyDefaultTarget, describeVerdict } from "./default-target.js";
 
+/** Headless and ACP keep their established non-TUI transports even when an
+ * embedding process leaves the interactive marker in the environment. */
+export function terminalLeaseEligible(
+	options: Pick<BootOptions, "headless" | "acp">,
+	env: Readonly<Record<string, string | undefined>> = process.env,
+): boolean {
+	return !options.headless && !options.acp && env.CLIO_CODER_INTERACTIVE === "1";
+}
+
 export async function runClioCommand(options: BootOptions = {}): Promise<number> {
 	// Bare `clio` (no subcommand) boots interactive mode implicitly, but only
 	// when stdin is a real TTY. Piped or /dev/null stdin (used by verify.ts,
@@ -12,9 +22,14 @@ export async function runClioCommand(options: BootOptions = {}): Promise<number>
 	if (!options.headless && !options.acp && process.env.CLIO_CODER_INTERACTIVE === undefined && process.stdin.isTTY) {
 		process.env.CLIO_CODER_INTERACTIVE = "1";
 	}
-	if (process.env.CLIO_CODER_INTERACTIVE === "1") {
+	let startupSettings: import("../core/config.js").ClioSettings | undefined;
+	if (terminalLeaseEligible(options)) {
 		initializeClioHome();
-		const verdict = classifyDefaultTarget();
+		// The user file remains a strict gate. Project layers retain their
+		// established best-effort diagnostics, but every subsequent boot phase
+		// consumes this same effective snapshot.
+		startupSettings = readStrictLayeredSettings(process.cwd()).settings;
+		const verdict = classifyDefaultTarget(startupSettings);
 		if (verdict.kind === "missing-credential") {
 			// Diagnosis without a detour. The session continues, because whether
 			// the credential is actually required is the endpoint's answer to
@@ -25,10 +40,57 @@ export async function runClioCommand(options: BootOptions = {}): Promise<number>
 			);
 		} else if (verdict.kind !== "usable") {
 			process.stdout.write(`${describeVerdict(verdict)} Starting \`clio-coder configure\`.\n`);
+			const { runConfigureCommand } = await import("./configure.js");
 			const configured = await runConfigureCommand([]);
 			if (configured !== 0) return configured;
+			startupSettings = readStrictLayeredSettings(process.cwd()).settings;
+		}
+	}
+	let terminalLease: import("../interactive/terminal-lease.js").TerminalLease | undefined;
+	try {
+		if (terminalLeaseEligible(options)) {
+			const { createProcessTerminalLease, instantShellEnabled } = await import("../interactive/terminal-lease.js");
+			if (instantShellEnabled()) {
+				let stage0FrameId: number | null = null;
+				terminalLease = createProcessTerminalLease({
+					settings: startupSettings ?? readLayeredSettings(process.cwd()).settings,
+					onStage0Commit: (frameId) => {
+						stage0FrameId = frameId;
+					},
+				});
+				if (stage0FrameId !== null) {
+					const line = formatBootTrace("Stage 0 shell commit", `frameId=${stage0FrameId}`);
+					if (line) terminalLease.deferDiagnostic("stderr", line);
+				}
+			}
+		}
+		// Deterministic built-PTY interleaving seam. It is unavailable outside
+		// NODE_ENV=test and bounded even under a malformed value.
+		if (terminalLease && process.env.NODE_ENV === "test") {
+			const requestedDelay = Number.parseInt(process.env.CLIO_CODER_TEST_STAGE1_DELAY_MS ?? "0", 10);
+			const delayMs = Number.isFinite(requestedDelay) ? Math.max(0, Math.min(5_000, requestedDelay)) : 0;
+			if (delayMs > 0) await new Promise<void>((resolve) => setTimeout(resolve, delayMs));
+			if (process.env.CLIO_CODER_TEST_STAGE1_FAIL === "1") {
+				throw new Error("injected Stage 1 hydration failure");
+			}
+		}
+		const { bootOrchestrator } = await import("../entry/orchestrator.js");
+		const result = await bootOrchestrator({
+			...options,
+			...(startupSettings ? { startupSettings } : {}),
+			...(terminalLease ? { terminalLease } : {}),
+		});
+		return result.exitCode;
+	} catch (error) {
+		try {
+			await terminalLease?.fail();
+		} catch (cleanupError) {
+			// Preserve the established boot failure as the primary error. The lease
+			// has already attempted every restoration step and reached `closed`.
+			process.stderr.write(
+				`Clio Coder: terminal cleanup also failed: ${cleanupError instanceof Error ? cleanupError.message : String(cleanupError)}\n`,
+			);
 		}
+		throw error;
 	}
-	const result = await bootOrchestrator(options);
-	return result.exitCode;
 }

package/src/cli/config-inspect.ts

@@ -12,12 +12,13 @@
  */
 
 import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { basename } from "node:path";
 import type { ClioSettings } from "../core/config.js";
 import { readLayeredSettings, type SettingsOrigin, settingsSourceFor } from "../core/settings-layers.js";
 import { clioDataDir } from "../core/xdg.js";
 import {
 	loadOperatorProfile,
+	loadProjectClioMd,
 	loadProjectRules,
 	renderOperatorProfile,
 	renderPromptContext,
@@ -51,7 +52,7 @@ export interface CustomizationEntry {
 	sourcePath?: string;
 	hash?: string;
 	trust?: "trusted" | "untrusted" | "n/a";
-	precedence?: "winner" | "loser" | "single";
+	precedence?: "winner" | "loser" | "single" | "layer";
 	reloadClass: ReloadClass;
 	/** Token cost where the item enters the prompt; absent when it does not. */
 	contextCostTokens?: number;
@@ -105,29 +106,34 @@ function inspectSettings(cwd: string, graph: CustomizationGraph): void {
 }
 
 function inspectClioMd(cwd: string, graph: CustomizationGraph): void {
-	const path = join(cwd, "CLIO-CODER.md");
-	if (!existsSync(path)) return;
+	const loaded = loadProjectClioMd(cwd);
+	for (const issue of loaded.errors) graph.issues.push(`clio-md ${issue.path}: ${issue.error}`);
+	if (loaded.files.length === 0) return;
 	try {
-		const text = readFileSync(path, "utf8");
 		const promptContext = renderPromptContext(cwd);
 		const preload = classifyProjectPreload({ hasClioMd: promptContext.clioMd !== null, text: promptContext.text });
-		graph.entries.push({
-			category: "clio-md",
-			id: "CLIO-CODER.md",
-			scope: "project",
-			sourcePath: path,
-			hash: shortHash(text),
-			trust: "trusted",
-			precedence: "single",
-			reloadClass: "next-turn",
-			contextCostTokens: ceilChars(text.length),
-			detail: {
-				preload: preload.label,
-				preloadChars: preload.chars,
-				preloadLines: preload.lines,
-				...(preload.nearLimit ? { preloadNearLimit: true } : {}),
-			},
-		});
+		for (const [index, file] of loaded.files.entries()) {
+			const text = readFileSync(file.path, "utf8");
+			graph.entries.push({
+				category: "clio-md",
+				id: basename(file.path),
+				scope: "project",
+				sourcePath: file.path,
+				hash: shortHash(text),
+				trust: "trusted",
+				precedence: loaded.files.length === 1 ? "single" : "layer",
+				reloadClass: "next-turn",
+				contextCostTokens: ceilChars(text.length),
+				detail: {
+					layer: index + 1,
+					layers: loaded.files.length,
+					preload: preload.label,
+					preloadChars: preload.chars,
+					preloadLines: preload.lines,
+					...(preload.nearLimit ? { preloadNearLimit: true } : {}),
+				},
+			});
+		}
 	} catch (err) {
 		graph.issues.push(`clio-md: ${err instanceof Error ? err.message : String(err)}`);
 	}