docs, skill: an unresolved variable warns and the run goes ahead (kane-cli 0.8.15+)

[shravan-lambdatest]

Problem

The skill and the user guide describe the pre-run variable check as a refusal: an unresolved {{name}} stops the run with exit 2 and one error event, and a testrun member that references one fails preflight. Since kane-cli 0.8.15 the check warns and the run goes ahead: one warning event with code: "unresolved_variables", exit codes unchanged, the plan stays valid, and the name is typed into the page as written unless a step sets it first. An agent following the documented contract either stops for a refusal that never comes, or dispatches a run that types the placeholder literally.

Change

The variable check, described as it behaves

• Every passage that described the refusal now states the warn contract in one sentence: a name with no value is a warning; the run goes ahead and types the name as written, unless a step sets it first. Gated at kane-cli 0.8.15+.
• The warning event is documented in the events tables (SKILL.md, references/parsing.md) with its schema: code, message, suggested_file, and variables[] rows with name, reason (value_missing, not_declared, not_a_dataset_column), file, used_by[]. It arrives before the first progress frame on run and testmd run, and right after testrun_plan on testrun run.
• testrun_plan members carry unresolved[] and the plan stays valid; a suite preflight checks every step of a member, replayed ones included, while run and testmd run skip replayed steps. The unresolved_variables preflight failure is gone from references/testrun.md and the user guide, and the parsing loop handles the warning.
• The never-checked list gains an explicit {{global.*}} reference, which resolves from Test Manager at run time.
• references/cards.md: missing variable values are no longer an exit-2 cause; a run whose output carried the warning gets a Variables row on its card.
• User guide: variables-and-context, running-tests, testrun (the dry run prints the warning too), testmd/running, cicd (how to fail a CI step on the warning line), troubleshooting, assurance/design.
• The three skill copies (skill-installer/skills, .claude/skills/kane-cli, .agents/skills/kane-cli) stay byte-identical.

What an agent does about it

• SKILL.md §3 gains one recipe, Fill the variables before any run: collect the names with no value (the warning, a dry-run plan's unresolved[] rows, a design run's variables_declared and variables_summary rows); write the values you already have, from the user or the requirement document, into the file and say so; ask once for the rest using each variable's description, plain values here or in the file, secret-looking ones in the file only; then a fresh dry run of the exact selection with no warning is the check, and a member whose rows are all filled may run while the others wait. A row with secret: true or a credential in its description is a secret as much as a secret-looking name; no placeholder is filled to silence the check. The assurance references point at it, and the design page says how an agent fills and asks.
• variables_declared is documented as arriving just before the tests phase's commit event, and variables_summary only after session_complete on a clean completion, listing every name the run declared.

testrun run from an agent

• Every testrun run line an agent writes ends in < /dev/null (bash and zsh; < NUL in cmd.exe; through cmd from PowerShell). On 0.8.17+ the first stdout line is stream_start; a prose plan there means terminal mode, which shows the human view and, after a real run, waits on an evidence table until q or Esc. An empty stdout with a stderr message is a usage error. All examples carry the redirect.
• A directory is not a positional path (testrun run takes _test.md files); every tests/app/-style example now selects with --match '^tests/app/'.

Test cases always come from the assurance commands

• The skill no longer routes to kane-cli generate: the routing lines, the section and its two reference files are gone. A description given in chat is written to requirements/<feature>.md, ingested and designed from (new §6). The user guide's generate pages are unchanged.

Tests

Fresh subagents, each with the skill installed and a shim in front of kane-cli that logs and blocks every paid or irreversible call, before and after the skill changes:

Scenario	Before	After
Run designed tests whose variables are empty, owner waiting	3/3 filled the documented values, kept the password out of chat, never dispatched a member with unresolved rows	2/2 same, quoting the new rule
Write the command a Codex-in-VS-Code teammate pastes	6/6 had < /dev/null; 1/6 named the stream_start check	2/2 both
Test cases from a description given in chat	2/2 called kane-cli generate	3/3 wrote the requirements file and ran context ingest

Verification

• kane-cli testrun run .testmuai/tests/login_test.md --dry-run < /dev/null on kane-cli 0.8.18-beta.1, with one empty stub (demo_pass) and one undeclared name (start_url): stdout is stream_start, testrun_plan with valid: true and both names under the member's unresolved[], then one warning with code: "unresolved_variables", suggested_file and both variables[] rows; exit 0; stderr empty. This matches the documented shape field for field.
• diff -rq between the three skill copies is empty.
• Every statement about when the check runs and what it skips was checked against kane-cli 0.8.18 behaviour before editing.

🤖 Generated with Claude Code