@lemoncode/lemony 0.4.0 → 0.4.1

package/catalog/VERSION

@@ -1 +1 @@
-0.4.0
+0.4.1

package/catalog/agents/spec-author.md

@@ -44,7 +44,9 @@ the task branch before invoking you, so you are handed a real `<id>` from the st
      acceptance criteria. Always include the unwanted-behavior (`If … then …`) paths.
    - `design.md` — files, functions/interfaces, approach, edge cases, testing.
    - `tasks.md` — atomic, ordered checkboxes (vertical slices for TDD), each
-     referencing the requirements it satisfies, grouped under **risk-sized step
+     referencing the requirements it satisfies as a comma-separated `(R<n>, R<m>)`
+     list that ends a line (rule stated in `prd-to-spec`; a validator reads it),
+     grouped under **risk-sized step
      headers** (grouping criterion in `prd-to-spec`) — in step-by-step mode the
      loop runs one implement→review→checkpoint cycle per group, and the human
      approves the grouping with the rest of the spec.

package/catalog/skills/prd-to-spec/SKILL.md

@@ -193,8 +193,28 @@ of the spec. Grouping criterion:
 ## Group 2 — <name> _(<one-line boundary rationale>)_ [risk: data-loss]
 
 - [ ] T3 — <error path> (R2, R3)
+- [ ] **T4 — <a task that needs detail>.**
+      <detail prose, as many indented lines as it needs, with the ref list
+      ending the last one> (R3, R4)
 ```
 
+**Ref list — one rule, read by a script.** A task's requirement refs are one
+comma-separated `(R<n>, R<m>)` group that **ends a line**: the end of the task's first
+line, or the end of one continuation line (a line of its own, or the end of a detail
+line). Nothing after the closing paren on that line, not even a period. No ranges —
+`(R1–R4)` is not a list, write `(R1, R2, R3, R4)` — and no prose inside the parens.
+
+**Mentions.** A `(R<n>` on the task's first line, or right after the title's bold
+close, is always read as the declaration: it is reported if it does not end the line,
+even when a list ends a later line. Keep every other `(R<n>)` mention in detail prose
+**mid-line**. When two lists end continuation lines the validator cannot tell which is
+the declaration and reports the task; on a task that declares no list, the one
+line-ending mention is read as its declaration, and a mid-line one is reported.
+
+The review evidence ledger's validator enumerates each group's review slice from these
+refs; a task it cannot read is reported as `malformed-task-refs` — a spec defect that
+pauses the loop, never read as "declares none".
+
 Rules: order so the first task is a tracer bullet; never "write all tests" then
 "write all code"; keep each task small enough to verify on its own. Grouping never
 changes task granularity — checkboxes stay atomic and TDD runs per task; only review

package/dist/cli.mjs

@@ -5,7 +5,7 @@ import { basename, delimiter, dirname, extname, join, relative, resolve, sep } f
 import { argv, cwd, env, exit, stderr, stdin, stdout } from "node:process";
 import { createInterface } from "node:readline/promises";
 import { promisify } from "node:util";
-import { isMap, parse, parseDocument } from "yaml";
+import { parse, parseDocument } from "yaml";
 import { z } from "zod";
 import { createHash, randomBytes } from "node:crypto";
 import { constants } from "node:fs";
@@ -230,8 +230,6 @@ const setConfigValues = (rawYaml, updates) => {
 	}
 	for (const key of DEPRECATED_CONFIG_KEYS) if (doc.has(key)) doc.delete(key);
 	for (const key of DEPRECATED_PATHS_KEYS) if (doc.hasIn(["paths", key])) doc.deleteIn(["paths", key]);
-	const pathsNode = doc.get("paths", true);
-	if (isMap(pathsNode) && pathsNode.items.length === 0) doc.delete("paths");
 	for (const key of DEPRECATED_IMPLEMENTATION_KEYS) if (doc.hasIn(["implementation", key])) doc.deleteIn(["implementation", key]);
 	return doc.toString();
 };
@@ -2105,8 +2103,9 @@ const RISK_MARKER_ALL = /\[risk:/gi;
 const RISK_MARKER_LOOKALIKE = /\[\s*risks?\s*:/i;
 const TASK_LINE = /^\s*[-*+]\s*\[[ xX]\]\s*(?:\*\*|__|`)?\s*(T\d+)\b/;
 const TASK_REFS = /^\(((?:R\d+)(?:\s*,\s*R\d+)*)\)/;
-const TASK_REFS_LOOKALIKE = /\(\s*R\d+/;
-const TASK_REFS_AFTER_TITLE = /(?:\*\*|__)\s*(\(\s*R\d+)/;
+const TASK_REFS_LOOKALIKE_ALL = /\(\s*R\d+/g;
+const TASK_TITLE_WRAPPER = /^\s*[-*+]\s*\[[ xX]\]\s*(\*\*|__)/;
+const TASK_REFS_AFTER_TITLE_CLOSE = /^\s*(\(\s*R\d+)/;
 const REQUIREMENT_LINE = /^\s*-\s*\*\*(R\d+)\*\*/;
 const TEST_FILE = /(^|\/)__tests__\/|\.(spec|test)\.[cm]?[jt]sx?$/;
 //#endregion
@@ -2209,7 +2208,7 @@ const parseTaskBlock = (id, parts) => {
 			id,
 			requirementRefs: [...new Set(requirementRefs)]
 		},
-		malformedRefs: refs === null && TASK_REFS_LOOKALIKE.test(block)
+		malformedRefs: refs === null && hasRefLookalike(parts)
 	};
 };
 const declarationAt = (parts, block, opener) => {
@@ -2230,17 +2229,40 @@ const declarationClosesLine = (parts, end) => {
 	return /^(?:\*\*|__)/.test(tail) && lineEnds.has(end + 2);
 };
 const refsOpener = (parts, block) => {
-	const candidates = [];
-	const onFirstLine = TASK_REFS_LOOKALIKE.exec(parts[0] ?? "")?.index;
-	if (onFirstLine !== void 0) candidates.push(onFirstLine);
-	const afterTitle = TASK_REFS_AFTER_TITLE.exec(block);
-	if (afterTitle) candidates.push(afterTitle.index + afterTitle[0].lastIndexOf("("));
-	let offset = (parts[0] ?? "").length + 1;
+	const first = parts[0] ?? "";
+	const attempted = [];
+	for (const lookalike of first.matchAll(TASK_REFS_LOOKALIKE_ALL)) {
+		if (isLinkTarget(first, lookalike.index)) continue;
+		attempted.push(lookalike.index);
+		break;
+	}
+	const afterTitle = afterTitleClose(first, block);
+	if (afterTitle !== void 0) attempted.push(afterTitle);
+	if (attempted.length > 0) return Math.min(...attempted);
+	const closing = [];
+	let offset = first.length + 1;
 	for (const part of parts.slice(1)) {
-		if (/^\(\s*R\d+/.test(part)) candidates.push(offset);
+		for (const lookalike of part.matchAll(TASK_REFS_LOOKALIKE_ALL)) {
+			if (isLinkTarget(part, lookalike.index)) continue;
+			const at = offset + lookalike.index;
+			if (declarationAt(parts, block, at) !== null) closing.push(at);
+		}
 		offset += part.length + 1;
 	}
-	return candidates.length === 0 ? void 0 : Math.min(...candidates);
+	return closing.length === 1 ? closing[0] : void 0;
+};
+const hasRefLookalike = (parts) => parts.some((part) => [...part.matchAll(TASK_REFS_LOOKALIKE_ALL)].some((lookalike) => !isLinkTarget(part, lookalike.index)));
+const isLinkTarget = (line, index) => line[index - 1] === "]";
+const afterTitleClose = (first, block) => {
+	const wrapper = TASK_TITLE_WRAPPER.exec(first);
+	const marker = wrapper?.[1];
+	if (!wrapper || marker === void 0) return void 0;
+	const close = block.indexOf(marker, wrapper[0].length);
+	if (close < 0) return void 0;
+	const tail = block.slice(close + marker.length);
+	const opener = TASK_REFS_AFTER_TITLE_CLOSE.exec(tail);
+	if (!opener) return void 0;
+	return close + marker.length + opener[0].indexOf("(");
 };
 const parseRiskMarker = (line) => {
 	const marker = RISK_MARKER.exec(line);
@@ -2381,7 +2403,7 @@ const runLedgerValidate = async (inputs) => {
 	});
 	for (const id of spec.malformedTaskRefs) problems.push({
 		kind: "malformed-task-refs",
-		message: `${id} carries a "(R<n>"-shaped tail that is not a well-formed "(R1, R2)" ref list. Left as-is it reads as a task that references no requirement, and its slice shrinks to itself.`,
+		message: `${id} carries a "(R<n>"-shaped ref list that is not a declaration: a declaration is one comma-separated "(R1, R2)" group that ends a line — no ranges ("R1–R3"), nothing after the closing paren on that line — at the end of the task's first line, right after the title's bold close, or the only group ending a continuation line. Left as-is it reads as a task that references no requirement, and its slice shrinks to itself.`,
 		subject: id
 	});
 	const groups = resolveGroups(spec.groups, address, problems);
@@ -3039,7 +3061,8 @@ const prunePrefix = async (repoRoot, options = {}) => {
 		}
 		if (sentOffset > size) return { prunedBytes: 0 };
 		const stateDir = stateDirOf(repoRoot);
-		const drainPath = join(stateDir, `${DRAINING_BASENAME}.${`${process.pid}-${randomBytes(4).toString("hex")}`}`);
+		const id = `${process.pid}-${randomBytes(4).toString("hex")}`;
+		const drainPath = join(stateDir, `${DRAINING_BASENAME}.${id}`);
 		const metaPath = `${drainPath}.meta`;
 		await mkdir(stateDir, { recursive: true });
 		await writeFile(metaPath, JSON.stringify({ sent_offset: sentOffset }));
@@ -3080,14 +3103,15 @@ const appendRejects = async (repoRoot, rejects, now) => {
 	const path = join(repoRoot, REJECTED_RELPATH);
 	await mkdir(dirname(path), { recursive: true });
 	const ts = now().toISOString();
-	await appendFile(path, `${rejects.map((reject) => {
+	const body = rejects.map((reject) => {
 		const entry = {
 			ts,
 			reason: reject.reason,
 			line: reject.line
 		};
 		return JSON.stringify(entry);
-	}).join("\n")}\n`);
+	}).join("\n");
+	await appendFile(path, `${body}\n`);
 	return rejects.length;
 };
 //#endregion
@@ -3759,7 +3783,8 @@ const checkVersionPin = (deps, config) => {
 };
 const checkCliResolution = async (deps) => {
 	const name = "cli-resolution";
-	if (await isExecutable(join(deps.repoRoot, "node_modules", ".bin", "lemony"))) return {
+	const localBin = join(deps.repoRoot, "node_modules", ".bin", LEMONY_BIN);
+	if (await isExecutable(localBin)) return {
 		name,
 		status: "ok",
 		detail: `Telemetry CLI resolves from node_modules/.bin/${LEMONY_BIN} (the durable setup).`
@@ -4236,7 +4261,8 @@ const snapshotDestPaths = (version, bundle) => {
 	];
 };
 const writeSnapshot = async (repoRoot, version, bundle) => {
-	const staging = join(snapshotsRootDir(repoRoot), STAGING_DIR);
+	const root = snapshotsRootDir(repoRoot);
+	const staging = join(root, STAGING_DIR);
 	await assertNoSymlinkTraversal(repoRoot, snapshotDestPaths(version, bundle));
 	await rm(staging, {
 		recursive: true,
@@ -4595,9 +4621,10 @@ const COMPANION_DOCS = [
 	"partition"
 ];
 const renderFile = async (templatePath, relPath, vars) => {
+	const template = await readFile(templatePath, "utf8");
 	return {
 		relPath,
-		content: renderTemplate(await readFile(templatePath, "utf8"), vars),
+		content: renderTemplate(template, vars),
 		executable: false
 	};
 };
@@ -4673,7 +4700,8 @@ const appendGitignoreBlock = async (repoRoot) => {
 		await writeFile(gitignorePath, next);
 		return ".gitignore";
 	}
-	await writeFile(gitignorePath, `${current}${current.length === 0 ? "" : current.endsWith("\n") ? "\n" : "\n\n"}${GITIGNORE_BLOCK}\n`);
+	const prefix = current.length === 0 ? "" : current.endsWith("\n") ? "\n" : "\n\n";
+	await writeFile(gitignorePath, `${current}${prefix}${GITIGNORE_BLOCK}\n`);
 	return ".gitignore";
 };
 const removeGitignoreBlock = async (repoRoot) => {
@@ -4834,9 +4862,10 @@ const runInstall = async (options) => {
 	const losers = await collectLosers(repoRoot, actions);
 	let snapshotVersion = null;
 	if (losers.length > 0) {
+		const baseline = new Map(vendorFiles.map((file) => [file.relPath, file.content]));
 		await writeSnapshot(repoRoot, vendorVersion, {
 			working: losers,
-			baseline: new Map(vendorFiles.map((file) => [file.relPath, file.content]))
+			baseline
 		});
 		snapshotVersion = vendorVersion;
 	}
@@ -4893,7 +4922,8 @@ const runInstall = async (options) => {
 	};
 };
 const collectLosers = (repoRoot, actions) => {
-	return collectWorkingFiles(repoRoot, actions.filter((action) => action.kind === "pick-vendor").map((action) => action.relPath));
+	const losingPaths = actions.filter((action) => action.kind === "pick-vendor").map((action) => action.relPath);
+	return collectWorkingFiles(repoRoot, losingPaths);
 };
 //#endregion
 //#region src/install/resolve-collision.ts
@@ -4932,12 +4962,14 @@ const runReconcile = async (inputs) => {
 	const fromVersion = config.vendor_version;
 	const target = config.target;
 	const taskStorageRepo = config.task_storage.repo;
-	const predatedKeys = findPredatedKeys(await readFile(join(repoRoot, HARNESS_CONFIG_FILENAME), "utf8"), fromVersion, toVersion, inputs.configKeySince ?? CONFIG_KEY_SINCE);
+	const rawConfig = await readFile(join(repoRoot, HARNESS_CONFIG_FILENAME), "utf8");
+	const predatedKeys = findPredatedKeys(rawConfig, fromVersion, toVersion, inputs.configKeySince ?? CONFIG_KEY_SINCE);
 	const baselineVersion = await findBaselineVersion(repoRoot);
 	const baseline = baselineVersion ? await readBaseline(repoRoot, baselineVersion) : /* @__PURE__ */ new Map();
 	const hadBaseline = baseline.size > 0;
 	const capabilities = await scanRepo(repoRoot);
-	const skills = selectSkills(await readCatalogSkills(vendorRoot), capabilities);
+	const catalogSkills = await readCatalogSkills(vendorRoot);
+	const skills = selectSkills(catalogSkills, capabilities);
 	const vendorNew = await materializeVendorFiles({
 		vendorRoot,
 		target,
@@ -4973,14 +5005,16 @@ const runReconcile = async (inputs) => {
 		predatedKeys
 	};
 	if (hadBaseline) {
+		const working = await collectWorkingFiles(repoRoot, [...baseline.keys()]);
 		await writeSnapshot(repoRoot, fromVersion, {
-			working: await collectWorkingFiles(repoRoot, [...baseline.keys()]),
+			working,
 			baseline
 		});
 		await rotateSnapshots(repoRoot, config.rollback.keep_snapshots);
 	}
 	await applyActions(repoRoot, actions);
-	const { lostHookCommands } = await resyncSpecialCased(repoRoot, join(vendorRoot, "templates", target));
+	const templateRoot = join(vendorRoot, "templates", target);
+	const { lostHookCommands } = await resyncSpecialCased(repoRoot, templateRoot);
 	const labelSync = inputs.runCommand ? await syncLabels(taskStorageRepo, createTaskTrackerProvider(config.task_storage.type, inputs.runCommand)) : null;
 	await writeBaseline(repoRoot, toVersion, vendorNew);
 	await writeConfigValues(repoRoot, configBumps);
@@ -5014,7 +5048,8 @@ const applyActions = async (repoRoot, actions) => {
 			default: return;
 		}
 	}));
-	await pruneEmptyDirs(repoRoot, actions.filter((action) => action.kind === "prune").map((action) => action.relPath));
+	const prunedPaths = actions.filter((action) => action.kind === "prune").map((action) => action.relPath);
+	await pruneEmptyDirs(repoRoot, prunedPaths);
 };
 const summarize = (actions) => {
 	const conflictedFiles = [];
@@ -5044,12 +5079,10 @@ const summarize = (actions) => {
 				winner: "vendor"
 			});
 			break;
-		case "pick-client":
-			pickedFiles.push({
-				relPath: action.relPath,
-				winner: "client"
-			});
-			break;
+		case "pick-client": pickedFiles.push({
+			relPath: action.relPath,
+			winner: "client"
+		});
 	}
 	return {
 		conflictedFiles,
@@ -5155,11 +5188,12 @@ const runRollback = async (options) => {
 	await assertNoSymlinkTraversal(repoRoot, [...restorePaths, ...removePaths]);
 	await Promise.all(bundle.working.map((file) => writeManaged(repoRoot, file.relPath, file.content, file.executable)));
 	await Promise.all(removePaths.map((path) => rm(join(repoRoot, path), { force: true })));
-	await writeBaseline(repoRoot, target, [...bundle.baseline].map(([relPath, content]) => ({
+	const baselineFiles = [...bundle.baseline].map(([relPath, content]) => ({
 		relPath,
 		content,
 		executable: false
-	})));
+	}));
+	await writeBaseline(repoRoot, target, baselineFiles);
 	await writeConfigValues(repoRoot, { vendor_version: target });
 	return {
 		repoRoot,
@@ -5700,16 +5734,18 @@ const telemetryEnable = async (repoRoot) => {
 	for (const line of formatTelemetryStatus(report)) console.log(line);
 };
 const telemetrySend = async (repoRoot) => {
+	const endpoint = env["LEMONY_TELEMETRY_ENDPOINT"] ?? "https://lemony-telemetry.lemoncode.workers.dev";
 	const result = await sendTelemetry({
 		repoRoot,
-		endpoint: env["LEMONY_TELEMETRY_ENDPOINT"] ?? "https://lemony-telemetry.lemoncode.workers.dev"
+		endpoint
 	});
 	console.log(`telemetry ${result.outcome} (${result.segmentsSent} sent, ${result.quarantined} quarantined)`);
 };
 const telemetryFlush = async (repoRoot) => {
+	const endpoint = env["LEMONY_TELEMETRY_ENDPOINT"] ?? "https://lemony-telemetry.lemoncode.workers.dev";
 	const result = await sendTelemetry({
 		repoRoot,
-		endpoint: env["LEMONY_TELEMETRY_ENDPOINT"] ?? "https://lemony-telemetry.lemoncode.workers.dev"
+		endpoint
 	});
 	for (const line of formatTelemetryFlush(result)) console.log(line);
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lemoncode/lemony",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Lemony — a Harness for AI Coding. Vendor package: installer, agent role catalog, generic skill catalog, hooks, and templates for a Spec-Driven Development workflow.",
   "type": "module",
   "private": false,
@@ -50,16 +50,16 @@
     "@types/node": "24.13.3",
     "husky": "9.1.7",
     "lint-staged": "17.4.1",
-    "oxlint": "1.80.0",
+    "oxlint": "1.81.0",
     "prettier": "3.9.6",
-    "tsdown": "0.22.14",
-    "tsx": "4.23.12",
+    "tsdown": "0.23.0",
+    "tsx": "4.23.13",
     "typescript": "7.0.2",
-    "vitest": "4.1.11"
+    "vitest": "5.0.0"
   },
   "dependencies": {
     "yaml": "2.9.0",
-    "zod": "4.4.3"
+    "zod": "4.5.4"
   },
   "scripts": {
     "build": "tsdown",