instar 0.28.87 → 0.28.88

package/dist/core/ProjectDigestCache.d.ts

@@ -0,0 +1,58 @@
+import type { InitiativeTracker, Initiative } from './InitiativeTracker.js';
+/** Where the digest lands. Hooks read this exact path. */
+export declare const DIGEST_CACHE_FILENAME = "projects-digest.cache";
+/** Max projects rendered into `digestLines`. Top-N by `lastTouchedAt`. */
+export declare const MAX_PROJECTS_IN_DIGEST = 5;
+/** Max characters per sanitized string (titles, round names). */
+export declare const MAX_STRING_LENGTH = 80;
+/** JSON shape that the hooks deserialize. */
+export interface ProjectDigestCacheFile {
+    /** ISO timestamp when this snapshot was written. */
+    generatedAt: string;
+    /** One sanitized one-liner per active project, top-N by `lastTouchedAt`. */
+    digestLines: string[];
+    /** Total active projects in the tracker (independent of truncation). */
+    totalActiveProjects: number;
+    /** True iff `totalActiveProjects > MAX_PROJECTS_IN_DIGEST`. */
+    truncated: boolean;
+}
+/**
+ * Strip control chars (incl. \n, \r, \t), then collapse runs of internal
+ * whitespace to single spaces and cap at `cap` chars.
+ *
+ * Exported so the hooks (well, their JS-side helpers) and tests can apply
+ * the same rule on read. The bash hooks themselves use a `tr`-based
+ * equivalent — the literal regex below is the canonical implementation.
+ */
+export declare function sanitizeDigestString(input: unknown, cap?: number): string;
+/**
+ * Render one digest line for a single project. Pure function — caller
+ * provides the project; sanitization happens inside.
+ */
+export declare function formatProjectDigestLine(project: Initiative): string;
+/**
+ * ProjectDigestCache — single-responsibility writer. Construct once at
+ * server boot; pass `writeDigestCache.bind(this)` as the invalidator on
+ * `InitiativeTracker.setDigestCacheInvalidator(fn)`.
+ */
+export declare class ProjectDigestCache {
+    private readonly filePath;
+    private readonly tracker;
+    /** Bound to `process.pid` so concurrent writers (test sandbox + main
+     *  process) don't trample one another's temp files. */
+    private readonly tmpSuffix;
+    constructor(stateDir: string, tracker: InitiativeTracker);
+    /** Absolute path to the cache file. Exposed for diagnostics. */
+    getCachePath(): string;
+    /**
+     * Snapshot all active projects, render the top-N digest lines, and write
+     * the result atomically. Synchronous on purpose — runs in the
+     * invalidator hot path (every project mutation calls it once).
+     *
+     * Best-effort: any thrown error is swallowed after logging, so a hiccup
+     * writing the cache never blocks a successful mutation.
+     */
+    writeDigestCache(): void;
+    private atomicWrite;
+}
+//# sourceMappingURL=ProjectDigestCache.d.ts.map

package/dist/core/ProjectDigestCache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProjectDigestCache.d.ts","sourceRoot":"","sources":["../../src/core/ProjectDigestCache.ts"],"names":[],"mappings":"AA8BA,OAAO,KAAK,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAE5E,0DAA0D;AAC1D,eAAO,MAAM,qBAAqB,0BAA0B,CAAC;AAE7D,0EAA0E;AAC1E,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAExC,iEAAiE;AACjE,eAAO,MAAM,iBAAiB,KAAK,CAAC;AAEpC,6CAA6C;AAC7C,MAAM,WAAW,sBAAsB;IACrC,oDAAoD;IACpD,WAAW,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,wEAAwE;IACxE,mBAAmB,EAAE,MAAM,CAAC;IAC5B,+DAA+D;IAC/D,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,SAAoB,GAAG,MAAM,CAUpF;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,UAAU,GAAG,MAAM,CAsBnE;AAaD;;;;GAIG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;IAC5C;2DACuD;IACvD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAEvB,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB;IAMxD,gEAAgE;IAChE,YAAY,IAAI,MAAM;IAItB;;;;;;;OAOG;IACH,gBAAgB,IAAI,IAAI;IA4BxB,OAAO,CAAC,WAAW;CAOpB"}

package/dist/core/ProjectDigestCache.js

@@ -0,0 +1,146 @@
+/**
+ * ProjectDigestCache — writes a sanitized JSON snapshot of active projects
+ * to `.instar/projects-digest.cache` for cheap, no-HTTP consumption by
+ * session-start and compaction-recovery hooks.
+ *
+ * Spec source: PROJECT-SCOPE-SPEC.md § Phase 1.9 (session-start + compaction
+ * recovery hooks). The hooks have a ≤50ms budget — pure file read, no HTTP.
+ *
+ * Invariants:
+ *   - Top 5 active projects by `lastTouchedAt` (desc) are included; the
+ *     `truncated` flag + `totalActiveProjects` count make over-limit visible.
+ *   - Every string field that lands in the cache is sanitized at write time:
+ *     control chars (incl. newline + CR) stripped, and the result capped at
+ *     80 characters. The hooks ALSO sanitize on read (defense in depth),
+ *     so direct cache-file poisoning can't smuggle an unprintable string
+ *     into orientation output.
+ *   - Atomic on-disk write (temp file + rename) — readers never observe a
+ *     partial file. Matches the pattern `InitiativeTracker.saveToDisk()`
+ *     uses for its own persistence.
+ *
+ * This module is the **read side** of the invalidator hook PR 1 added on
+ * InitiativeTracker (`setDigestCacheInvalidator`). The server wires
+ * `writeDigestCache()` as the invalidator at boot, so every successful
+ * project mutation re-renders the file. Mutations on `kind:'task'`
+ * initiatives also trigger a rewrite — the function filters internally to
+ * `kind:'project' && status:'active'`, so the side effect is a no-op when
+ * no project state changed.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+/** Where the digest lands. Hooks read this exact path. */
+export const DIGEST_CACHE_FILENAME = 'projects-digest.cache';
+/** Max projects rendered into `digestLines`. Top-N by `lastTouchedAt`. */
+export const MAX_PROJECTS_IN_DIGEST = 5;
+/** Max characters per sanitized string (titles, round names). */
+export const MAX_STRING_LENGTH = 80;
+/**
+ * Strip control chars (incl. \n, \r, \t), then collapse runs of internal
+ * whitespace to single spaces and cap at `cap` chars.
+ *
+ * Exported so the hooks (well, their JS-side helpers) and tests can apply
+ * the same rule on read. The bash hooks themselves use a `tr`-based
+ * equivalent — the literal regex below is the canonical implementation.
+ */
+export function sanitizeDigestString(input, cap = MAX_STRING_LENGTH) {
+    const raw = typeof input === 'string' ? input : input == null ? '' : String(input);
+    // Strip ASCII control chars (0x00-0x1F) and DEL (0x7F).
+    // Replaces with a single space so words don't collide.
+    // eslint-disable-next-line no-control-regex
+    const stripped = raw.replace(/[\x00-\x1F\x7F]/g, ' ');
+    // Collapse internal whitespace runs, trim ends.
+    const collapsed = stripped.replace(/\s+/g, ' ').trim();
+    if (collapsed.length <= cap)
+        return collapsed;
+    return collapsed.slice(0, cap);
+}
+/**
+ * Render one digest line for a single project. Pure function — caller
+ * provides the project; sanitization happens inside.
+ */
+export function formatProjectDigestLine(project) {
+    const id = sanitizeDigestString(project.id, MAX_STRING_LENGTH);
+    const rounds = Array.isArray(project.rounds) ? project.rounds : [];
+    const total = rounds.length;
+    const done = rounds.filter((r) => r && (r.status === 'complete' || r.status === 'complete-with-skips')).length;
+    // Next round: first non-complete round in order. Falls through to "(none)"
+    // when every round is done.
+    const next = rounds.find((r) => r &&
+        r.status !== 'complete' &&
+        r.status !== 'complete-with-skips' &&
+        r.status !== 'failed');
+    const nextLabel = next
+        ? sanitizeDigestString(next.name || '(unnamed round)', MAX_STRING_LENGTH)
+        : '(none — all rounds complete)';
+    return `Project [${id}]: ${done} of ${total} done. Next round: ${nextLabel}.`;
+}
+/**
+ * Sort projects by `lastTouchedAt` descending. Ties broken by `id` ascending
+ * so the output is stable.
+ */
+function sortByLastTouched(a, b) {
+    const at = a.lastTouchedAt ?? '';
+    const bt = b.lastTouchedAt ?? '';
+    if (at === bt)
+        return a.id.localeCompare(b.id);
+    return bt.localeCompare(at);
+}
+/**
+ * ProjectDigestCache — single-responsibility writer. Construct once at
+ * server boot; pass `writeDigestCache.bind(this)` as the invalidator on
+ * `InitiativeTracker.setDigestCacheInvalidator(fn)`.
+ */
+export class ProjectDigestCache {
+    filePath;
+    tracker;
+    /** Bound to `process.pid` so concurrent writers (test sandbox + main
+     *  process) don't trample one another's temp files. */
+    tmpSuffix;
+    constructor(stateDir, tracker) {
+        this.filePath = path.join(stateDir, DIGEST_CACHE_FILENAME);
+        this.tracker = tracker;
+        this.tmpSuffix = `.${process.pid}.tmp`;
+    }
+    /** Absolute path to the cache file. Exposed for diagnostics. */
+    getCachePath() {
+        return this.filePath;
+    }
+    /**
+     * Snapshot all active projects, render the top-N digest lines, and write
+     * the result atomically. Synchronous on purpose — runs in the
+     * invalidator hot path (every project mutation calls it once).
+     *
+     * Best-effort: any thrown error is swallowed after logging, so a hiccup
+     * writing the cache never blocks a successful mutation.
+     */
+    writeDigestCache() {
+        try {
+            const all = this.tracker.list({ kind: 'project', status: 'active' });
+            // `list()` already sorts by `lastTouchedAt` desc; re-sort defensively
+            // in case the contract changes underneath us.
+            const sorted = [...all].sort(sortByLastTouched);
+            const total = sorted.length;
+            const truncated = total > MAX_PROJECTS_IN_DIGEST;
+            const top = sorted.slice(0, MAX_PROJECTS_IN_DIGEST);
+            const digestLines = top.map((p) => formatProjectDigestLine(p));
+            const payload = {
+                generatedAt: new Date().toISOString(),
+                digestLines,
+                totalActiveProjects: total,
+                truncated,
+            };
+            this.atomicWrite(JSON.stringify(payload, null, 2));
+        }
+        catch (err) {
+            console.warn(`[ProjectDigestCache] writeDigestCache failed (non-fatal): ${err instanceof Error ? err.message : err}`);
+        }
+    }
+    atomicWrite(contents) {
+        const dir = path.dirname(this.filePath);
+        fs.mkdirSync(dir, { recursive: true });
+        const tmp = `${this.filePath}${this.tmpSuffix}`;
+        fs.writeFileSync(tmp, contents);
+        fs.renameSync(tmp, this.filePath);
+    }
+}
+//# sourceMappingURL=ProjectDigestCache.js.map

package/dist/core/ProjectDigestCache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProjectDigestCache.js","sourceRoot":"","sources":["../../src/core/ProjectDigestCache.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "0.28.87",
+  "version": "0.28.88",
   "description": "Persistent autonomy infrastructure for AI agents",
   "type": "module",
   "main": "dist/index.js",

package/src/data/builtin-manifest.json

@@ -1,9 +1,9 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-05-11T20:08:03.908Z",
-  "instarVersion": "0.28.87",
-  "entryCount": 187,
+  "generatedAt": "2026-05-11T23:38:42.167Z",
+  "instarVersion": "0.28.88",
+  "entryCount": 188,
   "entries": {
     "hook:session-start": {
       "id": "hook:session-start",
@@ -363,6 +363,14 @@
       "contentHash": "5b3557fa3662cf0c7b7bab85a252cc2e567b3fc64a04a92d430374ef1f264ca6",
       "since": "2025-01-01"
     },
+    "skill:instar-project": {
+      "id": "skill:instar-project",
+      "type": "skill",
+      "domain": "skills",
+      "sourcePath": ".claude/skills/instar-project/SKILL.md",
+      "contentHash": "8c8a924740d8afedeb5e0b4bea7a3760c9654dc6b49a9a415429fe0366ff8429",
+      "since": "2025-01-01"
+    },
     "skill:secret-setup": {
       "id": "skill:secret-setup",
       "type": "skill",
@@ -984,7 +992,7 @@
       "type": "template",
       "domain": "safety",
       "sourcePath": "src/templates/hooks/compaction-recovery.sh",
-      "contentHash": "97929330cdb4794117bbaafbfbd0635d95c27b24a1189a685eae9f5445000642",
+      "contentHash": "ca6a2a5c2ee03839654c9708912292bc03d81c61281dffbbb958d4877ee1dc91",
       "since": "2025-01-01"
     },
     "template:dangerous-command-guard.sh": {
@@ -1024,7 +1032,7 @@
       "type": "template",
       "domain": "safety",
       "sourcePath": "src/templates/hooks/session-start.sh",
-      "contentHash": "1b63c4646f30126601f8e425359d9638442e92561e27fa404d33f832bd03e263",
+      "contentHash": "4d98736d3ee30fe8639f0851e5e492416ad05f4ae49f84e8695723faa4b9398e",
       "since": "2025-01-01"
     },
     "template:settings-template.json": {

package/src/templates/hooks/compaction-recovery.sh

@@ -464,5 +464,55 @@ if [ -f "$CONFIG_FILE" ] && command -v tmux >/dev/null 2>&1; then
   fi
 fi
 
+# Active projects digest — file-first, no HTTP (PROJECT-SCOPE-SPEC Phase 1.9).
+# Re-injects the active-project orientation after compaction so the agent
+# doesn't lose track of multi-spec work. Same cache as session-start.sh.
+DIGEST_FILE="$INSTAR_DIR/projects-digest.cache"
+echo ""
+if [ -f "$DIGEST_FILE" ]; then
+  PROJ_DIGEST=$(python3 - "$DIGEST_FILE" <<'PYEOF' 2>/dev/null
+import json, re, sys
+path = sys.argv[1]
+try:
+    with open(path, 'r', encoding='utf-8') as f:
+        d = json.load(f)
+    lines = d.get('digestLines') or []
+    if not isinstance(lines, list):
+        sys.exit(0)
+    ctrl = re.compile(r'[\x00-\x1F\x7F]')
+    cleaned = []
+    for ln in lines[:5]:
+        if not isinstance(ln, str):
+            continue
+        s = ctrl.sub(' ', ln)
+        s = re.sub(r'\s+', ' ', s).strip()
+        if not s:
+            continue
+        cleaned.append(s[:200])
+    if not cleaned:
+        print('Active projects: none')
+    else:
+        print('--- ACTIVE PROJECTS (post-compaction) ---')
+        for c in cleaned:
+            print(c)
+        truncated = bool(d.get('truncated'))
+        total = d.get('totalActiveProjects')
+        if truncated and isinstance(total, int) and total > len(cleaned):
+            more = total - len(cleaned)
+            print(f'+{more} more on dashboard.')
+        print('--- END ACTIVE PROJECTS ---')
+except Exception:
+    sys.exit(0)
+PYEOF
+)
+  if [ -n "$PROJ_DIGEST" ]; then
+    echo "$PROJ_DIGEST"
+  else
+    echo "Active projects: state unavailable — run /project status when ready"
+  fi
+else
+  echo "Active projects: state unavailable — run /project status when ready"
+fi
+
 echo ""
 echo "=== RECOVERY COMPLETE — You are grounded. Continue your work. ==="

package/src/templates/hooks/session-start.sh

@@ -355,4 +355,54 @@ except Exception:
   fi
 fi
 
+# Active projects digest — file-first, no HTTP (PROJECT-SCOPE-SPEC Phase 1.9).
+# Reads .instar/projects-digest.cache, written by the server on every
+# project mutation. Re-sanitizes each line on read for defense in depth.
+DIGEST_FILE="$INSTAR_DIR/projects-digest.cache"
+echo ""
+if [ -f "$DIGEST_FILE" ]; then
+  PROJ_DIGEST=$(python3 - "$DIGEST_FILE" <<'PYEOF' 2>/dev/null
+import json, re, sys
+path = sys.argv[1]
+try:
+    with open(path, 'r', encoding='utf-8') as f:
+        d = json.load(f)
+    lines = d.get('digestLines') or []
+    if not isinstance(lines, list):
+        sys.exit(0)
+    ctrl = re.compile(r'[\x00-\x1F\x7F]')
+    cleaned = []
+    for ln in lines[:5]:
+        if not isinstance(ln, str):
+            continue
+        s = ctrl.sub(' ', ln)
+        s = re.sub(r'\s+', ' ', s).strip()
+        if not s:
+            continue
+        cleaned.append(s[:200])
+    if not cleaned:
+        print('Active projects: none')
+    else:
+        print('--- ACTIVE PROJECTS ---')
+        for c in cleaned:
+            print(c)
+        truncated = bool(d.get('truncated'))
+        total = d.get('totalActiveProjects')
+        if truncated and isinstance(total, int) and total > len(cleaned):
+            more = total - len(cleaned)
+            print(f'+{more} more on dashboard.')
+        print('--- END ACTIVE PROJECTS ---')
+except Exception:
+    sys.exit(0)
+PYEOF
+)
+  if [ -n "$PROJ_DIGEST" ]; then
+    echo "$PROJ_DIGEST"
+  else
+    echo "Active projects: state unavailable — run /project status when ready"
+  fi
+else
+  echo "Active projects: state unavailable — run /project status when ready"
+fi
+
 exit 0

package/upgrades/0.28.88.md

@@ -0,0 +1,91 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: minor -->
+<!-- Valid values: patch, minor, major -->
+<!-- patch = bug fixes, refactors, test additions, doc updates -->
+<!-- minor = new features, new APIs, new capabilities (backwards-compatible) -->
+<!-- major = breaking changes to existing APIs or behavior -->
+
+## What Changed
+
+### Project-scope Phase 1a PR 3 — `/project` skill + session-start digest
+
+Final of three PRs scaffolding the project-scope feature. PR 1 added
+the type-level fields; PR 2 added the stage-transition validator and
+HTTP surface; PR 3 ships the user-invocable surface and the
+session-start orientation block so active projects stay visible across
+new sessions.
+
+Spec source: `docs/specs/PROJECT-SCOPE-SPEC.md` §§ Phase 1.7 (skill),
+Phase 1.9 (session-start + compaction-recovery hooks).
+
+**New files:**
+- `src/core/ProjectDigestCache.ts` — synchronous writer that
+  snapshots active projects to `.instar/projects-digest.cache`. Top 5
+  by `lastTouchedAt`, sanitized strings (control-char strip + 80-char
+  per-field cap), atomic write.
+- `.claude/skills/instar-project/SKILL.md` — slash-command skill. Phase
+  1a ships `/project create`, `/project status`, and `/project next`
+  (read-only + create). The mutating commands ship in Phase 1b along
+  with the round-runner.
+
+**Wired-in behavior:**
+- Server boot now constructs a `ProjectDigestCache` and registers it
+  as the digest invalidator on `InitiativeTracker`. Every successful
+  project mutation (create / update / status change) re-renders the
+  cache file atomically. First boot writes the cache unconditionally
+  so the hook scripts always have a well-formed file to read.
+- `.instar/hooks/instar/session-start.sh` and
+  `.instar/hooks/instar/compaction-recovery.sh` append an
+  `--- ACTIVE PROJECTS ---` block at the end of their orientation
+  output. They read the cache file (no HTTP, ≤50ms budget), re-sanitize
+  each line on read (defense in depth), and fall back to
+  `Active projects: state unavailable — run /project status when ready`
+  on miss / parse error.
+
+**Cache file shape (`.instar/projects-digest.cache`):**
+```json
+{
+  "generatedAt": "2026-05-11T...",
+  "digestLines": [
+    "Project [my-project]: 2 of 5 done. Next round: Round 3."
+  ],
+  "totalActiveProjects": 1,
+  "truncated": false
+}
+```
+
+## What to Tell Your User
+
+PR 3 closes the first slice of the project-tracking work. Your agent now has a built-in slash command for inspecting and registering projects, plus a session-start orientation line that keeps active projects visible at the top of every new conversation.
+
+What you'll see at session start: a short Active Projects block with up to five projects, one line each — telling you the project name, how many rounds are done out of the total, and what the next round is. If you have more than five active projects, the block ends with a note saying how many more are on the dashboard. If your agent has no projects registered yet, the block is empty.
+
+What this changes day-to-day: your agent won't lose track of multi-spec projects after a session restart or a context compaction. Before this, the first few features in a project would get attention and the rest would drift off the radar. Now the project roster is structurally visible at every new conversation. The same digest re-injects after context compression, so a long session that hits the compaction window still keeps the active-project orientation in context.
+
+The project skill itself is this slice's read-only surface: you can register a project from a markdown plan doc, list all projects, fetch one with its children, or ask "what's next?" (which currently returns a placeholder — the next phase will wire the real answer). The mutating commands that actually drive a project forward — advancing rounds, halting, acknowledging, resuming, abandoning, running a round, drift-checking, accepting a partial round, and claiming ownership across machines — ship in the next phase once the round-runner lands.
+
+Nothing existing changes shape. The initiatives routes still return what they always did. The new session-start block appears at the end of the orientation output and is plain text. If your agent doesn't register projects, you won't see any difference.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| `/project create <plan-doc>` | Register a project from a markdown plan via `POST /projects` |
+| `/project status [id]` | List all projects, or fetch one with its children, via `GET /projects[/:id]` |
+| `/project next [id]` | Phase 1a placeholder; returns the spec's 501 response |
+| Session-start project digest | Top 5 active projects rendered at every new session start (no extra config) |
+| Compaction-recovery digest | Same digest re-injects after context compression |
+| Cache file (read-only consumer) | `.instar/projects-digest.cache` — JSON snapshot, atomic writes, sanitized |
+
+## Evidence
+
+Spec: `docs/specs/PROJECT-SCOPE-SPEC.md` §§ 1.7, 1.9.
+
+- `tests/unit/ProjectDigestCache.test.ts` — 19 new tests covering
+  empty case, 3-project + 7-project cases, sanitization (control char
+  strip + 80-char cap), atomic write, invalidator wiring.
+- `tests/unit/project-digest-hooks.test.ts` — 7 new tests exercising
+  the bash hook scripts against present / missing / malformed /
+  poisoned cache files.
+- Side-effects review: `upgrades/side-effects/project-scope-phase1a-pr3.md`.

package/upgrades/side-effects/0.28.87.md

@@ -0,0 +1,13 @@
+# Side-Effects Review — v0.28.87
+
+This release shipped two user-facing changes:
+
+- **Stuck-Telegram-message auto-recovery (PR #151)** — side-effects review at
+  [`verify-injection-stuck-input.md`](./verify-injection-stuck-input.md).
+- **Project-scope Phase 1a PR 2 — stage validator + `/projects` API** —
+  side-effects review at
+  [`project-scope-phase1a-pr2.md`](./project-scope-phase1a-pr2.md).
+
+This file is the version-keyed pointer the pre-push gate looks for; the
+per-change artifacts above contain the actual side-effects analysis. No
+other behavior changed in 0.28.87 beyond what those two reviews cover.