npm - comprehende - Versions diffs - 0.7.0 → 0.8.0 - Mend

comprehende 0.7.0 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (268) hide show

package/skills/comprehende/SKILL.md CHANGED Viewed

@@ -12,14 +12,14 @@ Group a git diff into review concerns and serve a local UI. The point is cogniti
 Run every command inside the repository under review. Cwd is the repo; there is no `--repo` flag. Use the pinned CLI:
 ```sh
-npx comprehende@0.7.0 <command>
+npx comprehende@0.8.0 <command>
 ```
 The review document is interpretation only. It holds a title, groups, summaries, and hunk pointers. Do not copy patch text into it. `serve` reads the diff from git.
 ## Workflow
-1. Check npm for a newer package. Run `npm view comprehende version`. If that version is newer than this pin (`npx comprehende@0.7.0`), stop and tell the user. Show this command as an option they can run:
+1. Check npm for a newer package. Run `npm view comprehende version`. If that version is newer than this pin (`npx comprehende@0.8.0`), stop and tell the user. Show this command as an option they can run:
    ```sh
    npx skills update
@@ -27,19 +27,19 @@ The review document is interpretation only. It holds a title, groups, summaries,
    Do not run that command. Wait for them to continue with this pin, or to update and start this skill again. If the versions match or the query fails, continue.
 2. Resolve base and head. Use the refs the user named; three-dot (`base...head`) is the merge request or branch diff. When the change is already on the default branch, use the request's recorded base and head SHAs; the moving default-branch `HEAD` includes later merges. When only the head SHA is known, base is the merge-base of that head with the named base branch. Fetch refs missing from the local clone. Done when both refs resolve in cwd; if one still does not resolve, stop and tell the user rather than guess a ref.
-3. Run `npx comprehende@0.7.0 index [--base <ref>] [--head <ref>]` and keep the JSON outside the work tree (stdout or a temp file). Defaults: `--head` is `HEAD`; `--base` is `origin/HEAD`, falling back to `main` or `master`. The index lists hunk refs (path plus `@@` ranges), image files (`oldStart` and `newStart` 0), and `skipped` (lockfiles and non-image binaries). It carries no line content.
-4. Recover the why, write the title, and write the what. Read the sources listed under The why and The title, read `git diff --stat <base>...<head>` and the diffs themselves, then write document `title` (always), document `summary` (always), and document `why` (only when a source names the motive). Summaries come from the code, not the log.
+3. Run `npx comprehende@0.8.0 index [--base <ref>] [--head <ref>]` and keep the JSON outside the work tree (stdout or a temp file). Defaults: `--head` is `HEAD`; `--base` is `origin/HEAD`, falling back to `main` or `master`. The index lists hunk refs (path plus `@@` ranges), image files (`oldStart` and `newStart` 0), and `skipped` (lockfiles and non-image binaries). It carries no line content.
+4. Recover the why, write the title, write the what, and compare the sources with the diff. Read the sources listed under The why and The title, read `git diff --stat <base>...<head>` and the diffs themselves, then write document `title` (always), document `summary` (always), document `why` (only when a source names the motive), and document `lookFor` (only when a source names work to check against the diff; see lookFor). Summaries come from the code, not the log. Done when every piece of work a source names is either in the diff or in a document `lookFor` bullet.
 5. Group the hunks by review concern, following the Grouping rules. Done when every hunk ref from the index appears in at least one group and every group has its `why`.
 6. Write `review.json` in a fresh temp directory outside the repository (`mktemp -d` or the platform equivalent; the work tree stays untouched, with no new gitignore entries). Shape per [references/review.schema.json](./references/review.schema.json); worked example in [references/example.md](./references/example.md). Copy hunk objects verbatim from the index. Set document `size` from review burden, not `git diff --stat`.
-7. Run `npx comprehende@0.7.0 validate --data "$REVIEW_DIR/review.json"` with the absolute path. On failure, fix groups or coverage; the diff is git's, leave it alone. Done when validate exits 0.
-8. When they ask to upload the report, follow Export. Otherwise run `npx comprehende@0.7.0 serve --data "$REVIEW_DIR/review.json" --open` and give the user the localhost URL (`127.0.0.1` only).
+7. Run `npx comprehende@0.8.0 validate --data "$REVIEW_DIR/review.json"` with the absolute path. On failure, fix groups or coverage; the diff is git's, leave it alone. Done when validate exits 0.
+8. When they ask to upload the report, follow Export. Otherwise run `npx comprehende@0.8.0 serve --data "$REVIEW_DIR/review.json" --open` and give the user the localhost URL (`127.0.0.1` only).
 ## Export
 Write a static site and put that folder where they asked.
 ```sh
-npx comprehende@0.7.0 export --data "$REVIEW_DIR/review.json" --out "$EXPORT_DIR"
+npx comprehende@0.8.0 export --data "$REVIEW_DIR/review.json" --out "$EXPORT_DIR"
 ```
 `$EXPORT_DIR` is a fresh directory outside the work tree, not a git repository. The folder is the UI plus frozen git payloads. There is no git in it. Done when they have the URL or path they named. If `review.json` is not written yet, finish the Workflow through validate, then export.
@@ -91,9 +91,11 @@ Hunk identity is `(path, oldStart, newStart)` plus `oldPath` when renamed. Copy
 ## lookFor
-`lookFor` is for what the live diff does not make obvious. Empty is correct for a rename, a formatting change, or a wording-only docs group; leave it empty rather than fill it.
+`lookFor` is for what the live diff does not make obvious. Each bullet is one inspectable claim: optionally a short risk tag (Subtle, Breaking, Race, Perf), then one sentence. The bullet states the claim; the human checks it against the live diff and keeps the verdict. Pseudocode, diagrams, collapsed diffs, commit lists, hunk counts, and pass/fail marks stay out.
-Each bullet is one inspectable claim: optionally a short risk tag (Subtle, Breaking, Race, Perf), then one sentence. When a behavior change hides in the hunk, a predicted trace earns a bullet: a small realistic input, where the old and new paths diverge, and the observable result. The human checks the claim against the live diff; pseudocode, diagrams, collapsed diffs, commit lists, and hunk counts stay out.
+Group `lookFor` holds claims that live in those hunks. When a behavior change hides in the hunk, a predicted trace earns a bullet: a small realistic input, where the old and new paths diverge, and the observable result. Empty is correct for a rename, a formatting change, or a wording-only docs group; leave it empty rather than fill it.
+Document `lookFor` holds claims about the whole change, and work a source names that no hunk does. Compare each source with the diff. When a ticket, request, comment, or transcript names work, the bullet says what it asks for and what the diff does about it. Cite the source with `[text](source:s1)`; the id goes in `sources`, and `validate` fails on an unknown id. Omit the field when no source names expected work, or when the bullet would only restate document `summary`.
 ## Write the prose

package/skills/comprehende/references/example.md CHANGED Viewed

@@ -6,6 +6,7 @@ Pointers and prose only. The `@@` numbers must come from `comprehende index`, no
 - `docs` is a separate part, last in `suggestedOrder`, because it could have been its own pull request.
 - Ticket #12 names why this work exists, so document `why` is present. Document `title` keeps the ticket title. Document `summary` names both stories. The why cites the ticket with `[#12](source:s1)`.
 - `login` `summary` names how those hunks meet. `login` `lookFor` is a predicted trace. `docs` has no `lookFor`.
+- Document `lookFor` compares ticket #12 with the diff: work the ticket asks for that no hunk does, and one claim about the whole change. Both cite `[#12](source:s1)`. Group `lookFor` stays inside its hunks.
 ```json
 {
@@ -29,6 +30,10 @@ Pointers and prose only. The `@@` numbers must come from `comprehende index`, no
       "part": "Session cookie"
     }
   ],
+  "lookFor": [
+    "[#12](source:s1) also asks logout to clear the session cookie. No hunk touches `src/api/logout.ts`.",
+    "Subtle. [#12](source:s1) wants sessions that client scripts cannot read. Sessions issued before this change keep their old cookie until it expires; no hunk rotates them."
+  ],
   "groups": [
     {
       "id": "cookie",

package/skills/comprehende/references/review.schema.json CHANGED Viewed

@@ -62,6 +62,14 @@
         "$ref": "#/$defs/source"
       }
     },
+    "lookFor": {
+      "description": "Whole-change and missing-work claims. Cite the source. Do not store a pass/fail.",
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
     "groups": {
       "type": "array",
       "items": {