getgloss 0.8.0 → 0.8.2

package/dist/web/setup.md

@@ -180,6 +180,9 @@ Use `--no-watch` when the caller only needs to open the review. The background
 daemon exits automatically after a short idle window with no pending reviews.
 If cleanup looks stale, run `gloss doctor`; use `gloss stop --all` when you
 want to terminate all Gloss daemon processes for the current user.
+Use `gloss clear --dry-run` to preview old completed review artifacts, and
+`gloss clear` to delete completed artifacts older than 30 days. Pending reviews
+are always preserved.
 
 Mark a submitted review handled after applying feedback:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "getgloss",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "description": "Local browser-based diff review for coding-agent loops.",
   "type": "module",
   "packageManager": "pnpm@10.33.2",

package/skill/SKILL.md

@@ -1,84 +1,82 @@
 ---
 name: gloss
-description: Open local working-tree or branch changes in Gloss for browser review, wait for submitted feedback, continue existing reviews with new turns, and address returned comments or discuss them before editing. Use when the user asks to review local code changes, says "gloss this" or "open Gloss", wants to inspect a browser diff, wants comments handled before a PR, asks for a follow-up review pass, or asks to discuss/propose feedback fixes first.
+description: Open local working-tree or branch changes in Gloss for browser review, wait for submitted feedback, continue existing reviews with new turns, inspect Gloss status/state, and address returned comments or discuss them before editing. Use when the user asks to review local code changes, says "gloss this" or "open Gloss", wants to inspect a browser diff, wants comments handled before a PR, asks for a follow-up review pass, asks to find Gloss review state/artifacts, or asks to discuss/propose feedback fixes first.
 ---
 
 # Gloss
 
 ## Workflow
 
-1. Run `gloss open --json` from the repo root unless the user names a base ref.
-2. Leave the command running. It blocks until the browser review is submitted.
-3. Parse the JSON output and read `feedbackPath` when present.
-4. Check `feedback.reviewScope`:
-   - Missing or `{ "mode": "all" }` means the human submitted feedback while viewing the whole turn.
-   - `{ "mode": "single", "sha": "..." }` means feedback was submitted from one commit preview.
-   - `{ "mode": "range", "fromSha": "...", "toSha": "..." }` means feedback was submitted from a contiguous commit range preview.
-   Treat scoped feedback as comments on that submitted slice; do not infer that unreviewed commits were approved.
-5. Decide the mode (see "Discussion Mode" below). Default is apply-directly.
-6. Address every comment in file and line order, or per the discussion plan.
-7. Validate the fix with the narrowest relevant checks.
-8. When useful, run `gloss resolve <reviewId> --comment <commentId> --summary "<what changed>"` as each comment is handled.
-9. Run `gloss resolve <reviewId> --summary "<what changed>"`, then summarize the feedback addressed and validation performed.
-10. If the user asks for another pass on the same work, run `gloss open --review <reviewId> --json` so the next diff is added as a new turn in the same review.
+1. From the repo root, run `gloss open --json` unless the user names a base ref.
+2. Leave it running; it waits until browser submission. Use `--no-watch` only when the user only wants the review opened.
+3. Parse the JSON output and read `feedbackPath`.
+4. Apply feedback in file/line order unless "Discussion Mode" applies.
+5. Validate with the narrowest relevant checks.
+6. Resolve handled feedback with `gloss resolve <reviewId> --comment <commentId> --summary "<what changed>"` when useful, then `gloss resolve <reviewId> --summary "<what changed>"`.
+7. For another pass on the same work, run `gloss open --review <reviewId> --json`; use a fresh `gloss open --json` only for unrelated work.
 
 ## Discussion Mode
 
-Some feedback is ambiguous, opinionated, or wide-reaching enough that the right
-move is to talk through it before editing code. Enter discussion mode when any
-of these are true:
+Enter discussion mode when the user asks to discuss/propose first, or when a
+comment is too ambiguous to apply safely. Trigger phrases include "discuss
+first", "talk through it", "don't apply yet", "review the comments with me",
+and "propose first".
 
-- The user asked for it before running gloss — phrases like "discuss first",
-  "talk through it", "don't apply yet", "let's discuss", "review the comments
-  with me", or "propose first".
-- A comment is genuinely ambiguous and you'd otherwise have to guess intent.
+When discussing:
 
-When in discussion mode:
+1. Read every comment in `feedback.json` before editing. Do not edit files yet.
+2. Group comments by file. Restate each comment in one line, propose the change, and flag conflicts/out-of-scope items.
+3. Ask which items to apply, modify, or skip, then wait for the answer.
+4. Apply only approved items, validate, then resolve as usual. Mention skipped items in the resolution summary.
 
-1. Read every comment in `feedback.json` first. Do not edit any files yet.
-2. Group comments by file. For each, restate the comment in one line and
-   propose how you'd address it — the approach plus the lines that would
-   change. Flag any that conflict, are out of scope, or need a decision.
-3. Ask the user which to apply, modify, or skip. Wait for an answer.
-4. Apply only what's approved. Skip or defer the rest, and note skipped items
-   in the resolution summary so they aren't silently dropped.
-5. Validate, then resolve as usual.
+Default when the user did not request discussion and comments are clear:
+apply feedback directly.
 
-Default (no discussion request and no ambiguous comments): the current
-apply-directly workflow.
+## Feedback Scope
 
-Feedback is stored under `~/.gloss/reviews/<reviewId>/`:
+Check `feedback.reviewScope` before editing:
 
-- `turns/<turnId>/feedback.json` is the machine-readable handoff.
-- `turns/<turnId>/feedback.md` is the human-readable copy.
-- `turns/<turnId>/resolved.json` tracks mutable comment-level and turn-level resolution progress.
+- Missing or `{ "mode": "all" }`: feedback covers the whole turn.
+- `{ "mode": "single", "sha": "..." }`: feedback covers one commit preview.
+- `{ "mode": "range", "fromSha": "...", "toSha": "..." }`: feedback covers a contiguous commit range.
 
-The same browser URL stays open for the whole loop. Each `gloss open --review
-<reviewId> --json` creates or resumes the next turn, and the browser turn history
-shows the lineage. Historical turns are read-only. Keep using the same review ID
-until the user starts unrelated work or explicitly wants a new review.
+Treat scoped feedback as comments on that submitted slice; do not infer that
+unreviewed commits were approved.
+
+## State And Artifacts
+
+For existing loops, run `gloss status --json` first; it reports daemon state and
+active review metadata. If the daemon is down or the review ID is missing,
+inspect durable state under `${GLOSS_STATE_DIR:-$HOME/.gloss}`:
+
+- `server.json`: daemon pid, port, version, and state dir.
+- `reviews/<reviewId>/meta.json`: review status, cwd, active turn, and turn summaries.
+- `reviews/<reviewId>/turns/<turnId>/`: `turn.json`, `diff.json`, `feedback.json`, `feedback.md`, `resolved.json`.
+
+Use this pattern to discover review files:
+
+```bash
+state_dir="${GLOSS_STATE_DIR:-$HOME/.gloss}"
+find "$state_dir/reviews" -maxdepth 4 -type f
+```
+
+The same browser URL stays open for each review loop. Historical turns are
+read-only.
 
 Gloss opens staged, unstaged, and untracked working changes first. If the
 working tree is clean, it falls back to the branch diff against the best
 available merge-base. Use `--base <ref>` only when the user asks for a specific
 comparison such as `origin/main`, `origin/master`, or `HEAD`.
 
-If the user asks only to open the review and not wait, run
-`gloss open --json --no-watch`.
-
 `gloss open --json` intentionally stays alive until the browser review is
-submitted or the watch timeout expires. If a long-running `gloss open` looks
-unexpected, first check whether it is waiting on an active browser review
-before killing processes.
+submitted or times out. If it looks stuck, check whether it is waiting on an
+active browser review before killing processes.
 
 The background daemon shuts down on its own after a short idle window with no
-pending reviews. If process cleanup still looks stale, run `gloss doctor` to
-report unmanaged daemons. Use `gloss stop --all` only when intentionally
-cleaning up all Gloss daemon processes for the current user.
-
-If the user asks for a follow-up review after fixes, commits, or additional
-changes in the same review loop, run `gloss open --review <reviewId> --json`.
-Use a fresh `gloss open --json` only for unrelated work or a truly new review.
+pending reviews. Use `gloss doctor` for stale process cleanup diagnostics,
+`gloss stop --all` only for intentional daemon cleanup, and
+`gloss clear --dry-run` before deleting completed artifacts older than 30 days
+with `gloss clear`. Pending reviews are always preserved.
 
 For less-common options, run `gloss open --help` or `gloss --help` instead of
 guessing flags.