Sync workspace skills with local updates: usage-report, graph, sensitive-scan

hypaware-core/plugins-workspace/claude/hypaware.plugin.json

@@ -37,6 +37,9 @@
       { "name": "hypaware-ignore", "clients": ["claude"] },
       { "name": "hypaware-unignore", "clients": ["claude"] },
       { "name": "hypaware-privacy", "clients": ["claude"] },
+      { "name": "hypaware-graph", "clients": ["claude"] },
+      { "name": "hypaware-sensitive-scan", "clients": ["claude"] },
+      { "name": "hypaware-ai-usage-report", "clients": ["claude"] },
       { "name": "hypaware-ai-adoption-report", "clients": ["claude"] },
       { "name": "hypaware-ai-improvement-report", "clients": ["claude"] },
       { "name": "hypaware-ai-security-report", "clients": ["claude"] },

hypaware-core/plugins-workspace/claude/skills/hypaware-ai-adoption-report/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: hypaware-ai-adoption-report
-description: AI Adoption Profile for a HypAware server: descriptive "who's using the fleet and how": per-gateway utilization (volume + focus: top models, tools, repos, themes) and parallelism/fan-out (multi-agent adoption, concurrency, main-vs-subagent split, payoff).
+description: "SUPERSEDED by hypaware-ai-usage-report (merged with the spend review, 2026-07-13) — invoke that skill instead unless the user explicitly asks for a standalone adoption profile. Original scope: AI Adoption Profile for a HypAware server: descriptive \"who's using the fleet and how\": per-gateway utilization (volume + focus: top models, tools, repos, themes) and parallelism/fan-out (multi-agent adoption, concurrency, main-vs-subagent split, payoff)."
 ---
 
 # AI Adoption Profile
@@ -23,13 +23,31 @@ list it once). Present the options,
 ask which one (or more) to profile, then proceed against the chosen source.
 
 **Descriptive only.** Route every *action* out: "fan out more/less" and tooling go to
-**hypaware-ai-improvement-report**, token waste to **hypaware-ai-spend-report**. Query mechanics
-live in the **hypaware-query** skill; reuse hypaware-ai-spend-report's token spine for
-any token figure. For descriptive who-used-what rollups (distinct sessions per
-repo/model/tool/file), prefer the **hypaware-graph** skill, which reads them from the projected
-graph instead of scanning messages; keep token figures on messages.
+**hypaware-ai-improvement-report**, token waste to **hypaware-ai-spend-report**. Reuse
+hypaware-ai-spend-report's token spine for any token figure. Query mechanics are step 0 below —
+a mandatory read, not a reference.
 
 ## Procedure
+0. **Load query mechanics BEFORE the first query — skills, not memory.** After the user picks a
+   source and before you run any `hyp query sql`, read the **hypaware-query** skill (invoke it or
+   Read its SKILL.md), and the **hypaware-graph** skill if `hyp query status` lists `node`/`edge`
+   datasets. Memory notes and recall of past runs do NOT substitute: stale notes have cost real
+   runs failed queries and server crashes (a phantom "100-row output cap"; message-table `cwd`
+   scans that 504'd and then OOM'd the prod server). Then route every question by shape, per
+   hypaware-query's "when the graph answers it cheaper" boundary:
+   - **Graph first (`node`/`edge` — tiny, join-safe) for every entity/connection question:**
+     which sessions used a repo/model/tool/file, skill and program rollups (these two exist ONLY
+     in the graph — SQL reconstructions disagree with the projection), client mix, co-occurrence,
+     and gateway→person attribution — take `min/max(session_id)` per gateway from messages (an
+     ID-only aggregate), then look those session_ids up in graph Session nodes (`props.cwd`,
+     `props.client_name`). **Never GROUP BY / DISTINCT / row-fetch wide content columns (`cwd`,
+     `content_text`) on the messages table at scale** — that is the query shape that kills servers.
+   - **Messages (`ai_gateway_messages`) only for per-message measures:** token sums, distinct
+     part/session counts, timestamps and ordering, `is_sidechain`/`agent_id`, content sampling.
+     Slice long windows into server-sized date ranges; capture stderr and check it even on
+     success (truncation and server-cap notices land there).
+   If you skipped this step and a query fails, the fix is to come back here — not to iterate on
+   the failing SQL.
 1. **Scope + coverage.** Distinct `gateway_id` (the unit; `user_id` is ~always null, so don't
    measure reach by it); window; coverage of `gateway_id`, token usage, and subagent provenance
    (`agent_id` / `is_sidechain` / `parent_thread_id`, transcript-enriched, may not survive

hypaware-core/plugins-workspace/claude/skills/hypaware-ai-improvement-report/SKILL.md

@@ -16,9 +16,7 @@ and let the user choose which to query: **local logs** (this machine's own recor
 `query_sql` / `graph_neighbors` tool in your toolset); the same server can appear both ways,
 list it once). Present the options,
 ask which one (or more) to run the review against, then proceed against the chosen source.
-Query mechanics live in the **hypaware-query** skill; read it first. For descriptive
-who-used-what rollups (distinct sessions per repo/model/tool/file), prefer the **hypaware-graph**
-skill: it reads relationships from the projected graph instead of scanning messages.
+Query mechanics are step 0 of the procedure — a mandatory read, not a reference.
 
 Focus on these signals:
 
@@ -31,6 +29,23 @@ Focus on these signals:
   subagent, a context-hygiene rule, a skill that avoids the redo).
 
 ## Procedure
+0. **Load query mechanics BEFORE the first query — skills, not memory.** After the user picks a
+   source and before any `hyp query sql`, read the **hypaware-query** skill (invoke it or Read
+   its SKILL.md), and the **hypaware-graph** skill if `hyp query status` lists `node`/`edge`
+   datasets. Memory notes from past runs do NOT substitute — stale notes have cost real runs
+   failed queries and server crashes (a phantom "100-row output cap"; message-table `cwd` scans
+   that 504'd then OOM'd the prod server). Route by shape, per hypaware-query's "when the graph
+   answers it cheaper" boundary: entity/connection questions go to the graph's tiny `node`/`edge`
+   tables — sessions per repo/model/tool/file, **skill and program rollups (graph-only facets —
+   SQL reconstructions measurably disagree with the projection)**, client mix, shared-file
+   clustering via `touched` edges, and gateway→person attribution (`min/max(session_id)` per
+   gateway from messages — an ID-only aggregate — then look those session_ids up in graph
+   Session nodes' `props.cwd`). The messages table is for per-message measures only — token
+   sums (the spend spine), `is_error`/retry loops, stop-reasons, ordering, prompt sampling —
+   date-sliced to server-sized ranges, and **never GROUP BY / DISTINCT / row-fetch wide content
+   columns (`cwd`, `content_text`) at scale** (that query shape kills servers). Capture stderr
+   and check it even on success — truncation and server-cap notices land there. If a query
+   fails, come back to this step; don't iterate on the failing SQL.
 1. **Footprint + basis.** Window; distinct contributors (`gateway_id`), repos, sessions;
    claude/codex mix. State N and breadth; flag if single-contributor.
 2. **Scan the signals for possible improvements.** Work the three signals above; each turns
@@ -67,26 +82,56 @@ Focus on these signals:
 
 ## Output - SAVE A SHORT MAIN FILE + ONE FILE PER SECTION
 A **progressively-disclosed one-pager** is the deliverable: a reader can stop after the thesis
-sentence, glance the key-numbers table, skim the findings, or follow any link into a detail
-**section**, and each section is its own markdown file. Build the one-pager top-to-bottom so each
-layer is shorter and more glanceable than the one it summarizes.
+sentence, skim the numbered change list, or follow any link into a detail **section**, and each
+section is its own markdown file. Build the one-pager top-to-bottom so each layer is shorter and
+more glanceable than the one it summarizes.
+
+**Report language (applies to every file).** The reader may be a supervisor with no HypAware
+knowledge. Plain literal language only: no pipeline vocabulary (ingest, sidechain, part,
+projection), no metaphors or report-coined shorthand ("marathon sessions" was flagged as vague -
+write "sessions kept open across days re-read their entire history each morning"); coined names
+(a harness, an internal tool) get a one-line gloss at first mention on each page; when a skill or
+tool is named as a fix, add one clause saying what it literally does ("`/handoff` writes a short
+end-of-day note of where the work stands so the next day starts a fresh session"), never just its
+name; absolute dates, never "last week". Findings equip, never direct: state who/size/driver/what
+a change returns, never "ask X" / "talk to Y". In section files, any list item carrying several
+facts is a bold topic line + 2-3 short sub-bullets, not a multi-sentence prose bullet.
 
 - **Main one-pager:** `hypaware-reports/<YYYY-MM-DD>-improvement-review.md` (create the dir if
-  needed). Dated so reviews accumulate. Lay it out in exactly these blocks, separated by `---` rules:
-  1. **Title + scope** - `# AI Improvement Review`, then a `## <server/fleet> · <window>` subtitle.
-  2. **Thesis** - ONE **bold** sentence: "Create/edit these N things and what it will improve."
-  3. **`### Key numbers`** - a small metric→readout table, ~4-6 rows, each one glanceable fact with
-     no link (# improvements, new-vs-edit split, the single biggest token prize, the basis:
-     gateways / sessions / repos). This is the ONLY table on the one-pager.
-  4. **`## What this shows`** - 3-5 numbered findings = the top improvements, highest-leverage
-     first; each is a `### N. <headline>` naming **what + its form** (skill / subagent / AGENTS.md
-     edit), followed by 2-3 plain-language sentences with the evidence and the **bold** token prize,
-     then a single `[<section> →](<dir>/<file>.md)` link on its own line. Show AGENTS.md edits as
-     real diffs/code blocks in their section file, not prose.
-  5. **`## Caveat`** - token prizes are floors and capture is partial, in plain language + a
-     `[caveats →]` link.
-  6. **`## Report details`** - a one-line footer linking **every** section file written this run
-     (not just the cited ones), so nothing is orphaned - e.g.
+  needed). Dated so reviews accumulate. It is a **terse bullet brief** (user feedback 2026-07-14:
+  dense multi-clause sentences and prose paragraphs were both rejected as hard to read). Its only
+  headings are **Proposed changes / Data limitations / Supporting analysis** - standard
+  business-report vocabulary, never coinages like "What this shows" / "Key numbers" / "Report
+  details", and no metrics or findings section (the evidence rides inside the change list). Blocks:
+  1. **Title + scope** - an eyebrow line `<server/fleet> · <window>`, then `# AI Improvement Review`.
+  2. **Thesis** - one SHORT bold sentence (the create/edit-these-N-things claim). If it needs
+     supporting clauses, put them in 2-3 plain sub-bullets under it, never packed into the sentence.
+  3. **`## Proposed changes`** - the changes themselves lead, NOT a metrics block, and there is
+     NO separate findings/evidence section (user feedback 2026-07-14: a Key findings section
+     alongside the change list is redundant - the strongest evidence rides with each change). A
+     **numbered list**, one item per improvement, highest-leverage first, each exactly:
+     - the **what**: a short bold imperative naming ONE action (mechanics in parens after the
+       bold), nothing else on the line. Never join two actions with ";" or "+" in the bold line
+       (user feedback: "sounds like two suggestions, unclear") - when a change pairs a skill
+       move with a companion AGENTS.md rule, the bold names the primary action and the companion
+       rides in a sub-bullet;
+     - sub-bullet 1, the **why**: one short sentence with the token prize or headline number;
+     - sub-bullet 2, the **evidence**: one short line with the 1-2 strongest supporting numbers,
+       ending with the section link.
+     Never pack what+why+prize into the bold line (rejected as too long). Close with one line
+     linking the ready-to-apply artifacts (which live in section files, not here). No tables on
+     the one-pager.
+     **Every proposed change ships its artifact in its section file** (user feedback 2026-07-14
+     - not only AGENTS.md diffs): AGENTS.md/CLAUDE.md edit → a real diff; new skill or subagent
+     → the full proposed file (frontmatter + body) in a code block, ready to save; move of an
+     existing artifact → concrete source → destination paths, flagging any machine-specific
+     content to review (if the source file lives on another machine, say so - name the move,
+     don't fake the file); tool/config change → the exact proposed text.
+  4. **`## Data limitations`** - ~3 bullets: the basis (gateways / sessions / window), token
+     prizes are floors, capture is partial, plus any window-specific data-quality incident + a
+     `[caveats]` link.
+  5. **`## Supporting analysis`** - a one-line footer linking **every** section file written this
+     run (not just the cited ones), so nothing is orphaned - e.g.
      `[basis](<dir>/basis.md) · [skill candidates](<dir>/skill-candidates.md) · [subagent candidates](<dir>/subagent-candidates.md) · [AGENTS.md edits](<dir>/agents-md-edits.md) · [efficiency → setup](<dir>/efficiency-setup.md) · [caveats](<dir>/caveats.md)`.
 - **Section files are analysis, not inventory.** Each detail section is its own `<dir>/<file>.md`, held to the same standard as the one-pager: it argues one claim, opens with that takeaway, and ties every number to what it means for the reader. A section file that is only a stat table has failed - fold it back into the one-pager rather than shipping it as a page. Cut table narration ("how to read the table") and standing bookkeeping prose; compress source/window/method to a few lines.
 - **No scope apologies (in any file).** Scope rules (what routes to which report) are authoring guidance, never report copy. Don't write "descriptive only", "no recommendations here", or routing disclaimers in the one-pager or any section file; state findings plainly, and where a sibling report owns the action a plain cross-link is enough.