worclaude 2.9.0 → 2.9.2

package/CHANGELOG.md

@@ -4,6 +4,42 @@ All notable changes to worclaude are documented in this file. Format loosely fol
 
 ## [Unreleased]
 
+## [2.9.2] — 2026-04-28
+
+`upstream-check` workflow rebuild: fixes a 5-day silence and migrates to the official client library. Root cause of the silence: the daily workflow committed `.github/upstream-state.json` and pushed to `main`, but `main`'s branch protection (PR-required + 4 required status checks) rejected every push with `GH013`. State never advanced, items were re-evaluated daily, and the `Create issue` step was gated behind state-push success — silent forever. State persistence is now `actions/cache@v4` (key prefix `upstream-state-v3-`); the workflow no longer touches the git tree, `contents: write` permission dropped. Migration to [`@sefaertunc/anthropic-watch-client`](https://www.npmjs.com/package/@sefaertunc/anthropic-watch-client) replaces ~80 lines of hand-rolled fetch/dedup with composite-`uniqueKey` dedup (the `id`-only dedup at `scripts/upstream-precheck.mjs:95` was already silently dropping items where two sources shared an ID — `2.1.114` was the live example), version-gated fetch (`FeedVersionMismatchError`), and typed errors. Claude prompt + `upstream-watcher` agent + `docs/reference/upstream-automation.md` updated for the `community` source category (Reddit, HN, Twitter, GitHub commits — informational only per upstream's contract). Source counts no longer hardcoded — derived from `summary.sourcesChecked`.
+
+### Fixed
+
+- **5-day upstream-check silence** (PR follows) — replaces direct-push-to-`main` state persistence with `actions/cache@v4`. Fixes `GH013` rejection that blocked state advance and issue creation since `2026-04-18T09:08:21Z`. `contents: write` permission dropped.
+- **Composite-key dedup bug** in `scripts/upstream-precheck.mjs` (PR follows) — was deduping by `id` alone, silently dropping items where two sources shared an ID. Now uses `@sefaertunc/anthropic-watch-client`'s `filterNew` with the spec'd `${id}|${source}` fallback for legacy state entries.
+
+### Changed
+
+- **Migrated upstream fetch to `@sefaertunc/anthropic-watch-client@^1.0.2`** (PR follows) — version-gated feed envelope (`FeedVersionMismatchError`), typed `FeedFetchError` / `FeedMalformedError`, composite `uniqueKey` dedup. Three minor versions overdue per upstream's `WORCLAUDE-INTEGRATION.md` tracking note.
+- **Workflow Claude prompt** (PR follows) — added `community` source category (Reddit, HN, Twitter/X, GitHub commits) treated as informational-only per anthropic-watch's contract; removed hardcoded "16 sources" wording in favor of `summary.sourcesChecked`.
+- **`upstream-watcher` agent prompt** (template + dogfood, byte-identical) — updated to describe client-library usage and the `community` impact-classification row.
+
+### Tests
+
+- **`tests/scripts/upstream-precheck.test.js`** (new, 20 cases) — covers happy path, dedup correctness (including the cross-source-same-id regression case), legacy `${id}|unknown` fallback, all four typed-error paths, schema-version refusal, 90-day prune, watchdog-issue-number preservation, and the full output-key contract for downstream workflow steps.
+
+### Docs
+
+- **`docs/reference/upstream-automation.md`** — rewrote State File section for cache-based persistence, replaced "Required branch protection" with "Branch protection on `main` — fully compatible", added Community-source policy subsection, added v2.9.2 to version history.
+- **`docs/reference/agents.md`** — `upstream-watcher` description: source count now described as dynamic; switched from "via `curl` (no npm dependencies)" to client-library usage.
+
+## [2.9.1] — 2026-04-28
+
+Security patch clearing three transitive dev-dep advisories surfaced by Socket.dev and `npm audit` (esbuild dev-server CORS, vite path-traversal in optimized-deps, postcss XSS in CSS stringify). All three were dev-only, gated behind running `npm run docs:dev` and visiting a hostile origin in the same session — neither CI nor end-user installs trigger the conditions — but they kept appearing in scanner output and drowning out signal. Resolved via `npm overrides` in `package.json` (esbuild ^0.25.0, vite ^6.4.2, postcss ^8.5.10) which forces vitepress 1.6.4 onto patched transitives despite its declared `vite ^5.4.14` peer range; `npm run docs:build` verified clean. SECURITY.md rewritten: stale "pending upstream fixes" section replaced with "fixed via overrides", new false-positive subsections for Socket's AI-typosquat alert ("Did you mean: claude") and URL-strings alert (template content, not endpoints), supported-version table bumped to 2.9.x.
+
+### Fixed
+
+- **Three transitive dev-dep CVEs cleared via `npm overrides`** (PR #153) — esbuild 0.21.5 → 0.25.12 ([GHSA-67mh-4wv8-2f99](https://github.com/advisories/GHSA-67mh-4wv8-2f99) / CVE-2026-41305), vite 5.4.21 → 6.4.2 ([GHSA-4w7w-66w2-5vf9](https://github.com/advisories/GHSA-4w7w-66w2-5vf9) / CVE-2026-39365), postcss 8.5.8 → 8.5.12 ([GHSA-qx2v-qp2m-jg93](https://github.com/advisories/GHSA-qx2v-qp2m-jg93)). `npm audit` now reports 0 vulnerabilities; all 947 tests still pass; `npm run docs:build` succeeds against vitepress 1.6.4.
+
+### Docs
+
+- **`SECURITY.md` refresh** (PR #153) — replaces the obsolete "pending upstream fixes" section with a "fixed via overrides" section listing each advisory and resolved version. Adds two new false-positive subsections documenting Socket's AI-typosquat alert ("Did you mean: claude" — permanent, package was published under this name from day one) and URL-strings alert (flagged hostnames/filenames are template prose under `templates/`, not runtime endpoints; only `src/utils/npm.js` makes a network call). Bumps the supported-version table from `2.6.x` to `2.9.x`.
+
 ## [2.9.0] — 2026-04-28
 
 Audit-driven workflow rebuild executing the canonical 7-phase plan derived from the 2026-04 master architecture audit, plus the @claude GitHub Action surface and post-phase polish. Phase 1 cleaned drift and gap-filled hooks. Phase 2 rebuilt the slash-command surface, retired three superseded commands, and split `/start`/`/end` into distinct forward-looking-handoff and backward-looking-session-summary artifacts with `sha:` frontmatter for SHA-based drift detection. Phase 3 made agent files the routing source of truth via a new frontmatter contract (`category`, `triggerType`, `whenToUse`, `whatItDoes`, `expectBack`, `situationLabel`) regenerated on every `/sync` and `worclaude upgrade`. Phase 4 introduced the memory-architecture skill and the `/update-claude-md` promotion algorithm. Phase 5 added the `worclaude doc-lint` subcommand. Phase 6a shipped end-to-end observability — capture, the `worclaude observability` aggregator, and the `/observability` slash command. Phase 7 added an `init` opt-in for the @claude GitHub Action workflow. Post-phase polish required explicit human invocation of `/commit-push-pr` or `/sync` for any git write (no more conversational "yes" authorizations) and extracted multi-line bash from three slash commands into POSIX helper scripts under `templates/scripts/` so each invocation matches a single allow rule. Test surface grew from 804/58 files to 947/69 files.

package/SECURITY.md

@@ -4,8 +4,8 @@
 
 | Version | Supported          |
 | ------- | ------------------ |
-| 2.6.x   | :white_check_mark: |
-| < 2.6   | :x:                |
+| 2.9.x   | :white_check_mark: |
+| < 2.9   | :x:                |
 
 ## Reporting a Vulnerability
 
@@ -69,39 +69,33 @@ an opt-in `workflow-meta.json`. The `fs-extra`-based filesystem capability
 flag is a disclosure, not a vulnerability — removing it would delete the
 tool's core function.
 
-### Dev-only transitive advisories pending upstream fixes
-
-Two advisories sit deep in the dev-dependency tree and cannot currently be
-resolved without either forking `vitepress` or waiting for its next release:
-
-- **[GHSA-4w7w-66w2-5vf9](https://github.com/advisories/GHSA-4w7w-66w2-5vf9)** —
-  `vite@5.4.21` path traversal in optimized-deps handling. Fixed in
-  `vite@>=6.4.2`.
-- **[GHSA-67mh-4wv8-2f99](https://github.com/advisories/GHSA-67mh-4wv8-2f99)** —
-  `esbuild@0.21.5` dev-server CORS misconfiguration. Fixed in
-  `esbuild@>=0.25.0`.
-
-Both are pulled through `vitepress@1.6.4` (the current latest on npm),
-which pins `vite` at `^5.0.0`, which in turn pins `esbuild` at `^0.21.3`.
-`npm overrides` cannot force newer major versions without breaking the
-vite peer contract.
-
-Why these do not block a release:
-
-- Both packages are in `devDependencies` only. The `files` whitelist in
-  `package.json` does not include `tests/` or any dev tooling; end users
-  installing `worclaude` via npm do not get these packages.
-- Both advisories require an **active local dev server** to exploit. The
-  vite/vitest attack surface only exists while `npm run docs:dev` is
-  running and the operator browses to a hostile origin in the same
-  session. `npm test`, `npm run lint`, `npm run docs:build`, and CI
-  runs do not start a server.
-- Worclaude's CI does not run `docs:dev`; it runs `test`, `lint`, and
-  `docs:build` only.
-
-Tracking: a GitHub issue is opened to bump `vitepress` once a release
-using `vite@>=6.4.2` lands upstream. Until then the scanner will continue
-to flag these, and we accept the dev-only risk.
+### Dev-only transitive advisories (fixed via overrides)
+
+Three advisories sat deep in the dev-dependency tree, all pulled through
+`vitepress@1.6.4 → vite@5.x → esbuild@0.21.x`. They are now pinned to
+patched versions via `"overrides"` in `package.json`:
+
+- **[GHSA-67mh-4wv8-2f99](https://github.com/advisories/GHSA-67mh-4wv8-2f99)
+  / CVE-2026-41305** — `esbuild` dev-server CORS misconfiguration.
+  Override: `"esbuild": "^0.25.0"` (resolved 0.25.12).
+- **[GHSA-4w7w-66w2-5vf9](https://github.com/advisories/GHSA-4w7w-66w2-5vf9)
+  / CVE-2026-39365** — `vite` path traversal in optimized-deps handling
+  (affects vite 6.0.0–6.4.1; Socket's range matcher also flags 5.x).
+  Override: `"vite": "^6.4.2"` (resolved 6.4.2).
+- **[GHSA-qx2v-qp2m-jg93](https://github.com/advisories/GHSA-qx2v-qp2m-jg93)** —
+  `postcss` XSS via unescaped `</style>` in CSS stringify output.
+  Override: `"postcss": "^8.5.10"` (resolved 8.5.12).
+
+Verified clean: `npm audit` reports 0 vulnerabilities, `npm run docs:build`
+succeeds against `vitepress@1.6.4` despite its declared `vite@^5.4.14`
+peer range, and all 947 tests pass.
+
+These were not exploitable in worclaude's actual usage — every advisory
+required an active local dev server (`npm run docs:dev`) and the operator
+visiting a hostile origin in the same session. `npm test`, `npm run lint`,
+`npm run docs:build`, and CI never start a server. They are flagged
+nonetheless because Socket and `npm audit` scan the lockfile by version,
+not by exploit reachability.
 
 ### brace-expansion DoS (fixed via override)
 
@@ -109,3 +103,28 @@ to flag these, and we accept the dev-only risk.
 `brace-expansion@<1.1.13` zero-step sequence. Fixed in 1.1.13; enforced
 via `"overrides": { "brace-expansion": "^1.1.13" }` in `package.json`
 since v2.6.2. Pulled by `eslint@9.x → minimatch@3.x`.
+
+### AI-detected typosquat alert (false positive)
+
+Socket's "AI-detected possible typosquat — Did you mean: claude" flag
+triggers because the package name `worclaude` contains the substring
+`claude`. The package was published under this name from day one
+(2026-02), the npm namespace is owned by the original author
+(`sefaertunc`), and the package is the canonical home for the workflow
+described in this README. There is no upstream `claude` workflow
+scaffolder being typosquatted — `claude` on npm is an unrelated
+abandoned package. Renaming a published, indexed package would break
+every existing user's CLI alias and slash-command muscle memory; the
+alert is accepted as a permanent false positive.
+
+### URL-strings supply-chain alert (template content)
+
+Socket's "URL strings" alert lists hostnames and filenames extracted
+from the package's text content (e.g. `gitforwindows.org`, `Fly.io`,
+`Platform.sh`, `CLAUDE.md`, `SKILL.md`). Every match is documentation
+or template prose under `templates/` — instruction text the scaffolder
+writes into the user's project. Worclaude does not make network calls
+at runtime; the only HTTP code path is `src/utils/npm.js`, which
+queries the npm registry for the latest published version during
+`worclaude upgrade` and `worclaude status`. The flagged strings are
+content, not endpoints.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "worclaude",
-  "version": "2.9.0",
+  "version": "2.9.2",
   "description": "The Workflow Layer for Claude Code — scaffold agents, commands, skills, hooks, and memory into any project",
   "type": "module",
   "bin": {
@@ -64,6 +64,7 @@
   ],
   "license": "MIT",
   "dependencies": {
+    "@sefaertunc/anthropic-watch-client": "^1.0.2",
     "chalk": "^5.4.1",
     "commander": "^13.1.0",
     "fs-extra": "^11.3.0",
@@ -79,6 +80,9 @@
     "vitest": "^3.0.9"
   },
   "overrides": {
-    "brace-expansion": "^1.1.13"
+    "brace-expansion": "^1.1.13",
+    "esbuild": "^0.25.0",
+    "vite": "^6.4.2",
+    "postcss": "^8.5.10"
   }
 }

package/templates/agents/universal/upstream-watcher.md

@@ -27,24 +27,39 @@ You are read-only. Report findings and recommend actions — do not implement th
 
 ## 1. Fetch Upstream Feeds
 
-Feed base: `https://sefaertunc.github.io/anthropic-watch/feeds/`
-
-Fetch both feeds in parallel to keep the worst-case wait bounded by a single
-`--max-time`:
-
-```bash
-curl -s --max-time 10 https://sefaertunc.github.io/anthropic-watch/feeds/run-report.json &
-curl -s --max-time 10 https://sefaertunc.github.io/anthropic-watch/feeds/all.json &
-wait
+Use the official client library `@sefaertunc/anthropic-watch-client` (zero
+runtime deps, version-gated, composite-key dedup, typed errors). Add it to the
+project's `package.json` if not already present, then:
+
+```js
+import {
+  AnthropicWatchClient,
+  FeedFetchError,
+  FeedMalformedError,
+  FeedVersionMismatchError,
+} from '@sefaertunc/anthropic-watch-client';
+
+const client = new AnthropicWatchClient({ timeout: 10_000 });
+const [report, items] = await Promise.all([
+  client.fetchRunReport(),
+  client.fetchAllItems(),
+]);
 ```
 
-If either fetch fails (non-zero exit, empty body, or non-JSON), report
-"Could not reach anthropic-watch feeds" and stop — no impact analysis is
-possible without the feed data.
+If any fetch throws `FeedFetchError` (network/HTTP), `FeedMalformedError`
+(bad JSON), or `FeedVersionMismatchError` (feed schema bump), report
+"Could not reach anthropic-watch feeds: {error.message}" and stop — no
+impact analysis is possible without the feed data.
+
+`report` gives per-source health, `summary.sourcesChecked` (the live source
+count — do not hardcode a number), and `newItemCount` per source. `items`
+gives every item across all sources, sorted newest-first. Each item carries
+`id`, `uniqueKey`, `source`, `sourceCategory`, `sourceName`, `title`, `date`,
+`url`, `snippet`.
 
-`run-report.json` gives per-source health and `newItemCount`. `all.json` gives
-the full list of items across all 16 sources, sorted newest-first. Each item
-carries `source`, `sourceCategory`, `title`, `date`, `url`, `snippet`.
+The client lib's `filterNew(items, seenSet)` and `uniqueKey(item)` helpers
+handle composite-key dedup with the documented `${id}|${source}` fallback for
+items missing the `uniqueKey` field.
 
 ## 2. Read Project Infrastructure
 
@@ -74,6 +89,7 @@ For each new upstream item, classify it into one of these buckets:
 | Anthropic API SDK / docs | Relevant **only** if the project imports the SDK directly — skip otherwise |
 | Engineering blog | New patterns or best practices worth adopting; never blocking |
 | Status page | Informational only; no action required |
+| `sourceCategory: community` (Reddit, HN, Twitter/X, GitHub commits) | **Informational only — never direct-impact** unless an item explicitly names a project file. Per anthropic-watch's contract, community items are not suitable for autonomous-action triggers. |
 | Other sources | Classify by content — prefer informational unless it names something the project uses |
 
 ## 4. Report Format