verikun 0.26.2 → 0.26.3

package/.claude/skills/verikun/SKILL.md

@@ -386,7 +386,8 @@ vk ai onboarding.md --timeout 5m        # tighten the run timeout (default 15m)
   including file; a fragment may include another. Name a fragment `_something.md` — `vk suite`
   skips `_`-prefixed files, so a fragment never runs as a test of its own. Each chunk compiles
   and caches separately, so editing a shared fragment recompiles the fragment, not every test
-  that uses it.
+  that uses it. A title or a description states no step, so it is folded into the chunk of its
+  own file that does, rather than compiled as a test of its own — put it wherever reads best.
 - The plan expresses **conditions** (`if-present`, for optional interstitials like a
   permission dialog) and **bounded loops** (`repeat … until`, e.g. scroll-until) —
   control flow `vk batch` cannot, so a flaky popup or a scroll-to-find no longer breaks

package/CHANGELOG.md

@@ -6,6 +6,16 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [0.26.3] - 2026-09-11
+
+A `vk ai` test's description is no longer compiled into steps of its own.
+
+### Fixed
+- **`vk ai`** no longer compiles a title or description above an `@include` as a test of its
+  own, inventing steps that then ran first. ([#133])
+
+[#133]: https://github.com/ddikman/verikun/issues/133
+
 ## [0.26.2] - 2026-09-10
 
 Android hierarchy reads no longer mistake a sheet's or dialog's barrier for an empty screen.

package/dist/agent/include.js

@@ -9,25 +9,30 @@
 // because the preamble is conditional ("dismiss whichever of these six screens is present"),
 // which is exactly the part only `vk ai` can express.
 //
-// Two properties make the mechanism honest:
+// Three properties make the mechanism honest:
 //
 //  - **The resolved text is the cache key.** Callers hash `nl` (fragments already inlined),
 //    so editing a fragment invalidates every test that includes it. Keying on the top-level
 //    file would silently replay stale plans for all of them.
 //  - **A fragment is not a test.** `vk suite` skips `_`-prefixed files and never recurses
 //    into subdirectories, so a fragment gets no report row and no `--app` data reset.
+//  - **A chunk is a whole prompt, so a chunk that is not a test must not become one.** Prose
+//    that only describes the test is folded into the chunk of its own file that states the
+//    steps it describes, never compiled alone (groupDescriptions, issue #133).
 //
-// `segments` is what makes the compile CHEAP as well as short: each contiguous chunk of
-// prose is compiled on its own and cached under its own key, so a preamble shared by nine
-// tests is compiled ONCE (see compileFromSegments in cli.ts). Splicing happens at the plan
-// level, which the shallow IR allows — a plan is a flat list of steps.
+// `segments` is what makes the compile CHEAP as well as short: each chunk of prose is
+// compiled on its own and cached under its own key, so a preamble shared by nine tests is
+// compiled ONCE (see compileFromSegments in cli.ts). Splicing happens at the plan level,
+// which the shallow IR allows — a plan is a flat list of steps.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.hasInstruction = hasInstruction;
+exports.statesInstruction = statesInstruction;
 exports.resolveIncludes = resolveIncludes;
 exports.segmentLabel = segmentLabel;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const errors_1 = require("../errors");
+const lint_1 = require("./lint");
 /** An include directive: `@include <path>` alone on a line (leading space allowed).
  *  Deliberately a whole-line form — a path is everything after the keyword, so it needs
  *  no quoting and can contain spaces. */
@@ -47,6 +52,47 @@ function hasInstruction(text) {
     const bare = text.replace(/<!--[\s\S]*?-->/g, '');
     return bare.split('\n').some((line) => line.trim() !== '' && !DECORATION_RE.test(line));
 }
+/** A list item of ANY kind — ordered or bulleted. `lint.ts` counts only ORDERED items, because
+ *  there an unordered bullet carrying explanation would inflate the expected plan size and
+ *  manufacture a rejection. Here the polarity is reversed: a bulleted preamble
+ *  ("- Launch the app with its data cleared.") is a list of steps, and missing it is what would
+ *  do damage. */
+const LIST_ITEM_RE = /^\s*(?:\d+[.)]|[-*+])\s+/;
+/**
+ * Does this chunk STATE a step, or only DESCRIBE the test?
+ *
+ * Deliberately NOT `lint.ts`'s `instructionUnits(text) > 0`, even though that counter answers a
+ * neighbouring question. It is documented as biased to UNDERCOUNT, which is safe where it is
+ * used ("an undercount only weakens detection, while an overcount would reject a correct plan")
+ * and exactly backwards here, where an undercount means calling a real step a description.
+ * Measured, all scoring zero units: a bulleted preamble, "First, launch the app.", and this
+ * repo's own `_launch-to-home.md` reworded to open with its subject instead of its verb.
+ *
+ * So this asks for POSITIVE EVIDENCE and errs the other way — a list item of any kind, or one
+ * of the same verbs `lint.ts` knows appearing ANYWHERE in a line rather than only at its start.
+ * Every misreading it can still make is the safe one: a description that happens to contain
+ * "check" or "wait" reads as a step and is compiled alone, which is what happened before this
+ * existed. Nothing regresses; some things stop being fabricated.
+ *
+ * Exported solely so the unit suite can reach it.
+ */
+function statesInstruction(text) {
+    let fenced = false;
+    for (const line of text.replace(/<!--[\s\S]*?-->/g, '').split('\n')) {
+        if (FENCE_RE.test(line)) {
+            fenced = !fenced;
+            continue;
+        }
+        if (fenced)
+            continue;
+        if (LIST_ITEM_RE.test(line))
+            return true;
+        for (const word of line.toLowerCase().match(/[a-z]+/g) ?? [])
+            if (lint_1.IMPERATIVES.has(word))
+                return true;
+    }
+    return false;
+}
 const endWithNewline = (s) => (s.endsWith('\n') ? s : `${s}\n`);
 const readFile = (path) => (0, node_fs_1.readFileSync)(path, 'utf8');
 /**
@@ -58,17 +104,21 @@ const readFile = (path) => (0, node_fs_1.readFileSync)(path, 'utf8');
  * otherwise expand until it ran out of memory.
  */
 function resolveIncludes(file, read = readFile) {
-    const segments = [];
-    const nl = expand((0, node_path_1.resolve)(process.cwd(), file), [], segments, read, null);
-    return { nl, segments };
+    const ex = { out: [], read, units: 0 };
+    // `nl` is assembled from `parts`, independently of `ex.out`, so regrouping the chunks below
+    // cannot change the resolved text — and therefore cannot change the whole-test cache key, nor
+    // what the assembled-plan lint is asked about.
+    const nl = expand((0, node_path_1.resolve)(process.cwd(), file), [], ex, null);
+    return { nl, segments: groupDescriptions(ex.out) };
 }
-function expand(path, stack, out, read, from) {
+function expand(path, stack, ex, from) {
+    const unit = ex.units++;
     if (stack.includes(path)) {
         throw new errors_1.CliError(`ai: include cycle — ${[...stack, path].map((p) => shortName(p)).join(' → ')}`, 2);
     }
     let text;
     try {
-        text = read(path);
+        text = ex.read(path);
     }
     catch (e) {
         const where = from ? ` (included from ${from})` : '';
@@ -91,8 +141,9 @@ function expand(path, stack, out, read, from) {
         // The label points at the chunk's first real line, not at the blank line that
         // separated it from the include above it.
         const lead = buf.findIndex((l) => l.trim() !== '');
-        if (lead >= 0)
-            out.push({ text: chunk, source: path, startLine: bufStart + lead, compilable: hasInstruction(chunk) });
+        if (lead >= 0) {
+            ex.out.push({ text: chunk, source: path, startLine: bufStart + lead, compilable: hasInstruction(chunk), unit });
+        }
         buf = [];
     };
     lines.forEach((line, i) => {
@@ -106,11 +157,87 @@ function expand(path, stack, out, read, from) {
             return;
         }
         flush();
-        parts.push(endWithNewline(expand((0, node_path_1.resolve)((0, node_path_1.dirname)(path), m[1]), [...stack, path], out, read, `${shortName(path)}:${i + 1}`)));
+        parts.push(endWithNewline(expand((0, node_path_1.resolve)((0, node_path_1.dirname)(path), m[1]), [...stack, path], ex, `${shortName(path)}:${i + 1}`)));
     });
     flush();
     return parts.join('');
 }
+/**
+ * The chunk a description folds into: the next chunk of its OWN expansion that states a step,
+ * else the previous one. `-1` when that expansion states no step anywhere.
+ *
+ * Scanning by EXPANSION rather than by path is what keeps a fragment included twice identical in
+ * both places. Scanning by FILE rather than simply "the next chunk" is the load-bearing half:
+ * the next chunk is normally the fragment the `@include` pulled in, and folding a per-test
+ * description into it would change the FRAGMENT's cache key per test, destroying the
+ * compiled-once property `@include` exists for. Another expansion's chunks are skipped OVER, not
+ * stopped at — reaching across the include to the file's own next chunk is the entire point.
+ */
+function hostFor(raw, describes, i) {
+    const usable = (j) => raw[j].unit === raw[i].unit && raw[j].compilable && !describes[j];
+    for (let j = i + 1; j < raw.length; j++)
+        if (usable(j))
+            return j;
+    for (let j = i - 1; j >= 0; j--)
+        if (usable(j))
+            return j;
+    return -1;
+}
+const plain = ({ text, source, startLine, compilable }) => ({ text, source, startLine, compilable });
+/**
+ * Fold a chunk that only DESCRIBES the test into the chunk of the same file that states the
+ * steps it describes (issue #133).
+ *
+ * A title and a summary paragraph written above the first `@include` used to become a chunk of
+ * its own — and a chunk is a whole prompt. Compiled alone, the summary IS the test, so the model
+ * invents a plan for it and those steps are spliced AHEAD of the launch the include was there to
+ * perform; the reported case was 34 fabricated steps whose first act was to tap a login button on
+ * the Android launcher. `SECTION_NOTE` has told the model since `@include` shipped that a summary
+ * is not an instruction, and it still went the wrong way on 5 of 14 tests in one run: whether
+ * prose reads as a spec is a model judgement, so the fix has to be deterministic.
+ *
+ * A STRICT IMPROVEMENT, deliberately: every chunk either folds into a neighbour or is left
+ * exactly as it was. There is no third disposition, and in particular nothing is DROPPED — prose
+ * this pass discarded would be prose the model never sees, and a fragment wrongly discarded is a
+ * suite that silently stops launching its app. No coverage rule could catch that: the floor and
+ * the tail anchors both measure `nl`, which this pass does not touch.
+ */
+function groupDescriptions(raw) {
+    const describes = raw.map((s) => s.compilable && !statesInstruction(s.text));
+    const host = raw.map((_, i) => (describes[i] ? hostFor(raw, describes, i) : -1));
+    // The overwhelmingly common case — no description, or one with nowhere to go — allocates
+    // nothing and is byte-identical to the behaviour before this pass existed.
+    if (host.every((h) => h < 0))
+        return raw.map(plain);
+    const out = [];
+    const slot = new Map(); // index in `raw` -> index in `out`
+    raw.forEach((s, i) => {
+        if (host[i] >= 0)
+            return; // folded into its host below
+        slot.set(i, out.length);
+        out.push(plain(s));
+    });
+    // Prepends run BACKWARDS and appends run FORWARDS. Not a style choice: each fold lands at the
+    // host's edge, so whichever is written LAST ends up nearest the host. A file with two
+    // descriptions separated by two includes has to come out in the order its author wrote them,
+    // and a single pass in either direction reverses one of those two chains.
+    for (let i = raw.length - 1; i >= 0; i--) {
+        if (host[i] <= i)
+            continue;
+        const at = slot.get(host[i]);
+        // The earlier line, so `segmentLabel` names where the folded text now begins. That label is
+        // the accounting for the fold: a chunk that printed as `t.md:8` prints as `t.md:1`, and the
+        // "assembled from N chunk(s)" line drops by one. No prose moves unannounced.
+        out[at] = { ...out[at], text: raw[i].text + out[at].text, startLine: Math.min(out[at].startLine, raw[i].startLine) };
+    }
+    for (let i = 0; i < raw.length; i++) {
+        if (host[i] < 0 || host[i] > i)
+            continue;
+        const at = slot.get(host[i]);
+        out[at] = { ...out[at], text: out[at].text + raw[i].text };
+    }
+    return out;
+}
 /** A path as a human reads it: relative to the cwd when it is below it. */
 function shortName(path) {
     const cwd = `${process.cwd()}/`;

package/dist/agent/lint.js

@@ -28,6 +28,7 @@
 // rule requires a fairly unambiguous phrase and checks for a specific structural counterpart.
 // It never edits the plan; the model gets the feedback and stays the author.
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.IMPERATIVES = void 0;
 exports.coverageChecksEnabled = coverageChecksEnabled;
 exports.instructionLines = instructionLines;
 exports.instructionUnits = instructionUnits;
@@ -87,8 +88,15 @@ const FENCE_RE = /^\s*(```|~~~)/;
  * Verbs that open an instruction. A CLOSED set, and a tight one — every entry here raises
  * the expected plan size, so a loose entry costs a false rejection while a missing one only
  * costs detection. The floor below is generous enough to absorb the resulting undercount.
+ *
+ * Exported for ONE other consumer, `agent/include.ts`, which asks a different question of the
+ * same vocabulary: not "how many steps does this prose state" but "does it state one at all".
+ * Shared rather than copied for the reason `pidAlive` is shared with `agent/plan-lock.ts` — a
+ * second list of verbs drifts from this one invisibly. Note that it is NOT part of
+ * `COMPILER_FINGERPRINT`, so an edit here moves a chunk boundary as well as a lint threshold;
+ * the version bump such an edit already requires is what rotates the fingerprint.
  */
-const IMPERATIVES = new Set([
+exports.IMPERATIVES = new Set([
     'tap', 'press', 'click', 'type', 'enter', 'fill',
     'launch', 'open', 'start', 'restart', 'relaunch', 'stop', 'close',
     'confirm', 'verify', 'assert', 'check', 'ensure',
@@ -121,7 +129,7 @@ function instructionLines(nl) {
         const body = (ordered ? raw.replace(ORDERED_ITEM_RE, '') : raw).trim();
         if (!body)
             continue;
-        if (ordered || IMPERATIVES.has((/^([A-Za-z]+)/.exec(body)?.[1] ?? '').toLowerCase()))
+        if (ordered || exports.IMPERATIVES.has((/^([A-Za-z]+)/.exec(body)?.[1] ?? '').toLowerCase()))
             out.push(body);
     }
     return out;

package/dist/version.js

@@ -3,4 +3,4 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
 // GENERATED by scripts/gen-version.mjs from package.json's "version" at build time
 // (the `prebuild` script). Do NOT edit by hand; bump package.json instead.
-exports.VERSION = '0.26.2';
+exports.VERSION = '0.26.3';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "verikun",
-  "version": "0.26.2",
+  "version": "0.26.3",
   "description": "Drive Android emulators/devices and iOS simulators for AI agents: tap, type, swipe, screenshot, and inspect the UI hierarchy by semantic identifiers — like Puppeteer for native apps.",
   "keywords": [
     "android",