@iowarp/clio-coder 0.4.3 → 0.4.5

package/evals/source-explanation-grader.mjs

@@ -0,0 +1,118 @@
+import { strict as assert } from "node:assert";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const fixture = JSON.parse(readFileSync(new URL("./fixtures/source-explanation.json", import.meta.url), "utf8"));
+
+// A bounded content screen, not a semantic judge. Root must still review the
+// cited claims. In particular, schema success and pane lifecycle are not delivery.
+export function assessExplanation(agentId, output, conformance) {
+	let value;
+	try {
+		value = JSON.parse(output);
+	} catch {
+		value = {};
+	}
+	const findings = Array.isArray(value.findings) ? value.findings : [];
+	const prose = agentId === "scout" ? findings.map((finding) => finding.claim ?? "").join(" ") : (value.summary ?? "");
+	const words = typeof prose === "string" && prose.trim() ? prose.trim().split(/\s+/u).length : 0;
+	// Scout cites through structured findings; Coder cites inline as file:line
+	// inside its summary, the declared place for a read-only explanation.
+	const cited = Object.keys(fixture.files).every((path) =>
+		agentId === "scout"
+			? findings.some((finding) => finding.path === path && Number.isSafeInteger(finding.line) && finding.line > 0)
+			: new RegExp(`${path.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&")}:[1-9]\\d*`, "u").test(prose),
+	);
+	const topics = [
+		/uniform/iu,
+		/nonuniform/iu,
+		/forward/iu,
+		/backward/iu,
+		/spacing/iu,
+		/coordinate/iu,
+		/convergence/iu,
+		/linspace|equidistant/iu,
+		/does not|do not|not .*irregular/iu,
+	].every((pattern) => pattern.test(prose));
+	// Both recipes carry a 1200-word cited explanation: Scout as findings, Coder
+	// in its mutation-report summary under the contract's summary allowance.
+	const suitable = agentId === "scout" || agentId === "coder";
+	const limited = agentId === "coder" && /cannot deliver/iu.test(prose) && /allowance|UTF-8 bytes/iu.test(prose);
+	return {
+		"explanation.recipeSuitable": suitable,
+		"explanation.conforms": conformance === "pass",
+		"explanation.delivered":
+			conformance === "pass" &&
+			suitable &&
+			cited &&
+			topics &&
+			words >= fixture.wordRange[0] &&
+			words <= fixture.wordRange[1],
+		"explanation.limited": limited,
+		"explanation.words": words,
+	};
+}
+
+function prepare() {
+	for (const path of Object.keys(fixture.files)) assert.ok(!existsSync(path), `refuse to overwrite ${path}`);
+	for (const [path, content] of Object.entries(fixture.files)) {
+		mkdirSync(dirname(path), { recursive: true });
+		writeFileSync(path, content);
+	}
+}
+
+async function grade(agentId) {
+	assert.ok(agentId === "coder" || agentId === "scout");
+	const events = readFileSync(process.env.CLIO_CODER_EVAL_RUNNER_STDOUT_FILE, "utf8")
+		.split(/\r?\n/u)
+		.flatMap((line) => {
+			try {
+				return [JSON.parse(line)];
+			} catch {
+				return [];
+			}
+		});
+	const starts = events.filter((event) => event.type === "tool_execution_start" && event.toolName === "dispatch");
+	assert.equal(starts.length, 1, "one explicitly selected worker; no substituted or extra recovery dispatch");
+	assert.equal(starts[0].args.agent, agentId);
+	assert.equal(starts[0].args.task, fixture.task);
+	const end = events.find((event) => event.type === "tool_execution_end" && event.toolCallId === starts[0].toolCallId);
+	const runs = end?.result?.details?.runs;
+	assert.equal(runs?.length, 1, "one terminal receipt required");
+	const receipt = JSON.parse(readFileSync(runs[0].receiptPath, "utf8"));
+	assert.equal(receipt.agentId, agentId);
+	const metrics = assessExplanation(agentId, receipt.output?.text ?? "", receipt.quality?.resultContract?.conformance);
+	if (
+		receipt.outcome !== "succeeded" ||
+		receipt.exitCode !== 0 ||
+		receipt.quality?.resultContract?.quality === "fail" ||
+		receipt.output?.state !== "final" ||
+		receipt.output?.truncated !== false
+	)
+		metrics["explanation.delivered"] = false;
+	metrics["task.solved"] = metrics["explanation.delivered"];
+	process.stdout.write(`${JSON.stringify({ schema: "clio-coder.eval.measure.v1", metrics })}\n`);
+	assert.equal(receipt.outcome, "succeeded");
+	assert.equal(receipt.exitCode, 0);
+	assert.equal(receipt.output?.state, "final");
+	assert.equal(receipt.output?.truncated, false, "a truncated report is not complete delivery");
+	assert.equal(metrics["explanation.conforms"], true);
+	assert.notEqual(receipt.quality?.resultContract?.quality, "fail");
+	assert.equal(metrics["explanation.recipeSuitable"], true);
+	assert.equal(metrics["explanation.delivered"], true);
+	assert.equal(metrics["explanation.limited"], false);
+	for (const [path, content] of Object.entries(fixture.files)) assert.equal(readFileSync(path, "utf8"), content);
+	// Headless runs cannot assert watch-pane lifecycle. Root records it separately.
+	assert.ok(metrics["task.solved"], "the requested explanation was not delivered in the declared result shape");
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	try {
+		if (process.argv[2] === "--prepare") prepare();
+		else await grade(process.argv[2]);
+	} catch (error) {
+		process.stderr.write(`${error instanceof Error ? error.stack : String(error)}\n`);
+		process.exitCode = 1;
+	}
+}

package/evals/tool-surface-grader.mjs

@@ -0,0 +1,53 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+const events = readFileSync(process.env.CLIO_CODER_EVAL_RUNNER_STDOUT_FILE, "utf8")
+	.split(/\r?\n/u)
+	.flatMap((line) => {
+		try {
+			return [JSON.parse(line)];
+		} catch {
+			return [];
+		}
+	});
+const starts = events.filter((event) => event.type === "tool_execution_start");
+const ends = events.filter((event) => event.type === "tool_execution_end");
+function output(call) {
+	const end = ends.find((event) => event.toolCallId === call.toolCallId);
+	assert.ok(end, "required tool call did not finish");
+	return JSON.stringify(end.result);
+}
+switch (process.argv[2]) {
+	case "read-tail": {
+		assert.equal(starts.length, 1);
+		const call = starts[0];
+		assert.equal(call.toolName, "read");
+		assert.equal(resolve(call.args.path), resolve("evals/fixtures/tool-surface/read.txt"));
+		assert.equal(call.args.tail, 2, "last-line probe must use the advertised tail argument");
+		assert.match(output(call), /gamma/u);
+		assert.match(output(call), /delta/u);
+		assert.doesNotMatch(output(call), /alpha|beta/u);
+		break;
+	}
+	case "bash-cwd-reset": {
+		assert.equal(starts.length, 2);
+		assert.ok(starts.every((call) => call.toolName === "bash"));
+		assert.equal(starts[0].args.command.trim(), "cd evals/fixtures/tool-surface/subdir && pwd");
+		assert.equal(starts[1].args.command.trim(), "pwd");
+		assert.equal(starts[1].args.cwd, undefined);
+		assert.ok(output(starts[0]).includes(resolve("evals/fixtures/tool-surface/subdir")));
+		assert.ok(output(starts[1]).includes(process.cwd()));
+		assert.ok(!output(starts[1]).includes("/tool-surface/subdir"));
+		break;
+	}
+	case "web-fetch-scheme": {
+		assert.equal(starts.length, 1);
+		assert.equal(starts[0].toolName, "web_fetch");
+		assert.equal(starts[0].args.url, "file:///tool-surface-fixture");
+		assert.match(output(starts[0]), /(?:unsupported|invalid|only)[\s\S]*(?:scheme|https?)/iu);
+		break;
+	}
+	default:
+		throw new Error("unknown tool surface case");
+}

package/evals/tool-surface-model.yaml

@@ -0,0 +1,274 @@
+version: 2
+suite:
+  id: tool-surface-model
+  title: Tool description and argument behavior
+  visibility: public
+  description: Model-required probes of read tail selection, bash child directory
+    reset, and web_fetch URL rejection. Expected rejection is distinct from
+    unintended tool errors.
+matrix:
+  targets:
+    - id: mini
+  repeats: 3
+tasks:
+  - id: read-tail
+    tags:
+      - behavioral
+      - model-required
+      - tool:read
+    behavioral:
+      schema: clio-coder.eval.scenario.v1
+      corpus:
+        id: tool-surface-model
+        version: 1.0.0
+      execution:
+        mode: model-required
+        subject:
+          kind: main-agent
+          role: main
+        toolTarget: available
+      expectedBehavior:
+        - id: read-tail-calls
+          category: tool_choice
+          fact:
+            source: tool
+            key: tools.calls.read
+            op: eq
+            value: 1
+        - id: read-tail-errors
+          category: tool_choice
+          fact:
+            source: tool
+            key: tools.failed.read
+            op: eq
+            value: 0
+        - id: read-tail-blocks
+          category: safety_comprehension
+          fact:
+            source: tool
+            key: tools.blocked.read
+            op: eq
+            value: 0
+        - id: read-tail-successes
+          category: tool_choice
+          fact:
+            source: tool
+            key: tools.succeeded.read
+            op: eq
+            value: 1
+        - id: read-tail-correct
+          category: task_correctness
+          fact:
+            source: grader
+            key: task.solved
+            op: eq
+            value: true
+      forbiddenBehavior: []
+      judge:
+        maxEvidenceItems: 32
+        maxExplanationChars: 500
+    workspace:
+      kind: temp-copy
+      path: ..
+      excludes:
+        - .git
+        - .superpowers
+        - node_modules
+        - dist
+    runner:
+      kind: clio-coder-run
+      autonomy: auto-edit
+      prompt: Read only the final two lines of evals/fixtures/tool-surface/read.txt
+        using one read call. Do not read the entire file or use other tools.
+        Report those lines. Do not edit files.
+    verify:
+      measure:
+        - node evals/tool-surface-grader.mjs read-tail
+      protectedFiles:
+        - evals/tool-surface-grader.mjs
+        - evals/fixtures/tool-surface/read.txt
+        - evals/fixtures/tool-surface/subdir/keep.txt
+    metrics:
+      collect:
+        - task.solved
+        - tools.totalCalls
+        - tools.calls.read
+        - tools.failed.read
+        - tools.blocked.read
+        - tools.succeeded.read
+    timeoutMs: 120000
+  - id: bash-cwd-reset
+    tags:
+      - behavioral
+      - model-required
+      - tool:bash
+    behavioral:
+      schema: clio-coder.eval.scenario.v1
+      corpus:
+        id: tool-surface-model
+        version: 1.0.0
+      execution:
+        mode: model-required
+        subject:
+          kind: main-agent
+          role: main
+        toolTarget: available
+      expectedBehavior:
+        - id: bash-cwd-reset-calls
+          category: tool_choice
+          fact:
+            source: tool
+            key: tools.calls.bash
+            op: eq
+            value: 2
+        - id: bash-cwd-reset-errors
+          category: tool_choice
+          fact:
+            source: tool
+            key: tools.failed.bash
+            op: eq
+            value: 0
+        - id: bash-cwd-reset-blocks
+          category: safety_comprehension
+          fact:
+            source: tool
+            key: tools.blocked.bash
+            op: eq
+            value: 0
+        - id: bash-cwd-reset-successes
+          category: tool_choice
+          fact:
+            source: tool
+            key: tools.succeeded.bash
+            op: eq
+            value: 2
+        - id: bash-cwd-reset-correct
+          category: task_correctness
+          fact:
+            source: grader
+            key: task.solved
+            op: eq
+            value: true
+      forbiddenBehavior: []
+      judge:
+        maxEvidenceItems: 32
+        maxExplanationChars: 500
+    workspace:
+      kind: temp-copy
+      path: ..
+      excludes:
+        - .git
+        - .superpowers
+        - node_modules
+        - dist
+    runner:
+      kind: clio-coder-run
+      autonomy: auto-edit
+      prompt: Use exactly two bash calls and no other tools. First run cd
+        evals/fixtures/tool-surface/subdir && pwd. Then run pwd with no cwd
+        argument, relying on the documented default directory of a new bash
+        call. Report whether the second call starts at the workspace root. Do
+        not edit files.
+    verify:
+      measure:
+        - node evals/tool-surface-grader.mjs bash-cwd-reset
+      protectedFiles:
+        - evals/tool-surface-grader.mjs
+        - evals/fixtures/tool-surface/read.txt
+        - evals/fixtures/tool-surface/subdir/keep.txt
+    metrics:
+      collect:
+        - task.solved
+        - tools.totalCalls
+        - tools.calls.bash
+        - tools.failed.bash
+        - tools.blocked.bash
+        - tools.succeeded.bash
+    timeoutMs: 120000
+  - id: web-fetch-scheme
+    tags:
+      - behavioral
+      - model-required
+      - tool:web_fetch
+    behavioral:
+      schema: clio-coder.eval.scenario.v1
+      corpus:
+        id: tool-surface-model
+        version: 1.0.0
+      execution:
+        mode: model-required
+        subject:
+          kind: main-agent
+          role: main
+        toolTarget: available
+      expectedBehavior:
+        - id: web-fetch-scheme-calls
+          category: tool_choice
+          fact:
+            source: tool
+            key: tools.calls.web_fetch
+            op: eq
+            value: 1
+        - id: web-fetch-scheme-errors
+          category: tool_choice
+          fact:
+            source: tool
+            key: tools.failed.web_fetch
+            op: eq
+            value: 1
+        - id: web-fetch-scheme-blocks
+          category: safety_comprehension
+          fact:
+            source: tool
+            key: tools.blocked.web_fetch
+            op: eq
+            value: 0
+        - id: web-fetch-scheme-successes
+          category: tool_choice
+          fact:
+            source: tool
+            key: tools.succeeded.web_fetch
+            op: eq
+            value: 0
+        - id: web-fetch-scheme-correct
+          category: task_correctness
+          fact:
+            source: grader
+            key: task.solved
+            op: eq
+            value: true
+      forbiddenBehavior: []
+      judge:
+        maxEvidenceItems: 32
+        maxExplanationChars: 500
+    workspace:
+      kind: temp-copy
+      path: ..
+      excludes:
+        - .git
+        - .superpowers
+        - node_modules
+        - dist
+    runner:
+      kind: clio-coder-run
+      autonomy: auto-edit
+      prompt: "Probe the web_fetch URL validation once with
+        file:///tool-surface-fixture. This is an intentional invalid-scheme
+        test: invoke web_fetch exactly once, report the rejection, and do not
+        retry or use other tools. Do not edit files."
+    verify:
+      measure:
+        - node evals/tool-surface-grader.mjs web-fetch-scheme
+      protectedFiles:
+        - evals/tool-surface-grader.mjs
+        - evals/fixtures/tool-surface/read.txt
+        - evals/fixtures/tool-surface/subdir/keep.txt
+    metrics:
+      collect:
+        - task.solved
+        - tools.totalCalls
+        - tools.calls.web_fetch
+        - tools.failed.web_fetch
+        - tools.blocked.web_fetch
+        - tools.succeeded.web_fetch
+    timeoutMs: 120000

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@iowarp/clio-coder",
-	"version": "0.4.3",
+	"version": "0.4.5",
 	"description": "The terminal coding agent for people who maintain the code that science runs on, with user-chosen models and inspectable evidence.",
 	"keywords": [
 		"ai",
@@ -76,15 +76,15 @@
 		"pi:surface-diff": "node --import tsx scripts/pi-surface-diff.ts",
 		"pi:surface-snapshot": "node --import tsx scripts/pi-surface-diff.ts --write",
 		"test:file": "node --import tsx --import ./tests/harness/tmp-root.ts --test",
-		"pretest": "test -f dist/cli/index.js || npm run build",
+		"pretest": "test -f dist/cli/index.js || pnpm run build",
 		"test": "node --import tsx --import ./tests/harness/tmp-root.ts --test tests/contracts/*.test.ts tests/smoke/*.test.ts",
-		"test:trace-viewer": "npm --prefix apps/trace-viewer test",
+		"test:trace-viewer": "pnpm --filter @iowarp/clio-trace-viewer test",
 		"trace:ui": "node apps/trace-viewer/server.mjs",
-		"ci": "npm run typecheck && npm run lint && npm run build && npm run test && npm run test:trace-viewer",
-		"ci:release": "npm run ci && node scripts/check-release.mjs",
+		"ci": "pnpm run typecheck && pnpm run lint && pnpm run build && pnpm run test && pnpm run test:trace-viewer",
+		"ci:release": "pnpm run ci && node scripts/check-release.mjs",
 		"install:local": "bash scripts/install-local.sh",
 		"smoke:real-home": "bash scripts/smoke-real-home.sh",
-		"prepublishOnly": "CLIO_CODER_RELEASE_CONTEXT=publish npm run ci:release",
+		"prepublishOnly": "CLIO_CODER_RELEASE_CONTEXT=publish pnpm run ci:release",
 		"skills:pin": "node --import tsx scripts/pin-skills.ts",
 		"skills:check": "node --import tsx scripts/pin-skills.ts --check"
 	},
@@ -92,18 +92,14 @@
 		"@anthropic-ai/claude-agent-sdk": "0.3.186"
 	},
 	"dependencies": {
-		"@earendil-works/pi-agent-core": "0.84.4",
-		"@earendil-works/pi-ai": "0.84.4",
-		"@earendil-works/pi-tui": "0.84.4",
+		"@earendil-works/pi-agent-core": "0.85.1",
+		"@earendil-works/pi-ai": "0.85.1",
+		"@earendil-works/pi-tui": "0.85.1",
 		"@silvia-odwyer/photon-node": "^0.3.4",
 		"grok-mermaid": "0.2.2",
 		"ollama": "0.6.3",
 		"smol-toml": "1.8.0"
 	},
-	"overrides": {
-		"@anthropic-ai/sdk": "0.105.0",
-		"esbuild": "0.28.1"
-	},
 	"devDependencies": {
 		"@biomejs/biome": "2.5.1",
 		"@types/node": "24.12.2",
@@ -119,5 +115,9 @@
 		"typescript": "6.0.3",
 		"uuid": "14.0.1",
 		"yaml": "2.9.0"
-	}
+	},
+	"packageManager": "pnpm@10.34.5",
+	"workspaces": [
+		"apps/*"
+	]
 }

package/skills/README.md

@@ -193,7 +193,7 @@ clio-coder skills install find-skills --project  # strongest discovered project
 
 ## Publishing: the marketplace index
 
-`npm run skills:pin` writes two files. `registry.yaml` pins content hashes and
+`pnpm run skills:pin` writes two files. `registry.yaml` pins content hashes and
 is what drift is measured against. `skill-marketplace.json` is the published
 index: one entry per skill with `name`, `description`, optional `triggers`,
 `sourceUrl` (the skill's own `clio-coder.source-url`), `version`, `audit`, and
@@ -213,7 +213,7 @@ Install then clones the repository named in that entry's `sourceUrl` and copies
 the skill out of it, so the index is only as live as the branch its URLs name.
 The catalog's `source-url` values all point at `main`; until a release branch
 lands there, an install through the index fails naming the repository, the
-branch, and the missing path. `npm run skills:check` fails if a skill's
+branch, and the missing path. `pnpm run skills:check` fails if a skill's
 `source-url` stops ending with its catalog path, which is how a skill moved
 between categories cannot ship a stale pointer.
 
@@ -292,7 +292,7 @@ dependency warnings, and other harnesses ignore it like any unknown key.
 
 The deprecated nested `clio:` mapping and legacy flat keys (`registry-id`,
 `source-url`, `audit` at the top level) are still read as fallbacks for older
-installed copies. The catalog itself must use `clio-coder:`, and `npm run
+installed copies. The catalog itself must use `clio-coder:`, and `pnpm run
 skills:check` enforces that.
 
 ### Versioning policy
@@ -350,7 +350,7 @@ names rather than mapping them. Translating `bash` to `Bash` for
 Claude-compatibility would not restrict anything; it would silently add `Bash`
 to the always-allow rules of every session that loaded the skill. The same goes
 for a `clio-coder skills export --for claude` lane, so there is no such lane. To keep
-a well-meaning edit from introducing that, `npm run skills:check` fails on any
+a well-meaning edit from introducing that, `pnpm run skills:check` fails on any
 `allowed-tools` entry that is not a Clio tool name in canonical lowercase.
 
 The rest of the surface, read from the same build:
@@ -401,10 +401,10 @@ observed writing outside its workspace. Eval numbers are evidence about a
 cooperative model, not an isolation guarantee. Run campaigns with `CLIO_CODER_*`
 pointed at throwaway directories.
 
-`npm run skills:pin` enforces this contract structurally: it refuses to pin a
+`pnpm run skills:pin` enforces this contract structurally: it refuses to pin a
 catalog where any skill is missing the required frontmatter, `audit: pass`, or
 its `evals.md`, declares a tool name Clio does not have, or carries a
-`source-url` that no longer ends with its catalog path. `npm run skills:check`
+`source-url` that no longer ends with its catalog path. `pnpm run skills:check`
 (run in CI) fails on any drift between the catalog and either generated file,
 `registry.yaml` or `skill-marketplace.json`. Each pin covers the normalized
 `SKILL.md`, not the whole skill directory. Install-lifecycle stamps such as

package/skills/coding/coding-standards/SKILL.md

@@ -7,8 +7,17 @@ triggers:
   - parse don't validate
   - illegal states unrepresentable
   - functional core imperative shell
-version: 0.3.0
+version: 0.4.0
 license: Apache-2.0
+allowed-tools:
+  - read
+  - grep
+  - find
+  - ls
+  - code_nav
+  - bash
+  - write
+  - edit
 clio-coder:
   registry-id: iowarp/clio-coder
   source-url: https://github.com/iowarp/clio-coder/tree/main/skills/coding/coding-standards
@@ -33,9 +42,10 @@ code, and never rewrite unrelated old code without an explicit migration
 request. **The host project's own documented standards always win over
 this file.**
 
-This skill declares no tool surface on purpose: it rides along with
-whatever task is in flight (writing, refactoring, reviewing), so it must
-not narrow the tools that task needs.
+This skill's tool surface covers the whole write-code loop (read, grep,
+find, ls, code_nav, bash, write, edit) so a solo run can apply the rules
+it names. When it rides along with another skill, the surfaces merge as a
+union, so it never narrows the tools the task in flight needs.
 
 ## Arguments
 

package/skills/context/context-handoff/SKILL.md

@@ -7,7 +7,7 @@ triggers:
   - handoff to another agent
   - context is about to be lost
   - write a continuation brief
-version: 0.5.0
+version: 0.5.1
 license: Apache-2.0
 allowed-tools:
   - read
@@ -65,8 +65,8 @@ Distinct from two things it is often confused with:
   actionable one as the focus; state that reading in the draft's "Next
   session focus" line rather than leaving it blank.
 
-There is no operator in a headless run: `ask_user` is not registered and
-nothing will answer it even if you call it. If the focus, slug, or a
+There is no operator in a headless run: `ask_user` is not registered, so
+any call is refused as an unregistered tool rather than answered. If the focus, slug, or a
 redaction call is ambiguous, state your best reading in the draft and in your
 final reply, and proceed — never stall a step waiting on `ask_user`.
 

package/skills/context/context-prime/SKILL.md

@@ -7,7 +7,7 @@ triggers:
   - where were we
   - get up to speed
   - resume repository work after a break
-version: 0.4.0
+version: 0.4.1
 license: Apache-2.0
 allowed-tools:
   - read
@@ -96,8 +96,8 @@ Work top to bottom; stop early once you have enough to state where things stand.
    ending with the focus to confirm. `ask_user` is only registered in an
    interactive session with an operator present; call it there, offering
    the handoff's suggested focus as the first option. **A headless run has
-   no operator: `ask_user` is not registered and nothing will answer it
-   even if you call it.** If it is not among your available tools, do not
+   no operator: `ask_user` is not registered, so any call is refused as an
+   unregistered tool rather than answered.** If it is not among your available tools, do not
    attempt it and do not keep re-reading files hoping for more certainty
    first — state the focus as the orientation's `Next` line, in plain
    text, and stop; that written statement is the confirmation for this

package/skills/planning/architecture/SKILL.md

@@ -7,7 +7,7 @@ triggers:
   - architecture for this feature
   - decide the engineering approach
   - compare architecture options
-version: 0.4.0
+version: 0.4.1
 license: Apache-2.0
 allowed-tools:
   - read
@@ -64,10 +64,10 @@ expensive calls only).
   to Step 0's own question — what are we building, and is there a written
   intent to read — rather than inventing a project to architect.
 
-There is no operator in a headless run: `ask_user` still executes, but with
-nothing to answer it every call returns immediately with no answers, every
-time — calling it again will not produce a different result. From wherever
-the first empty response lands — Step 0's "ask whether reference docs
+There is no operator in a headless run: `ask_user` is not registered, so
+any call is refused as an unregistered tool rather than answered, every
+time; calling it again will not produce a different result. From wherever
+the first refusal lands — Step 0's "ask whether reference docs
 exist", Step 1's greenfield/brownfield call, or any decision in Step 2 —
 switch immediately to the treatment already described above (state the
 options, the recommendation, the reasoning, adopt it, mark it `assumed —

package/skills/planning/backlog/SKILL.md

@@ -7,7 +7,7 @@ triggers:
   - build the backlog
   - decompose this plan into tickets
   - create GitHub issues from this architecture
-version: 0.4.0
+version: 0.4.1
 license: Apache-2.0
 allowed-tools:
   - read
@@ -47,9 +47,9 @@ tracker. Decomposition is tracker-agnostic; creation branches on the target.
   (Step 1's own rule picks it — see below) and a milestone/epic to attach
   tickets to.
 
-There is no operator in a headless run: `ask_user` resolves immediately
-with no answer, every time it is called — not a stall, and calling it again
-will not produce a different result. **This skill treats headless
+There is no operator in a headless run: `ask_user` is not registered, so
+any call is refused as an unregistered tool rather than answered; that is
+not a stall, and calling it again will not produce a different result. **This skill treats headless
 degradation differently at each step below, because Step 3 gates an
 outward, not-cleanly-reversible action — real tickets, GitHub issues or
 persisted local tasks — not a document write:**