web: the playbooks say what is true in a tab

Each SKILL.md in the browser build gets one preamble: the shell is a simulated bash with no git, npm,
node, python or test runner and cannot run the code, so the steps that say to run them are skipped,
no result is claimed for them, and the summary says which checks were not run. The steps and the menu
entries are unchanged; the desktop's files are untouched.

Also: the verify.command example means what it says (`! grep -rn TODO src`).

Author: ndemianc

web/ai-extension/build.mjs

@@ -38,6 +38,7 @@ if (!nodePaths.some((p) => fs.existsSync(path.join(p, 'buffer')))) { console.err
 
 const { applyCopy } = createRequire(import.meta.url)('./copy.js');
 const { skinChat } = createRequire(import.meta.url)('./skin.js');
+const { browserSkill } = createRequire(import.meta.url)('./skills.js');
 
 const outDir = path.join(outRoot, 'levelcode-ai');
 fs.rmSync(outDir, { recursive: true, force: true });
@@ -56,6 +57,8 @@ function collect(rel, filter) {
 			let text = TEXT.has(path.extname(r)) ? applyCopy(r, buf.toString('utf8')) : null;
 			// The browser's look for the chat goes into this embedded copy and nowhere else (skin.js).
 			if (text !== null && r === 'media/chat.html') { text = skinChat(text); }
+			// The playbooks assume git and a test runner; the browser's shell has neither (skills.js).
+			if (text !== null) { text = browserSkill(r, text); }
 			out[r] = text !== null ? text : { base64: buf.toString('base64') };
 		}
 	};

web/ai-extension/manifest.js

@@ -65,7 +65,7 @@ const DESCRIPTION_OVERRIDES = {
 		description: 'Backstop timeout in milliseconds before a command in LevelCode Shell is stopped. The Stop button on the command\'s card is the primary control; set 0 to disable the backstop.',
 	},
 	'levelcode.ai.verify.command': {
-		markdownDescription: 'Optional one-shot command run in **LevelCode Shell** to verify the agent\'s edits (e.g. `grep -rn TODO src && exit 1`, or `sh check.sh` for a script of your own). It must exit on its own. Leave empty to verify with editor diagnostics only.',
+		markdownDescription: 'Optional one-shot command run in **LevelCode Shell** to verify the agent\'s edits (e.g. `! grep -rn TODO src`, which fails while any TODO is left, or `sh check.sh` for a script of your own). It must exit on its own. Leave empty to verify with editor diagnostics only.',
 	},
 	'levelcode.ai.agent.autopilot': {
 		description: 'Autopilot: let the agent run commands without asking, and prefer verifying its own work over pausing to ask you. It still stops and asks before deleting files. File edits stay reviewable with Keep/Undo either way. Off by default.',

web/ai-extension/skills.js

@@ -0,0 +1,36 @@
+// The playbooks (extensions/levelcode-ai/skills/*/SKILL.md) as the browser build ships them.
+//
+// They were written for a machine with git, a test runner and a build: "run git diff", "npm test", "the suite is
+// green". In a tab the shell is a simulated bash over the workspace's files, and a model that follows those steps
+// literally either burns turns on commands that answer "not found" or — worse — ends with "all tests passing" for
+// tests that never ran. One preamble at the top of each body says what is true here; the steps stay as written and
+// the desktop's files are untouched (this is applied to the embedded copy, like copy.js and skin.js).
+//
+// Plain CommonJS; web/test/unit/skills.test.js pins it.
+'use strict';
+
+const PREAMBLE = [
+	'> **BROWSER EDITION.** The shell here is a simulated bash over the workspace files: no git, npm, node, python, pytest or any test runner,',
+	'> and it cannot run your code. Where the steps below say to run git, tests, a linter, a build or a script: skip that step, do not try it, and do not',
+	'> claim a result for it. Use read_file, search and the editor\'s diagnostics instead, and end your summary by saying which checks were not run and the',
+	'> exact command the user can run on their own computer. Never write "passing", "green" or "builds" unless a command you ran in this shell, or the',
+	'> editor\'s diagnostics, actually showed it.',
+	'',
+].join('\n');
+
+const FRONT = /^---\r?\n[\s\S]*?\r?\n---\r?\n/;
+
+/**
+ * @param {string} rel path relative to extensions/levelcode-ai, forward slashes
+ * @param {string} text
+ * @returns {string}
+ */
+function browserSkill(rel, text) {
+	if (!/^skills\/[^/]+\/SKILL\.md$/.test(rel)) { return text; }
+	const m = FRONT.exec(text);
+	// The front matter (name, description) is the skill's menu entry and must stay the first thing in the file.
+	if (!m) { return PREAMBLE + '\n' + text; }
+	return text.slice(0, m[0].length) + '\n' + PREAMBLE + text.slice(m[0].length);
+}
+
+module.exports = { browserSkill, PREAMBLE };

web/test/unit/skills.test.js

@@ -0,0 +1,54 @@
+/*---------------------------------------------------------------------------------------------
+ *  The playbooks in the browser build — run: node web/test/unit/skills.test.js
+ *
+ *  Each SKILL.md gets one preamble that says what is true in a tab; the desktop's files are never edited.
+ *--------------------------------------------------------------------------------------------*/
+// @ts-check
+'use strict';
+
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+const { browserSkill, PREAMBLE } = require('../../ai-extension/skills.js');
+
+const SKILLS = path.join(__dirname, '..', '..', '..', 'extensions', 'levelcode-ai', 'skills');
+let n = 0;
+function test(name, fn) { fn(); n++; console.log('  ok - ' + name); }
+
+const names = fs.readdirSync(SKILLS).filter((d) => fs.existsSync(path.join(SKILLS, d, 'SKILL.md')));
+
+test('there are skills to treat, and each keeps its front matter as the first lines (that is the menu entry)', () => {
+	assert.ok(names.length >= 3);
+	for (const name of names) {
+		const src = fs.readFileSync(path.join(SKILLS, name, 'SKILL.md'), 'utf8');
+		const out = browserSkill('skills/' + name + '/SKILL.md', src);
+		const front = /^---\r?\n[\s\S]*?\r?\n---\r?\n/.exec(src)[0];
+		assert.ok(out.startsWith(front), name + ': the front matter moved');
+		assert.ok(out.includes(PREAMBLE), name + ': no preamble');
+		assert.strictEqual(out.split(PREAMBLE).length - 1, 1, name + ': more than one preamble');
+		assert.ok(out.endsWith(src.slice(front.length)), name + ': the steps changed');
+	}
+});
+
+test('the preamble forbids claiming a result that never ran, and names what is missing', () => {
+	const flat = PREAMBLE.replace(/\n> /g, ' ');
+	for (const word of ['git', 'npm', 'node', 'python', 'test runner', 'do not claim a result', 'Never write "passing"']) {
+		assert.ok(flat.includes(word), 'the preamble does not say: ' + word);
+	}
+	assert.ok(!/hackable/i.test(PREAMBLE));
+});
+
+test('only SKILL.md bodies are touched; a text without front matter gets the preamble on top', () => {
+	assert.strictEqual(browserSkill('media/chat.html', 'x'), 'x');
+	assert.strictEqual(browserSkill('skills/a/README.md', 'x'), 'x');
+	assert.ok(browserSkill('skills/a/SKILL.md', 'no front matter').startsWith(PREAMBLE));
+});
+
+test('the desktop sources are not modified by it', () => {
+	for (const name of names) {
+		const src = fs.readFileSync(path.join(SKILLS, name, 'SKILL.md'), 'utf8');
+		assert.ok(!src.includes('BROWSER EDITION'), name);
+	}
+});
+
+console.log(`\n${n} tests passed`);