@iowarp/clio-coder 0.4.3 → 0.4.4

package/docs/process/release-cut-checklist.md

@@ -0,0 +1,207 @@
+# Release-Cut Checklist
+
+> **Visual blueprint:** The source checkout includes the complete
+> [Release-Cut Checklist visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/release_checklist_blueprint.html).
+
+This document provides the standard procedure for cutting a release of Clio Coder.
+Releases are cut from an annotated tag on canonical main. The GitHub release is
+produced by GitHub Actions, while package publication to npm is an authorized manual
+step performed by a maintainer. Everything before the authorization boundary is local,
+repeatable, and reversible. Every step following the authorization boundary affects
+canonical remote state or publishes immutable packages.
+
+## Part 1: Candidate Preparation on a Local Compact Branch
+
+Maintainers prepare release candidates on a local-only compact branch named after
+the version without punctuation, such as `v044` for version `0.4.4`. Dotted branch
+names like `v0.4.4` are forbidden because dotted names belong exclusively to immutable
+tags. The canonical repository hosts only `main`, and no release candidate branch is
+ever pushed to canonical origin.
+
+1. Ensure the working tree is clean and updated from canonical origin:
+
+   ```bash
+   git checkout -b v044 origin/main
+   ```
+
+2. Update `version` in `package.json` to the release version.
+
+3. Retitle the active changelog section in `CHANGELOG.md` from `## Unreleased` to
+   `## <version> - YYYY-MM-DD`. The release gate in `scripts/check-release.mjs` requires
+   the first version header to match the version in `package.json`.
+
+4. Commit the release candidate preparation locally:
+
+   ```bash
+   git commit -am "chore(release): prepare <version>"
+   ```
+
+## Part 2: Local Candidate Verification Gate
+
+Run deterministic local checks on the candidate commit before requesting authorization.
+
+1. Execute the release gate:
+
+   ```bash
+   npm run ci:release
+   ```
+
+   This gate runs `npm run ci` followed by `node scripts/check-release.mjs`. It verifies
+   type checking, Biome formatting, hygiene rules, architecture boundary invariants,
+   the build, the contract and smoke test suites, trace-viewer tests, and dist integrity.
+   The packaging audit checks executable entry shebangs, ensures forbidden files like
+   source maps and caches are omitted, verifies runtime resources from `scripts/release-manifest.json`,
+   and enforces size limits (10 MB packed, 50 MB unpacked).
+
+2. Optionally validate a live model turn against a configured target:
+
+   ```bash
+   node dist/cli/index.js run --target <id> --autonomy read-only "Reply with exactly: CLIO_LIVE_OK"
+   ```
+
+3. Run the real-home smoke test against the operator configuration:
+
+   ```bash
+   npm run smoke:real-home -- --target <id> --strict
+   ```
+
+   This runs `scripts/smoke-real-home.sh` using a copy of operator settings in a scratch
+   `CLIO_CODER_HOME`. The `--strict` flag ensures any failing rows from `clio-coder doctor`
+   fail the smoke run.
+
+4. Inspect the npm package contents with a dry run:
+
+   ```bash
+   npm pack --dry-run
+   ```
+
+5. Validate an installed tarball in a clean temporary directory:
+
+   Create a temporary directory, pack the tarball, install it via npm, and verify
+   installed binary lifecycle commands in an isolated environment with an empty `CLIO_CODER_HOME`:
+
+   ```bash
+   clio-coder --version
+   clio-coder --help
+   clio-coder doctor
+   clio-coder uninstall --dry-run
+   ```
+
+## Part 3: Candidate Review and Authorization Boundary
+
+Before touching any remote ref, summarize the candidate for maintainer review:
+- Candidate commit SHA
+- Results of `npm run ci:release`
+- Verification output from real-home smoke and installed package testing
+- Changelog contents and target npm version
+
+Every step below changes canonical remote refs, creates a release, or publishes
+an immutable package. Do not execute any of them without explicit maintainer authorization.
+
+## Part 4: Fast-forward Canonical Main
+
+1. Fetch the latest remote status from origin:
+
+   ```bash
+   git fetch origin
+   ```
+
+2. Confirm `origin/main` is an ancestor of the local candidate branch.
+
+3. Fast-forward local `main` to the candidate commit:
+
+   ```bash
+   git checkout main
+   git merge --ff-only v044
+   ```
+
+4. Verify that local `main` matches the reviewed candidate SHA exactly.
+
+5. Push `main` to canonical origin:
+
+   ```bash
+   git push origin refs/heads/main:refs/heads/main
+   ```
+
+   No release branch is ever pushed to origin.
+
+## Part 5: Tagging and GitHub Release
+
+1. Wait for GitHub Actions CI on canonical `main` to finish green for the pushed SHA.
+
+2. Create an annotated git tag matching the version:
+
+   ```bash
+   git tag -a v<version> -m "Clio Coder <version>"
+   ```
+
+3. Push only the release tag to canonical origin:
+
+   ```bash
+   git push origin refs/tags/v<version>
+   ```
+
+4. Pushing the tag triggers `.github/workflows/release.yml`. The workflow:
+   - Verifies the tag matches `package.json`.
+   - Runs `npm run ci:release` on the tagged commit.
+   - Packs the release tarball with `npm pack`.
+   - Extracts the version changelog section from `CHANGELOG.md`.
+   - Creates the GitHub Release with the tarball attached using `gh release create`.
+
+5. Inspect the GitHub Actions workflow run and confirm the GitHub release is published.
+
+## Part 6: Package Publication to npm
+
+Publishing to npm is a manual maintainer step performed from the tagged commit.
+
+1. Confirm authentication and registry status:
+
+   ```bash
+   npm whoami
+   ```
+
+2. Confirm the version does not already exist on npm:
+
+   ```bash
+   npm view @iowarp/clio-coder@<version>
+   ```
+
+3. Publish the package from the tagged checkout:
+
+   ```bash
+   npm publish
+   ```
+
+   The `prepublishOnly` lifecycle script sets `CLIO_CODER_RELEASE_CONTEXT=publish` and
+   re-executes `npm run ci:release` as a mandatory release-mode verification gate before
+   files are uploaded. When publishing a pre-release channel, append `--tag <channel>`.
+
+## Part 7: Post-Publish Verification and Branch Closeout
+
+1. Verify package availability on npm:
+
+   ```bash
+   npm view @iowarp/clio-coder version
+   ```
+
+2. On a clean machine, install the package globally and run basic lifecycle checks:
+
+   ```bash
+   npm install -g @iowarp/clio-coder@<version>
+   clio-coder --version
+   clio-coder doctor
+   ```
+
+3. Remove the local compact candidate branch:
+
+   ```bash
+   git branch -d v044
+   ```
+
+   The canonical repository remains in its steady state containing only `main` and immutable tags.
+
+## Part 8: Rollback and Error Recovery
+
+npm package publication is irreversible. A published version cannot be removed or overwritten.
+Any issue discovered after publication must be resolved through a subsequent release. Prior
+to pushing git tags or publishing to npm, local candidate commits can be amended or reset freely.

package/docs/process/scientific-validation.md

@@ -5,19 +5,19 @@
 
 Scientific software development cannot treat simple file presence as proof of correctness. A simulation script that crashes on rank 48, or writes out NetCDF arrays filled with `NaN`s, may still successfully write a file to the disk. 
 
-Clio Coder recognizes **scientific validation contract files** as an opt-in signal for a higher evidence bar. Currently, the session rigor resolver does not parse or enforce a scientific contract schema. The presence of `.clio-coder/validation.yaml`, `.clio-coder/validation.yml`, `validation.yaml`, `validation.yml`, or `VALIDATION.md` at the workspace root raises the default rigor level to `high`; the file contents are advisory material for developers, project agents, and external validators.
+Clio Coder recognizes a **scientific validation contract** as an opt-in signal for a higher evidence bar. One strict loader in `src/domains/safety/validation-contract.ts` reads the first of `.clio-coder/validation.yaml`, `.clio-coder/validation.yml`, `validation.yaml`, or `validation.yml` at the workspace root and parses it under the version-1 schema below. A contract that parses raises the default rigor level to `high`. A contract that does not parse (empty, malformed YAML, unknown field, unsupported version, over the 256 KiB cap) leaves rigor at `normal` and is diagnosed with the exact fault: `clio-coder doctor` reports it in the `validation contract` row, the interactive session prints it once at startup, and `clio-coder verifiers author` repeats it. A Markdown `VALIDATION.md` is recognized as present but is never parsed and never raises rigor on its own; it is advisory prose for developers, project agents, and external validators.
 
-This advisory convention is separate from the executable project verifier catalog at `.clio-coder/verifiers.yaml`. The verifier catalog has a strict version-1 schema and admits exact argv vectors to the `verify` tool. Scientific validation contracts and handbook expectations do not grant command authority: prose such as `validators: ["python tools/check_grid.py"]` remains guidance until the project owner confirms the equivalent argv, cwd, timeout, and tags in `verifiers.yaml`. The executable catalog does not interpret numerical tolerances or artifact expectations; it only runs the explicitly declared process vector through safe-exec.
+This advisory convention is separate from the executable project verifier catalog at `.clio-coder/verifiers.yaml`. The verifier catalog has a strict schema (version 2, with version 1 still loading) and admits exact argv vectors to the `verify` tool. Scientific validation contracts and handbook expectations do not grant command authority: prose such as `validators: ["python tools/check_grid.py"]` remains guidance until the project owner confirms the equivalent argv, cwd, timeout, and tags in `verifiers.yaml`. The executable catalog runs only the explicitly declared process vector through safe-exec; a `numeric-compare` or `perf-budget` entry adds a judgement of that command's output or wall time, never an interpretation of the contract's artifact expectations.
 
-`clio-coder verifiers author` can inspect top-level `validators` entries in the YAML contract filenames above and propose catalog checks. It labels those vectors as project-declared and shows their source index, exact argv, cwd, timeout, tags, catalog path, and resulting execution authority. This inspection is read-only. A command string with sound quoting and no shell operator can be represented as argv for review; shell expansion, pipes, redirection, environment assignments, incomplete quoting, and Markdown prose receive a manual JSON-argv diagnostic. Nothing becomes executable and nothing is dry-run until the operator confirms the catalog write with `--yes`.
+`clio-coder verifiers author` reads the parsed contract's `validators` entries through the same loader and proposes catalog checks. It labels those vectors as project-declared and shows their source index, exact argv, cwd, timeout, tags, catalog path, and resulting execution authority. This inspection is read-only. A command string with sound quoting and no shell operator can be represented as argv for review; shell expansion, pipes, redirection, environment assignments, incomplete quoting, and Markdown prose receive a manual JSON-argv diagnostic. Nothing becomes executable and nothing is dry-run until the operator confirms the catalog write with `--yes`.
 
-The convention below is a recommended shape for scientific projects that need to document expected dimensions, attributes, numerical tolerances, scheduler context, and verification commands for scientific artifacts. Developed at the [Gnosis Research Center (GRC)](https://grc.iit.edu) at Illinois Tech as part of the NSF-funded scientific-software context (NSF Award [#2411318](https://www.nsf.gov/awardsearch/showAward?AWD_ID=2411318)), this convention links execution metadata with physical output checks without claiming that the current harness executes those checks automatically.
+The convention below is a recommended shape for scientific projects that need to document expected dimensions, attributes, numerical tolerances, scheduler context, and verification commands for scientific artifacts. Developed at the [Gnosis Research Center (GRC)](https://grc.iit.edu) at Illinois Tech as part of the NSF-funded scientific-software context (NSF Award [#2411318](https://www.nsf.gov/awardsearch/showAward?AWD_ID=2411318)), this convention links execution metadata with physical output checks; the harness executes a check only through a matching `verifiers.yaml` entry.
 
 ---
 
 ## Validation Contract Convention
 
-A validation contract can be stored as YAML or Markdown. A custom or project-level agent (such as a local `scientific-validator` agent example under `.clio-coder/agents/`) or the developer can draft these files and commit them next to the research code. Clio core currently checks only for the documented filenames at the workspace root.
+A validation contract is a YAML file under the version-1 schema; `VALIDATION.md` is the Markdown companion for prose that the schema cannot hold. A custom or project-level agent (such as a local `scientific-validator` agent example under `.clio-coder/agents/`) or the developer can draft these files and commit them next to the research code. The loader rejects unknown fields at every level and names the field it rejected, so a typo is a diagnostic rather than a silently ignored key.
 
 ### Example netCDF / Slurm validation contract:
 ```yaml
@@ -69,12 +69,14 @@ checks:
     tags: [scientific, netcdf]
 ```
 
-### Suggested Fields:
-1. **`version`:** Set to `1` for project-local compatibility.
-2. **`runtime.kind`:** Document execution mode (`local`, `slurm`, `mpi`, or `other`).
-3. **`artifacts`:** List output files or directories the validation plan should inspect.
-4. **`preserve`:** Project convention for artifacts that should not be deleted by cleanup workflows. Clio's built-in protected-artifact guard is separate and is driven by live `protect_path` effects, not by this YAML field.
-5. **`validators`:** List shell commands or scripts a verifier should run to validate the generated files.
+### Schema (version 1):
+Every field except `version` is optional. Strings are capped at 4096 bytes (`notes` at 16 KiB), `artifacts` at 256 entries, `validators` at 128, `runtime.modules` at 64, and each map at 256 keys; a diagnostic cites the cap it crossed.
+1. **`version`:** Required, exactly `1`.
+2. **`task`:** One string describing the work the contract covers.
+3. **`runtime`:** `kind` is required and one of `local`, `slurm`, `mpi`, or `other`; `nodes` and `ranks` are positive integers, `walltime` is a string, and `modules` is a list of strings.
+4. **`artifacts`:** Each entry needs `path`; `format` is a string, `expected_dimensions` maps names to non-negative integers, `expected_attributes` maps names to strings, `numerical_tolerances` holds `relative`, `absolute` (finite non-negative numbers), and `ulp` (non-negative integer), and `preserve` is a boolean. `preserve` is a project convention for cleanup workflows; Clio's built-in protected-artifact guard is separate and is driven by live `protect_path` effects, not by this field.
+5. **`validators`:** A list of command strings a verifier should satisfy. They remain prose until the project declares matching `verifiers.yaml` entries.
+6. **`notes`:** Free text.
 
 ---
 
@@ -88,8 +90,7 @@ Comparing floating-point values in scientific computations must accommodate roun
 | **`absolute`** | $|val - ref| \le absolute$ | Additive difference check. Used when reference value is close to `0`. |
 | **`ulp`** | $StepsBetween(val, ref) \le ulp$ | Unit in the Last Place. Measures floating-point representation steps. |
 
-> [!NOTE]
-> Clio core does not currently execute tolerance comparisons and does not apply a default numerical tolerance. Put defaults directly in project validators or contract text.
+Tolerances become executable through a `kind: numeric-compare` entry in `.clio-coder/verifiers.yaml` (catalog version 2). The entry's `command` prints a JSON object of `string -> number | number[]` on stdout, `reference` names a repository-relative JSON file of the same shape, and `tolerance` names at least one of `relative`, `absolute`, or `ulp`. A value passes only when it satisfies every tolerance given; a key missing on either side fails with the key named, arrays compare elementwise and fail on length mismatch, and any `NaN` or infinity fails. The report lists each key's worst deviation and which tolerance it failed, and it is recorded on the `verify` result and on the host-verification check of a dispatch receipt. Clio applies no default tolerance: the catalog entry states it. `clio-coder verifiers author` proposes one such entry for every contract artifact that declares `numerical_tolerances`, with the command left for the operator to fill, so nothing runs until the operator confirms an exact argv. A `kind: perf-budget` entry judges the command's wall time the same way against a `budget` or a recorded baseline; see [Tool usage](../guide/tool-usage.md#project-verifier-catalog).
 
 ---
 
@@ -112,12 +113,12 @@ Scheduler-driven runs require distinct validation handling compared to local uni
 - **Queue status is not validation**: Checking if a Slurm command like `sbatch` exits successfully only proves that the Slurm scheduler accepted the job script. A good contract tells the verifier how to check actual simulation artifacts inside `out/` or `ckpt/` after job completion.
 - **Environment module loading**: The `runtime.modules` array can document the exact software stack dependencies (such as `intel/2024`, `openmpi/5.0`) that must be loaded before running the validators.
 - **HPC and Data Integration**: For large-scale allocations such as those at the Argonne Leadership Computing Facility (ALCF), projects can archive verification logs through their own storage or data-transfer workflow. Clio core does not manage Globus transfers.
-- **Validator execution**: In the current alpha version, contract validation is advisory. Quality/verification agents (such as the base `verifier` agent or custom project-level agents) read the contract to guide developers and write out verification receipts. Automated in-harness contract execution is not implemented yet.
+- **Validator execution**: A parsed contract's `artifacts` and `validators` are requirements the `verifier` agent and custom project-level agents must satisfy, and they are executable only through `verifiers.yaml` entries. Automated in-harness execution of the contract itself is not implemented.
 
 ### How a Validation Contract Raises Session Rigor
 
 Clio Coder integrates scientific validation contracts directly into its safety model to raise the evidence standard automatically:
-- **Automatic Escalation**: At startup, Clio scans the workspace root. The presence of any validation contract (e.g. `.clio-coder/validation.yaml`, `.clio-coder/validation.yml`, `validation.yaml`, `validation.yml`, or `VALIDATION.md`) automatically escalates the session's rigor level from `normal` to `high`.
-- **High-Rigor Gate Requirements**: Once the rigor is raised to `high`, the finish gate is active. It engages on a settled `turn_end` only when the recent window contains successful workspace mutation evidence and no validation evidence or explicit limitation. The window is entries since the last user message, capped at 80 entries:
+- **Parsed contract escalates**: At startup and at every finish-gate decision, `rigorResolution()` in `src/domains/safety/rigor.ts` loads the contract. A contract that parses raises the session's rigor level from `normal` to `high` with source `validation-contract`. An unparseable contract yields `normal` with source `invalid-contract` and the fault as the diagnostic; a Markdown-only workspace yields `normal` with source `markdown-advisory`. `CLIO_CODER_RIGOR` still overrides both directions.
+- **High-Rigor Gate Requirements**: Once the rigor is `high`, the finish gate is active. It engages on a settled `turn_end` only when the recent window contains successful workspace mutation evidence and no validation evidence or `limitation` receipt. The window is entries since the last user message, capped at 80 entries:
   - Clio issues a `request_continuation` middleware effect to keep the session running.
-  - Clio injects a dynamic warning reminder (`HIGH_RIGOR_REVALIDATION_MESSAGE`) instructing the agent to run a verification command or to declare a limitation before it can conclude the turn.
+  - Clio injects a dynamic warning reminder (`HIGH_RIGOR_REVALIDATION_MESSAGE`) instructing the agent to run a verification command or to call `limitation` before it can conclude the turn.

package/evals/behavioral-machinery-support.ts

@@ -133,6 +133,7 @@ export function dispatchStubContext(): DomainContext {
 		health: { status: "healthy", lastCheckAt: null, lastError: null, latencyMs: null },
 		capabilities: { ...runtime.defaultCapabilities },
 		discoveredModels: [],
+		discoveredModelsSource: "none",
 	}));
 	const fallbackStatus = statuses[0];
 	if (fallbackStatus === undefined) throw new Error("behavioral machinery requires one target");

package/evals/behavioral-machinery.yaml

@@ -12,7 +12,7 @@ suite:
 matrix:
   dimensions: []
   targets:
-    - id: local
+    - id: default
   repeats: 1
 tasks:
   - id: architect-positive

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@iowarp/clio-coder",
-	"version": "0.4.3",
+	"version": "0.4.4",
 	"description": "The terminal coding agent for people who maintain the code that science runs on, with user-chosen models and inspectable evidence.",
 	"keywords": [
 		"ai",

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:**

package/skills/planning/prd/SKILL.md

@@ -7,7 +7,7 @@ triggers:
   - define this feature
   - structure this product brain dump
   - create milestone prompts
-version: 0.4.0
+version: 0.4.1
 license: Apache-2.0
 allowed-tools:
   - read
@@ -50,8 +50,9 @@ the user saying so. Markdown only, no external templates, repo-aware.
   own prompt — let the user describe the idea raw — rather than an invented
   idea.
 
-There is no operator in a headless run: `ask_user` is either not registered
-or nothing answers it, and stalling a gate to wait for it never resolves.
+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, and
+stalling a gate to wait for it never resolves.
 When a gate goes unanswered, do not skip the phase and do not go quiet: run
 it as a monologue instead — state the phase's question, your
 recommendation (grounded in the repo and any evidence read, or the most

package/skills/planning/product-intent/SKILL.md

@@ -7,7 +7,7 @@ triggers:
   - problem-first PRD
   - define a falsifiable product hypothesis
   - greenfield product intent
-version: 0.4.0
+version: 0.4.1
 license: Apache-2.0
 allowed-tools:
   - read
@@ -50,10 +50,10 @@ decisions (library, data model, boundaries) never enter it; they belong to
 - Nothing is required beyond some text; a blank invocation gets Step 0's own
   "What do you want to build? A few sentences." question.
 
-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. Treat the
-first empty response exactly like the user saying "just write it" (see "If
+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. Treat the
+first refusal exactly like the user saying "just write it" (see "If
 the user declines the interview" below), and apply that treatment from
 wherever it happened onward — Step 0's evidence check included, not just
 the five clusters: state the question, your best evidence-grounded answer
@@ -89,8 +89,8 @@ the same turn. Thin answers get reflected back and dug into.
 If the user declines the interview ("just write it"): honor it, name what
 you will have to leave TBD, ask only the two or three highest-leverage
 questions, and mark everything else "TBD — needs validation". This is also
-the headless default: see Arguments above for what an empty `ask_user`
-response means and how to apply this same treatment cluster by cluster
+the headless default: see Arguments above for what a refused `ask_user`
+call means and how to apply this same treatment cluster by cluster
 instead of stopping after the first one.
 
 1. **Initiate.** Input given → restate and confirm. Blank → "What do you
@@ -159,7 +159,7 @@ outcome-shaped metrics · explicit non-goals · zero engineering decisions.
   counter-signal.
 - The literal filename `PRD.md`, or anything outside `docs/`, instead of
   `docs/<kebab-slug>.prd.md`.
-- Calling `ask_user` again after an empty response, instead of switching to
+- Calling `ask_user` again after a refusal, instead of switching to
   the decline treatment for every step from there on.
 - Opening a task list for the interview clusters; `tasks` is refused.
 - Reaching Generate without ever attempting Step 0 or the first cluster —

package/skills/planning/tech-spec/SKILL.md

@@ -7,7 +7,7 @@ triggers:
   - code-shaped contracts
   - implementation-ready technical specification
   - specify execution flows
-version: 0.3.0
+version: 0.3.1
 license: Apache-2.0
 disable-model-invocation: true
 allowed-tools:
@@ -63,9 +63,9 @@ and save a file only when the user asks; otherwise return the spec inline.
   installed to reference in the TDD Test Plan section; both are frontmatter
   facts, not something to explain to the user unless asked.
 
-There is no operator in a headless run: `ask_user` either isn't registered
-or nothing answers it, and a call that goes unanswered will not resolve
-differently on a second try. In Path B (below), that means: state the
+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, and a
+second try will not resolve differently. In Path B (below), that means: state the
 question, your recommendation grounded in the codebase and any docs read
 (or the most defensible engineering default when nothing grounds it), and
 the reasoning; adopt the recommendation; mark it `assumed — confirm`; move