comprehende 0.3.0 → 0.4.0

package/README.md

@@ -25,18 +25,25 @@ pnpm typecheck
 pnpm build
 pnpm pack:smoke
 pnpm sync:skill
+pnpm release:skill
 pnpm dev -- --help
 ```
 
 `pnpm build` emits `dist/cli` and `dist/ui`. `prepack` runs that build, so `pnpm pack` / `pnpm publish` always ship the UI.
 
+`pnpm sync:skill` copies the JSON Schema into `skills-next/comprehende/`, pins `npx comprehende@<version>` there, and mirrors that tree into `.agents/skills/comprehende` so agents in this checkout use the next skill. It does not touch `skills/comprehende/`.
+
 `comprehende serve` and `comprehende export` share one UI and one git payload layer. Serve computes those payloads on each request. Export writes the same JSON (and image bytes) next to the UI so any static file server can host the review.
 
-`pnpm dev` and `pnpm exec` run with this package as cwd, so they only make sense when _this_ repo is the one under review. To review a different project from a checkout, `cd` into it and run `npx comprehende@0.3.0` (or `node /path/to/comprehende/dist/cli/main.js` after `pnpm build`).
+`pnpm dev` and `pnpm exec` run with this package as cwd, so they only make sense when _this_ repo is the one under review. To review a different project from a checkout, `cd` into it and run `npx comprehende@0.4.0` (or `node /path/to/comprehende/dist/cli/main.js` after `pnpm build`).
 
 ## Release
 
-Bump `version` in `package.json` when the CLI or UI changes, then run `pnpm sync:skill` so the skill pin matches. Pre-commit and `pnpm test` fail if the staged package version and skill pin differ. Do not bump for skill-only edits.
+Edit the skill in `skills-next/comprehende/`. `npx skills add` reads `skills/comprehende/` only.
+
+Bump `version` in `package.json` when the CLI or UI changes, then run `pnpm sync:skill` so the next skill pin matches. Pre-commit and `pnpm test` fail if the staged package version and next skill pin differ. Do not bump for skill-only edits.
+
+When that next skill should ship with `npx skills add`, run `pnpm release:skill`. That copies `skills-next/comprehende/` onto `skills/comprehende/`. Run it in the same change that publishes a new CLI. Then `npx skills add` installs instructions that match the package they pin.
 
 Push to `main`. CI packs and tests the tarball on every change. If the version is not on npm yet, CI publishes it. Skill-only commits keep the same version, so they do not publish.
 

package/dist/api/live.js

@@ -1,12 +1,13 @@
 import { loadDocument } from "../cli/commands.js";
 import { blameFile } from "../git/blame.js";
 import { readImageBlob } from "../git/blob.js";
-import { fileLanguage, filePatchFromGit, resolveSource, toHunkRef } from "../git/diff.js";
+import { fileLanguage, filePatchFromGit, readPathDiff, resolveSource, toHunkRef } from "../git/diff.js";
 import { GitError } from "../git/exec.js";
 import { listCommits } from "../git/log.js";
 import { mergeBase } from "../git/repo.js";
 import { showFile } from "../git/show.js";
 import { coverReview } from "../review/coverage.js";
+import { isLockfilePath } from "../schema/lockfile.js";
 import { ApiError } from "./error.js";
 export async function openReview(cwd, dataPath) {
     const document = await loadDocument(dataPath);
@@ -34,6 +35,7 @@ export async function openReview(cwd, dataPath) {
 }
 export function reviewPayload(ctx) {
     const { document, resolved, files, coverage, commits } = ctx;
+    const lockfiles = lockfileFiles(files);
     return {
         document,
         resolved,
@@ -49,6 +51,7 @@ export function reviewPayload(ctx) {
             .map((group) => ({
             id: group.group.id,
             title: group.group.title,
+            why: group.group.why,
             summary: group.group.summary,
             lookFor: group.group.lookFor ?? [],
             dependsOn: group.group.dependsOn ?? [],
@@ -62,6 +65,10 @@ export function reviewPayload(ctx) {
             hunkCount: coverage.unassigned.length,
             files: uniquePaths(coverage.unassigned),
         },
+        lockfiles: {
+            fileCount: lockfiles.length,
+            files: lockfiles.map((file) => file.path),
+        },
         stale: coverage.stale,
         files: files.map((file) => {
             const entry = {
@@ -87,6 +94,9 @@ export function hunksPayload(ctx, groupId) {
     if (groupId === "unassigned") {
         return serializeLayer(ctx.files, ctx.coverage.unassigned);
     }
+    if (groupId === "lockfiles") {
+        return serializeLockfiles(ctx.files);
+    }
     const group = ctx.coverage.groups.find((item) => item.group.id === groupId);
     if (group === undefined) {
         throw new ApiError(404, `unknown group "${groupId}"`);
@@ -153,10 +163,16 @@ export async function renderResource(ctx, resource) {
             return { encoding: "json", body: await blamePayload(ctx, resource.path, resource.side) };
         case "image":
             return imagePayload(ctx, resource.path, resource.side);
+        case "patch":
+            return { encoding: "json", body: await patchPayload(ctx, resource.path) };
     }
 }
 export function listResources(ctx) {
-    const resources = [{ kind: "review" }, { kind: "hunks", group: "unassigned" }];
+    const resources = [
+        { kind: "review" },
+        { kind: "hunks", group: "unassigned" },
+        { kind: "hunks", group: "lockfiles" },
+    ];
     for (const group of ctx.document.groups) {
         resources.push({ kind: "hunks", group: group.id });
     }
@@ -167,6 +183,9 @@ export function listResources(ctx) {
             }
             continue;
         }
+        if (isLockfilePath(file.path) && !file.binary) {
+            resources.push({ kind: "patch", path: file.path });
+        }
         for (const side of sidesFor(file)) {
             resources.push({ kind: "file", path: file.path, side });
             resources.push({ kind: "blame", path: file.path, side });
@@ -197,21 +216,48 @@ function serializeLayer(files, hunks) {
         }
         groups.push({ file, hunks: [hunk] });
     }
-    const serializedFiles = groups.map(({ file, hunks: fileHunks }) => {
-        const next = {
-            path: file.path,
-            kind: file.image ? "image" : "text",
-            status: file.status,
-            patch: file.image ? file.headerPatch : filePatchFromGit(file, fileHunks),
-            hunks: fileHunks.map(serializeHunk),
-        };
-        if (file.oldPath !== undefined) {
-            next.oldPath = file.oldPath;
-        }
-        return next;
-    });
+    const serializedFiles = groups.map(({ file, hunks: fileHunks }) => serializeLayerFile(file, fileHunks, true));
     return { hunks: hunks.map(serializeHunk), files: serializedFiles };
 }
+function serializeLockfiles(files) {
+    const serializedFiles = lockfileFiles(files).map((file) => serializeLayerFile(file, [], true));
+    return { hunks: [], files: serializedFiles };
+}
+function lockfileFiles(files) {
+    return files.filter((file) => isLockfilePath(file.path) && !file.binary && !file.image);
+}
+async function patchPayload(ctx, path) {
+    const file = findFile(ctx.files, path);
+    if (!isLockfilePath(file.path) || file.binary || file.image) {
+        throw new ApiError(404, "path is not a deferred lockfile");
+    }
+    const live = await readPathDiff(ctx.cwd, ctx.document.source.baseRef, ctx.document.source.headRef, file.path);
+    if (live === undefined) {
+        throw new ApiError(404, `no live diff for ${path}`);
+    }
+    return serializeLayerFile(live, live.hunks, false);
+}
+function serializeLayerFile(file, fileHunks, deferLockfile) {
+    const lockfile = isLockfilePath(file.path) && !file.binary && !file.image;
+    const deferred = deferLockfile && lockfile;
+    const next = {
+        path: file.path,
+        kind: file.image ? "image" : lockfile ? "lockfile" : "text",
+        status: file.status,
+        patch: deferred ? "" : file.image ? file.headerPatch : filePatchFromGit(file, fileHunks),
+        hunks: fileHunks.map(serializeHunk),
+    };
+    if (file.oldPath !== undefined) {
+        next.oldPath = file.oldPath;
+    }
+    if (file.added !== undefined) {
+        next.added = file.added;
+    }
+    if (file.removed !== undefined) {
+        next.removed = file.removed;
+    }
+    return next;
+}
 function serializeHunk(hunk) {
     return {
         ...toHunkRef(hunk),

package/dist/api/paths.js

@@ -10,6 +10,8 @@ export function apiHref(resource) {
             return `api/blame/${resource.side}/${encodeFilePath(resource.path)}.json`;
         case "image":
             return `api/images/${resource.side}/${encodeFilePath(resource.path)}`;
+        case "patch":
+            return `api/patches/${encodeFilePath(resource.path)}.json`;
     }
 }
 /** Decoded relative path under the site root. Static hosts map encoded request URLs onto this. */
@@ -25,6 +27,8 @@ export function apiFsRel(resource) {
             return `api/blame/${resource.side}/${resource.path}.json`;
         case "image":
             return `api/images/${resource.side}/${resource.path}`;
+        case "patch":
+            return `api/patches/${resource.path}.json`;
     }
 }
 export function parseApiPath(pathname) {
@@ -53,6 +57,20 @@ export function parseApiPath(pathname) {
         }
         return { kind: "image", path, side };
     }
+    if (parts[1] === "patches" && parts.length >= 3) {
+        const rest = parts.slice(2);
+        const last = rest.at(-1);
+        const stem = last === undefined ? undefined : jsonStem(last);
+        if (stem === undefined) {
+            return undefined;
+        }
+        rest[rest.length - 1] = stem;
+        const path = rest.join("/");
+        if (!isRepoPath(path)) {
+            return undefined;
+        }
+        return { kind: "patch", path };
+    }
     if ((parts[1] === "files" || parts[1] === "blame") && parts.length >= 4 && parts[2] !== undefined) {
         const side = parts[2];
         if (side !== "old" && side !== "new") {

package/dist/git/diff.js

@@ -1,6 +1,8 @@
 import { isImagePath, isLfsPointerText } from "../schema/image.js";
+import { isLockfilePath } from "../schema/lockfile.js";
 import { git } from "./exec.js";
-import { rangeLabel, resolveCommit } from "./repo.js";
+import { parseNameStatus, parseNumstat } from "./name-status.js";
+import { assertSafePath, rangeLabel, resolveCommit } from "./repo.js";
 const HUNK_HEADER = /^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/;
 export async function resolveSource(cwd, baseRef, headRef) {
     const baseSha = await resolveCommit(cwd, baseRef);
@@ -12,6 +14,53 @@ export async function resolveSource(cwd, baseRef, headRef) {
     };
 }
 export async function readDiff(cwd, baseRef, headRef) {
+    await resolveCommit(cwd, baseRef);
+    await resolveCommit(cwd, headRef);
+    const range = `${baseRef}...${headRef}`;
+    const entries = parseNameStatus(await git(cwd, ["diff", "--find-renames", "--find-copies", "--name-status", "-z", "--end-of-options", range]));
+    const lockEntries = entries.filter((entry) => isLockfilePath(entry.path));
+    const diffArgs = [
+        "diff",
+        "--find-renames",
+        "--find-copies",
+        "-U3",
+        "--no-color",
+        "--no-ext-diff",
+        "--end-of-options",
+        range,
+    ];
+    if (lockEntries.length > 0) {
+        const excludes = [
+            ...new Set(lockEntries.flatMap((entry) => {
+                const paths = [`:(exclude)${entry.path}`];
+                if (entry.oldPath !== undefined) {
+                    paths.push(`:(exclude)${entry.oldPath}`);
+                }
+                return paths;
+            })),
+        ];
+        diffArgs.push("--", ".", ...excludes);
+    }
+    const files = classifyDiffFiles(parseUnifiedDiff(await git(cwd, diffArgs))).filter((file) => !isLockfilePath(file.path));
+    if (lockEntries.length === 0) {
+        return files;
+    }
+    const stats = parseNumstat(await git(cwd, [
+        "diff",
+        "--find-renames",
+        "--find-copies",
+        "--numstat",
+        "-z",
+        "--end-of-options",
+        range,
+        "--",
+        ...lockEntries.map((entry) => entry.path),
+    ]));
+    const stubs = lockEntries.map((entry) => lockfileDiffFile(entry, stats.get(entry.path)));
+    return mergeDiffFiles(entries, files, stubs);
+}
+export async function readPathDiff(cwd, baseRef, headRef, path) {
+    assertSafePath(path);
     await resolveCommit(cwd, baseRef);
     await resolveCommit(cwd, headRef);
     const stdout = await git(cwd, [
@@ -23,8 +72,11 @@ export async function readDiff(cwd, baseRef, headRef) {
         "--no-ext-diff",
         "--end-of-options",
         `${baseRef}...${headRef}`,
+        "--",
+        path,
     ]);
-    return classifyDiffFiles(parseUnifiedDiff(stdout));
+    const files = classifyDiffFiles(parseUnifiedDiff(stdout));
+    return files.find((file) => file.path === path || file.oldPath === path);
 }
 export async function readHunkIndex(cwd, baseRef, headRef) {
     const { source } = await resolveSource(cwd, baseRef, headRef);
@@ -42,6 +94,10 @@ export async function readHunkIndex(cwd, baseRef, headRef) {
             skipped.push({ path: file.path, reason: "binary" });
             continue;
         }
+        if (isLockfilePath(file.path)) {
+            skipped.push({ path: file.path, reason: "lockfile" });
+            continue;
+        }
         for (const hunk of file.hunks) {
             hunks.push(toHunkRef(hunk));
         }
@@ -293,6 +349,9 @@ export function flattenHunks(files) {
         if (file.binary && !file.image) {
             continue;
         }
+        if (isLockfilePath(file.path)) {
+            continue;
+        }
         hunks.push(...file.hunks);
     }
     return hunks;
@@ -328,6 +387,46 @@ export function imageLiveHunk(path, oldPath) {
     }
     return hunk;
 }
+function lockfileDiffFile(entry, stat) {
+    const binary = stat === undefined || stat.added === null || stat.removed === null;
+    const file = {
+        path: entry.path,
+        status: entry.status,
+        binary,
+        image: false,
+        headerPatch: "",
+        patch: "",
+        hunks: [],
+    };
+    if (entry.oldPath !== undefined) {
+        file.oldPath = entry.oldPath;
+    }
+    if (!binary && stat !== undefined && stat.added !== null && stat.removed !== null) {
+        file.added = stat.added;
+        file.removed = stat.removed;
+    }
+    return file;
+}
+function mergeDiffFiles(entries, files, stubs) {
+    const filesByPath = new Map(files.map((file) => [file.path, file]));
+    const stubsByPath = new Map(stubs.map((file) => [file.path, file]));
+    const out = [];
+    const seen = new Set();
+    for (const entry of entries) {
+        const file = stubsByPath.get(entry.path) ?? filesByPath.get(entry.path);
+        if (file === undefined || seen.has(file.path)) {
+            continue;
+        }
+        seen.add(file.path);
+        out.push(file);
+    }
+    for (const file of files) {
+        if (!seen.has(file.path)) {
+            out.push(file);
+        }
+    }
+    return out;
+}
 export function fileLanguage(path) {
     if (isImagePath(path)) {
         return "image";

package/dist/git/log.js

@@ -1,8 +1,10 @@
 import { git } from "./exec.js";
+const RECORD_SEP = "\x1e";
+const FIELD_SEP = "\0";
 export async function listCommits(cwd, baseRef, headRef) {
     const stdout = await git(cwd, [
         "log",
-        "--format=%H%x00%h%x00%s%x00%an%x00%ad",
+        "--format=%H%x00%h%x00%s%x00%an%x00%ad%x00%b%x1e",
         "--date=short",
         "--end-of-options",
         `${baseRef}...${headRef}`,
@@ -11,16 +13,19 @@ export async function listCommits(cwd, baseRef, headRef) {
         return [];
     }
     return stdout
-        .split("\n")
-        .filter((line) => line.length > 0)
-        .map((line) => {
-        const [sha, shortSha, subject, author, date] = line.split("\0");
-        return {
-            sha: sha ?? "",
-            shortSha: shortSha ?? "",
-            subject: subject ?? "",
-            author: author ?? "",
-            date: date ?? "",
-        };
-    });
+        .split(RECORD_SEP)
+        .map((record) => record.replace(/^\n/, ""))
+        .filter((record) => record.length > 0)
+        .map(parseCommitRecord);
+}
+function parseCommitRecord(record) {
+    const [sha, shortSha, subject, author, date, ...bodyParts] = record.split(FIELD_SEP);
+    return {
+        sha: sha ?? "",
+        shortSha: shortSha ?? "",
+        subject: subject ?? "",
+        author: author ?? "",
+        date: date ?? "",
+        body: (bodyParts.join(FIELD_SEP) ?? "").replace(/\n+$/u, ""),
+    };
 }

package/dist/git/name-status.js

@@ -0,0 +1,73 @@
+export function parseNameStatus(stdout) {
+    const parts = stdout.split("\0").filter((part) => part !== "");
+    const entries = [];
+    let index = 0;
+    while (index < parts.length) {
+        const code = parts[index];
+        index += 1;
+        if (code === undefined) {
+            break;
+        }
+        if (code.startsWith("R") || code.startsWith("C")) {
+            const oldPath = parts[index];
+            const path = parts[index + 1];
+            index += 2;
+            if (oldPath === undefined || path === undefined) {
+                break;
+            }
+            entries.push({ status: "renamed", path, oldPath });
+            continue;
+        }
+        const path = parts[index];
+        index += 1;
+        if (path === undefined) {
+            break;
+        }
+        entries.push({ status: statusFrom(code), path });
+    }
+    return entries;
+}
+/** Git `--numstat -z`: `added\\tdeleted\\tpath\\0`, or `added\\tdeleted\\t\\0old\\0new\\0` for a rename. */
+export function parseNumstat(stdout) {
+    const parts = stdout.split("\0");
+    const out = new Map();
+    let index = 0;
+    while (index < parts.length) {
+        const field = parts[index];
+        if (field === undefined || field === "") {
+            index += 1;
+            continue;
+        }
+        const match = /^(-|\d+)\t(-|\d+)\t(.*)$/.exec(field);
+        if (match === null || match[1] === undefined || match[2] === undefined || match[3] === undefined) {
+            break;
+        }
+        index += 1;
+        const added = parseCount(match[1]);
+        const removed = parseCount(match[2]);
+        if (match[3] !== "") {
+            out.set(match[3], { path: match[3], added, removed });
+            continue;
+        }
+        const oldPath = parts[index];
+        const path = parts[index + 1];
+        index += 2;
+        if (oldPath === undefined || path === undefined || oldPath === "" || path === "") {
+            break;
+        }
+        out.set(path, { path, oldPath, added, removed });
+    }
+    return out;
+}
+function parseCount(value) {
+    return value === "-" ? null : Number(value);
+}
+function statusFrom(code) {
+    if (code.startsWith("A")) {
+        return "added";
+    }
+    if (code.startsWith("D")) {
+        return "deleted";
+    }
+    return "modified";
+}

package/dist/review/coverage.js

@@ -1,5 +1,6 @@
 import { flattenHunks, readDiff, toHunkRef } from "../git/diff.js";
 import { hunkKey } from "../schema/identity.js";
+import { isLockfilePath } from "../schema/lockfile.js";
 export async function coverReview(cwd, document) {
     const files = await readDiff(cwd, document.source.baseRef, document.source.headRef);
     const live = flattenHunks(files);
@@ -16,6 +17,9 @@ export function joinCoverage(document, live) {
         const hunks = [];
         const stale = [];
         for (const ref of group.hunkRefs) {
+            if (isLockfilePath(ref.path)) {
+                continue;
+            }
             const match = liveByKey.get(hunkKey(ref));
             if (match === undefined) {
                 stale.push(ref);
@@ -23,7 +27,7 @@ export function joinCoverage(document, live) {
                 continue;
             }
             hunks.push(match);
-            assignedKeys.add(hunkKey(ref));
+            assignedKeys.add(hunkKey(match));
         }
         return { group, hunks, stale };
     });

package/dist/schema/lockfile.js

@@ -0,0 +1,38 @@
+const LOCKFILE_NAMES = new Set([
+    ".terraform.lock.hcl",
+    "bun.lock",
+    "bun.lockb",
+    "cabal.project.freeze",
+    "Cargo.lock",
+    "Cartfile.resolved",
+    "composer.lock",
+    "conda-lock.yml",
+    "deno.lock",
+    "flake.lock",
+    "Gemfile.lock",
+    "go.sum",
+    "go.work.sum",
+    "Gopkg.lock",
+    "gradle.lockfile",
+    "lazy-lock.json",
+    "mix.lock",
+    "npm-shrinkwrap.json",
+    "package-lock.json",
+    "Package.resolved",
+    "pdm.lock",
+    "Pipfile.lock",
+    "pixi.lock",
+    "pnpm-lock.yaml",
+    "Podfile.lock",
+    "poetry.lock",
+    "pubspec.lock",
+    "renv.lock",
+    "shrinkwrap.yaml",
+    "stack.yaml.lock",
+    "uv.lock",
+    "yarn.lock",
+]);
+export function isLockfilePath(path) {
+    const base = path.split("/").pop() ?? path;
+    return LOCKFILE_NAMES.has(base) || base.endsWith(".gradle.lockfile");
+}

package/dist/schema/parse.js

@@ -1,8 +1,8 @@
 import { isReviewSize, REVIEW_SIZES } from "./types.js";
-const DOCUMENT_KEYS = new Set(["version", "source", "size", "walkthrough", "tickets", "groups"]);
+const DOCUMENT_KEYS = new Set(["version", "source", "size", "summary", "why", "tickets", "groups"]);
 const SOURCE_KEYS = new Set(["baseRef", "headRef", "range"]);
-const TICKET_KEYS = new Set(["id", "url", "title"]);
-const GROUP_KEYS = new Set(["id", "title", "summary", "lookFor", "dependsOn", "part", "suggestedOrder", "hunkRefs"]);
+const TICKET_KEYS = new Set(["id", "url", "title", "part"]);
+const GROUP_KEYS = new Set(["id", "title", "why", "summary", "lookFor", "dependsOn", "part", "suggestedOrder", "hunkRefs"]);
 const HUNK_KEYS = new Set(["path", "oldPath", "oldStart", "oldLines", "newStart", "newLines"]);
 export function parseReviewDocument(input) {
     const errors = [];
@@ -15,20 +15,22 @@ export function parseReviewDocument(input) {
     }
     const source = parseSource(input.source, errors);
     const size = parseSize(input.size, errors);
+    const summary = requiredString(input.summary, "summary", errors);
     const tickets = parseTickets(input.tickets, errors);
     const groups = parseGroups(input.groups, errors);
-    const walkthrough = input.walkthrough === undefined ? undefined : requiredString(input.walkthrough, "walkthrough", errors);
-    if (errors.length > 0 || source === undefined || size === undefined) {
+    const why = input.why === undefined ? undefined : requiredString(input.why, "why", errors);
+    if (errors.length > 0 || source === undefined || size === undefined || summary === undefined) {
         return { ok: false, errors };
     }
     const document = {
         version: 1,
         source,
         size,
+        summary,
         groups,
     };
-    if (walkthrough !== undefined) {
-        document.walkthrough = walkthrough;
+    if (why !== undefined) {
+        document.why = why;
     }
     if (tickets !== undefined) {
         document.tickets = tickets;
@@ -105,6 +107,12 @@ function parseTickets(value, errors) {
                 ticket.title = title;
             }
         }
+        if (item.part !== undefined) {
+            const part = requiredString(item.part, `tickets[${i}].part`, errors);
+            if (part !== undefined) {
+                ticket.part = part;
+            }
+        }
         tickets.push(ticket);
     });
     return tickets;
@@ -124,20 +132,21 @@ function parseGroups(value, errors) {
         extraKeys(item, GROUP_KEYS, `groups[${i}]`, errors);
         const id = requiredString(item.id, `groups[${i}].id`, errors);
         const title = requiredString(item.title, `groups[${i}].title`, errors);
+        const why = requiredString(item.why, `groups[${i}].why`, errors);
         const summary = requiredString(item.summary, `groups[${i}].summary`, errors, { allowEmpty: true });
         const suggestedOrder = requiredNumber(item.suggestedOrder, `groups[${i}].suggestedOrder`, errors);
         const hunkRefs = parseHunkRefs(item.hunkRefs, `groups[${i}].hunkRefs`, errors);
         const lookFor = parseStringList(item.lookFor, `groups[${i}].lookFor`, errors);
         const dependsOn = parseStringList(item.dependsOn, `groups[${i}].dependsOn`, errors);
         const part = item.part === undefined ? undefined : requiredString(item.part, `groups[${i}].part`, errors);
-        if (id === undefined || title === undefined || summary === undefined || suggestedOrder === undefined) {
+        if (id === undefined || title === undefined || why === undefined || summary === undefined || suggestedOrder === undefined) {
             return;
         }
         if (ids.has(id)) {
             errors.push(`duplicate group id "${id}"`);
         }
         ids.add(id);
-        const group = { id, title, summary, suggestedOrder, hunkRefs };
+        const group = { id, title, why, summary, suggestedOrder, hunkRefs };
         if (lookFor !== undefined) {
             group.lookFor = lookFor;
         }

package/dist/schema/skill-paths.js

@@ -3,9 +3,9 @@ import { findPackageRoot } from "../package-root.js";
 export function skillPaths(root = findPackageRoot()) {
     return {
         canonicalSchema: join(root, "src/schema/review.schema.json"),
+        nextSkill: join(root, "skills-next/comprehende"),
         publishedSkill: join(root, "skills/comprehende"),
         installedSkill: join(root, ".agents/skills/comprehende"),
-        publishedSchema: join(root, "skills/comprehende/references/review.schema.json"),
-        installedSchema: join(root, ".agents/skills/comprehende/references/review.schema.json"),
+        nextSchema: join(root, "skills-next/comprehende/references/review.schema.json"),
     };
 }