@oneie/claude 0.6.0 → 0.8.0

package/hooks/scripts/task-complete-verify.sh

@@ -1,52 +1,58 @@
 #!/bin/bash
-# TASK-COMPLETE VERIFY — The W4 Gate
+# TASK-COMPLETE VERIFY — a READER, not a runner. Fires on TaskCompleted.
 #
-# Runs on TaskCompleted. Blocks task mark if tests regress.
-# This is the gate between signal and pheromone — prevents corruption.
+# WHAT IT USED TO DO, measured 2026-09-04: `cd "$CLAUDE_PROJECT_DIR" && bun run
+# verify`. The repo root has no package.json, so bun answered "Script not found",
+# EXIT was 1, and this hook — wired `blocking: true` on matcher `*` — printed
+# "W4 GATE BLOCKED: Verification failed" for EVERY task completion in every
+# session, over a suite that never ran (plus an `integer expression expected`
+# from parsing that output). A false red on every task is a gate nobody reads.
 #
-# Exit 0 = task marked (all checks pass)
-# Exit 1 = task blocked (tests regressed or type errors detected)
-# Emits hook:w4-verify:{ok,fail} signal per Rule 1 (see .claude/skills/signal.md).
+# And the version that "worked" would be worse. TaskCompleted fires per subagent
+# task, in every session; twelve sessions completing tasks is twelve full suites
+# — the N-agents-N-full-suites shape that thrashed this box on 2026-08-18
+# (load 57, swap full, 18-minute gates). text/factory-do.md § Deploy is the ship
+# gate names this hook as "one file away from running the full suite on every
+# task completion", and the fix is not a governed run — it is that this hook
+# does not run a suite at all. The suite has owners: W4 runs `verify:fast`
+# through the governor and the memo; /close and ./deploy run the full lane.
+#
+# WHAT IT DOES NOW — two deterministic reads, milliseconds, no gate:
+#   1. the deferred-pin ledger: an outstanding debt on `main` means a plan
+#      landed without reaching its close gate. Named, never paid here.
+#   2. the governor: a slot held by a DEAD pid is an orphaned gate. Named.
+# Both are reports. Neither blocks — a task is not the place to pay a plan's
+# debt, and a hook that blocks on a neighbour's orphan punishes the wrong
+# session. Exit 0 always, with the facts in the signal.
+#
+# Emits hook:w4-verify:{ok,debt,orphan} per Rule 1 (see .claude/skills/signal.md).
 
 # shellcheck source=lib/signal.sh
 source "$CLAUDE_PROJECT_DIR/.claude/hooks/lib/signal.sh"
 
-cd "$CLAUDE_PROJECT_DIR" || exit 1
-
-# Run the full verify suite
-RESULT=$(bun run verify 2>&1)
-EXIT=$?
-
-# Extract test counts (used in both branches for the signal payload)
-PASSED=$(echo "$RESULT" | grep -o '[0-9]* pass' | head -1 | awk '{print $1}')
-FAILED=$(echo "$RESULT" | grep -o '[0-9]* fail' | head -1 | awk '{print $1}')
-ERRORS=$(echo "$RESULT" | grep -c "error TS" || echo "0")
+DEBT_FILE="${VERIFY_FAST_DEBT_FILE:-${TMPDIR:-/tmp}/one-verify-fast-debt}"
+GOVERN_DIR="${GOVERN_DIR:-${TMPDIR:-/tmp}/one-govern}"
 
-if [ $EXIT -eq 0 ]; then
-  # All checks passed — mark with deterministic receipts (Rule 3)
-  emit_signal "hook:w4-verify:ok" 1 "passed=${PASSED:-0} failed=0 errors=0"
-  exit 0
+notes=""
+if [ -s "$DEBT_FILE" ]; then
+  n=$(wc -l < "$DEBT_FILE" | tr -d ' ')
+  br=$(git -C "$CLAUDE_PROJECT_DIR" branch --show-current 2>/dev/null || echo "?")
+  echo "verify: $n deferred pin run(s) owed (branch $br) — paid by a GREEN full lane at /close or ./deploy, never here" >&2
+  emit_signal "hook:w4-verify:debt" 0 "deferred_pins=$n branch=$br"
+  notes="debt=$n"
 fi
 
-# Verify failed — extract details
-echo "W4 GATE BLOCKED: Verification failed" >&2
-echo "" >&2
-
-if [ -n "$FAILED" ] && [ "$FAILED" -gt 0 ]; then
-  echo "Tests: $FAILED failed" >&2
-fi
-if [ "$ERRORS" -gt 0 ]; then
-  echo "TypeScript: $ERRORS type errors" >&2
+orphans=0
+for d in "$GOVERN_DIR"/lock-slot-*; do
+  [ -d "$d" ] || continue
+  pid=$(cat "$d/pid" 2>/dev/null)
+  [ -n "$pid" ] && ! kill -0 "$pid" 2>/dev/null && orphans=$((orphans + 1))
+done
+if [ "$orphans" -gt 0 ]; then
+  echo "verify: $orphans governor slot(s) held by a dead pid — reaped on the next contender; \`bash .claude/scripts/gate-reaper.sh --dry-run\` to see them" >&2
+  emit_signal "hook:w4-verify:orphan" 0 "stale_slots=$orphans"
+  notes="${notes:+$notes }orphans=$orphans"
 fi
 
-# Show last 15 lines of output for context
-echo "" >&2
-echo "Last output:" >&2
-echo "$RESULT" | tail -15 >&2
-echo "" >&2
-echo "Fix baseline before marking task done." >&2
-
-# Full warn — tests actually regressed, agent produced nothing usable
-emit_signal "hook:w4-verify:fail" -1 "passed=${PASSED:-0} failed=${FAILED:-0} errors=${ERRORS:-0}"
-
-exit 1
+[ -z "$notes" ] && emit_signal "hook:w4-verify:ok" 1 "reader: no debt, no orphaned slot"
+exit 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oneie/claude",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "ONE Claude Code plugin — /do lifecycle, W0-W4 BUILD engine, 7-canon reconcile, ONE substrate via MCP, signals, and rules",
   "files": [
     ".claude-plugin",

package/rules/api.md

@@ -45,6 +45,15 @@ The `>` separator works as a fallback to `→`. Always pass `{ strength }` in th
 
 Active state (saved, archived, completed) belongs on the pheromone path, not in `localStorage`. Poll `/api/export/highways?from=source&limit=200` and classify by strength/resistance thresholds. This keeps state honest across devices.
 
+## Authorize off the context, never the body
+
+Scope every read and write to `ctx.ownerSlug`. A `slug`, `actorId`, `gid`, or
+`workspace` arriving in the request body or query string is **caller-supplied
+input, not identity** — trusting one is an IDOR, and this family has had ~80 of
+them fixed. A `?slug=` route must call `authorizeWorkspace` before it touches
+data. Ownership questions resolve by the authority walk (`schema/roles.tql`),
+not by comparing a body field to anything.
+
 ## No stubs
 
 Do not create a no-op endpoint (one that always returns `[]` or `{ok:true}`) as a placeholder. If the backend isn't ready, the caller handles the empty response from `signal`/`ask`.

package/rules/design.md

@@ -203,11 +203,21 @@ Three layers, all automatic:
 2. **PostToolUse hook** — `.claude/hooks/design-check.sh` greps every Write/Edit
    to `one.ie/web/**/*.{tsx,astro,css}` for banned patterns. Exit 2 on violation feeds
    the diff back to Claude as a tool error; the model self-corrects next turn.
-3. **This rule** — auto-loaded on the same files via `.claude/settings.json`,
-   so the constraints are in context before the first character is written.
+3. **This rule** — auto-loaded on the same files via the `paths:` frontmatter at
+   the top of this file (not `settings.json`, which wires hooks only), so the
+   constraints are in context before the first character is written.
 
 The hook allowlists `Layout.astro` (token source) and `design.astro` (showcase).
-There is no opt-out for other files.
+
+**Layers 2 and 3 are edit-triggered, so pre-existing violations survive.** The
+hook is PostToolUse: it only sees a file when that file is written. Nothing
+sweeps the tree, and layer 1 structurally cannot catch a hex string inside a JS
+object — it nulls Tailwind palette *classes*, not literals. So a file untouched
+since this rule landed can carry banned patterns indefinitely.
+`src/components/paths/PathGraph.tsx` did: it carried hex literals at lines 27,
+28, 29 and 55 until they were swept to `var(--color-{success,secondary,destructive})`.
+Treat "the hook is green" as "nobody has edited the offender", not as "the tree
+is clean".
 
 ---
 

package/rules/documentation.md

@@ -1,3 +1,12 @@
+---
+paths:
+  - "text/**/*.md"
+  - "**/*-todo.md"
+  - "**/*-plan.md"
+  - "**/*-docs.md"
+  - ".claude/commands/do*.md"
+---
+
 # Documentation Rules
 
 Apply to all TODOs and `/do` workflows.
@@ -8,6 +17,25 @@ Apply to all TODOs and `/do` workflows.
 
 Within a build cycle this still maps to three phases: **W2** declares which docs this cycle touches (the spec already exists; W2 lists the deltas), **W3** edits docs alongside code in the same wave, **W4** verifies consistency *and truth* against the shipped behaviour. The difference from before: the full doc set is not seeded-then-refined — it is written for real up front, and the cycle keeps it in sync and proves it true.
 
+## Promises grow with delivery (always update the promise with what shipped)
+
+**When you ship a feature that extends an already-kept promise — a new view, capability, or surface under the same banner — you MUST append it to that promise as a new `deliverable:` with its own `accept:` check, and extend the `proof:` `&&`-join to include that check.** This is not optional polish; it is what keeps the promise a record the system can depend on. A promise that silently omits shipped work is a promise that lies about the delivery, and the router that sells the next signal to the proven path is reading a stale contract.
+
+The covenant's freeze (clause 4, `text/promises.md`) permits this because it is a **monotonic ratchet** — the same "can't regress" DNA `/do` runs on:
+
+- **Allowed (do it every time):** append a deliverable whose `accept:` is **already green**, and add that exact `accept:` string to `proof:`. The join stays exit-0; the record only rises. No new `terms_hash` needed — nothing that was promised changed.
+- **Forbidden (needs a *new* promise):** anything that would make the existing proof go **red** — weakening a check, removing a line, reversing a decision, or a broken `assumes:`. That's a regression, not growth.
+
+Checklist when extending a kept promise `text/<slug>.md`:
+
+1. Add the `- item:` + `accept:` row under `deliverables:` (group fulfilled follow-ons under a dated comment).
+2. Append the identical `accept:` body to `proof:` (the schedule ⊆ proof law — `do-promise-lint.sh` enforces verbatim inclusion).
+3. Add any new `world:` entries (a new view → `views:`, a new workflow step → `workflow:`).
+4. Add the human-readable row to the deliverables table in the prose, and reconcile any now-stale status claim (e.g. an "X is still red / not shipped" line for the thing you just shipped).
+5. Run `bash .claude/scripts/do-promise-lint.sh <slug>` — it must report `schedule ⊆ proof, contract well-formed` **and** every `assumes:` green. Fix any stale `assumes:` path while you're there (a moved file makes the whole contract un-signable).
+
+The same discipline applies to the propagate matrix below: the promise is the first row every close reconciles, before its derived docs.
+
 **Format:** any ASCII diagram written into a doc follows `text/CLAUDE.md § ASCII diagrams` — max ~60 chars wide, vertical flow over multi-column tables. A diagram that's fine in a wide terminal wraps into garbage in the narrow panels these docs actually get read in.
 
 ---
@@ -106,79 +134,12 @@ These six docs are the **source of truth** and must stay in sync with code:
 | **one-ontology.md** | 6 dimensions, actor/group/thing/path/signal/hypothesis | Type system changes |
 | **routing.md** | L1-L7 loops, signal flow, priority formula | Loop/routing changes |
 | **lifecycle.md** | Agent journey stages, revenue flow | Lifecycle/economic changes |
-| **rubrics.md** | Code rubric (security/stability/simplicity/integration/speed) + agent rubric (fit/form/truth/taste) | Rubric changes or new dimensions |
+| **rubrics.md** | Code rubric (the design target — eight dims) + agent rubric (fit/form/truth/taste). Live weights are data at `.claude/scripts/rubric-weights.json`; the gap between the two is `text/rubric-migration-plan.md` | Rubric changes or new dimensions |
 
 **Feature-specific docs** (rich-messages.md, webhooks.md, etc.) are updated per feature. Always link back to the six core docs.
 
 ---
 
-## The Workflow Integration
-
-### Hook: Pre-W2 — Load Source Docs
-
-When a TODO is created, auto-load relevant source docs:
-
-```
-/do {name}-todo.md
-├─ [Hook] Load: dictionary.md, DSL.md, rubrics.md
-├─ [W1] Recon code (reads files)
-├─ [W2] Decide code + **document changes needed in docs**
-│       (explicit list: what terms change, what loops change, what's new)
-├─ [W3] Edit code (spawns Sonnet agents)
-│       + [Hook] Suggest: "Also edit X doc for {Y change}"
-└─ [W4] Verify code + **verify docs match** (cross-check task)
-```
-
-### Hook: Post-W4 — Validate Doc Consistency
-
-After W4 completes, auto-run consistency checks:
-
-```bash
-# Terminology consistency
-grep -r "old-term" text/ | flag if > 0 (not on deadname list)
-
-# Cross-references
-markdown-link-check text/*.md
-
-# Metaphor alignment (if touching signal/path semantics)
-grep -l "signal\|strength\|resistance" src/changed-files.txt | xargs -I {} \
-  check if metaphors.md still applies
-
-# Rubric scoring (if W4 added dimensions)
-grep "rubric\|dimension" src/changed-files.txt | flag for rubrics.md review
-```
-
----
-
-## Example: rich-messages-todo (Retrospective)
-
-**What should have happened (W2):**
-
-```markdown
-### Documentation Updates (W2)
-
-**New docs:**
-- None (extends existing types)
-
-**Docs modified:**
-- `text/dictionary.md` — add "Rich Messages" section, explain `data.rich` convention
-- `text/rich-messages.md` — add PaymentMetadata type, Payment flow section
-- `text/template-todo.md` — add "Documentation Updates (W2 + W4)" section
-
-**Schema changes:**
-- `nanoclaw/src/types.ts` — RichMessage.thread, RichMessage.payment added (Cycle 1 & 3)
-- `migrations/0010_payment_columns.sql` — new D1 columns for payment tracking
-```
-
-**What actually happened:**
-
-- ✅ Docs updated (rich-messages.md, dictionary.md, template-todo.md) — **AFTER W4**
-- ⚠️ Should have been planned in W2, preventing surprises in W3
-
-**Lesson:** Next TODO follows: document in W2, edit in W3, verify in W4. No surprises.
-
----
-
 ## Rules for `/do` (The Command)
 
 When running `/do {name}-todo.md`, the workflow enforces:
@@ -186,7 +147,7 @@ When running `/do {name}-todo.md`, the workflow enforces:
 1. **W2 must explicitly call out doc changes** — no surprise doc edits in W3
 2. **W3 spawns edit agents for both code AND docs** — parallel edits
 3. **W4 includes doc consistency check** — not just code tests
-4. **The code rubric (security/stability/simplicity/integration/speed) applies to docs too** — simplicity means fewer words; stability means no broken links; security means no sensitive data exposed; integration means every doc is linked from its family and lies about nothing shipped; speed means lean docs = fewer tokens to read
+4. **The code rubric applies to docs too**, reading each axis for prose — simplicity means fewer words; stability means no broken links and accurate references; security means no sensitive data exposed; integration means every doc is linked from its family and lies about nothing shipped; speed means lean docs = fewer tokens to read. (Axis names and weights: `.claude/scripts/rubric-weights.json`. Note the doc reading of *stability* — links and references — is not the code reading — error handling and closed loops; same name, two criteria, which is exactly why the eight-dim migration splits it.)
 
 ---
 
@@ -200,6 +161,8 @@ When running `/do {name}-todo.md`, the workflow enforces:
 
 | Trigger (detected from W3 diff) | Target doc | Edit |
 |---|---|---|
+| feature extends an already-kept promise | that `text/<slug>.md` promise | **first row, always** — append the fulfilled deliverable + its green `accept:`, extend `proof:`, add `world:` entries, then `do-promise-lint.sh <slug>` must pass (see § Promises grow with delivery) |
+| slug has `text/<slug>-agents.md` (a verification walk exists) | `.claude/scripts/do-walk.sh <slug> --agents` | run it — must exit 0; a promise extension that added a deliverable but no matching walk stop is an incomplete close, append the stop to both `-humans.md` and `-agents.md` before the cycle closes |
 | any change | source-of-truth doc(s) from plan frontmatter | always — even if only touch-verified |
 | 6-dim, L1-L8, or locked-rule change | root `CLAUDE.md` | edit the relevant section |
 | directory contract change (new component family, new pattern) | nearest `CLAUDE.md` (e.g., `one.ie/web/src/components/CLAUDE.md`) | append / edit section |
@@ -212,7 +175,12 @@ Anchor mismatch → log to `text/improvements.md` for manual W2 next cycle (no h
 **Learnings entry** (append to `text/learnings.md` on each close):
 
 ```
-- YYYY-MM-DD · cycle N · wave N|gate · {one sentence} · rubric=0.NN · source=w1|w2|w3|w4|cycle
+- YYYY-MM-DD · cycle N · wave N|gate · {one sentence} · rubric=0.NN [sec.NN simp.NN struct.NN speed.NN integ.NN reuse.NN test.NN ux.NN] · source=w1|w2|w3|w4|cycle
+
+The `[...]` eight-field vector is self-labeling and appended, never replacing the
+composite — see `text/rubrics.md` § Code Rubric for the eight dimensions and the
+per-field scoring rules. A close with no per-dimension breakdown to hand may omit
+the vector (old form still parses; counts toward the composite trend only).
 ```
 
 W4 code rubric applies to docs too: security (no sensitive data), stability (no broken links, accurate references), simplicity (fewer words, no bloat), speed (lean = fewer tokens to read).
@@ -222,7 +190,7 @@ W4 code rubric applies to docs too: security (no sensitive data), stability (no
 W4 must pass four bash checks before the rubric runs. Detail in `.claude/commands/do.md` W4 section. Summary:
 
 1. **stale-name check** — every old identifier in W3's rename list has 0 hits in `**/*.md`
-2. **broken-link check** — `markdown-link-check` on every touched doc returns 0 broken
+2. **broken-link check** — `markdown-link-check` on every touched doc returns 0 broken. **It is not installed** (`command -v markdown-link-check` → nothing), so this check cannot pass today. Report it `n/a`, never `ok` — an absent tool is an unrun check, not a green one. Install it or replace it with a resolve-every-relative-link grep; do not let it silently vanish.
 3. **contract-staleness check** — every dir whose code was touched has `CLAUDE.md` mtime ≥ newest code mtime
 4. **shipped-status check** — the just-built slug's own `text/<slug>-plan.md` / `-docs.md` must not still claim the feature is unbuilt:
    ```bash

package/rules/engine.md

@@ -120,7 +120,14 @@ world.restore(snapshot)     // rehydrate
 ```
 
 Over HTTP the same verbs are `SubstrateClient` methods (`packages/sdk/src/client.ts`).
-`harden` is exposed via `signal("learning:know")`.
+
+`harden` is the one verb with **no general wire**. `learning:know` is in no
+registry (`grep -c "learning:" packages/sdk/src/receivers.ts` → 0) and has no
+resolver; `client.know()` is `@deprecated` and returns `{}`. The only shipped
+harden receiver is **`chat:harden`** (`one.ie/web/src/lib/resolvers/entity.ts:566`),
+which crystallises a resolved chat thread into a dim-6 learning and requires an
+`entityId` — so it does not cover free-standing claims. Do not write
+`signal("learning:know")` into new code or docs; it fails silently.
 
 **Promise paths.** `promise:<slug>→proof` is a first-class weighted path
 family. At close, `.claude/scripts/do-promise-settle.sh` re-runs the

package/rules/ui.md

@@ -35,8 +35,12 @@ Receiver naming: `ui:<surface>:<action>` where surface is the component or page
 | `settings` | close, save, reset | `ui:settings:close`, `ui:settings:save` |
 | `memory` | reveal, forget, expand | `ui:memory:reveal`, `ui:memory:forget` |
 | `demo` | run, reset, next | `ui:demo:run`, `ui:demo:reset` |
+| `in:space` / `in:view` | the inbox axes — select, open | `ui:in:space:select`, `ui:in:view:open` |
+| `switcher` | group switching | `ui:switcher:open`, `ui:switcher:select` |
+| `members` | add, remove, delegate | `ui:members:add`, `ui:members:delegate` |
 
-Format: `ui:<surface>:<action>` — all lowercase, colon-delimited.
+Format: `ui:<surface>:<action>` — all lowercase, colon-delimited. A surface may
+nest (`in:space`), but the action is always the last segment.
 
 ---
 

package/scripts/agentverse-audit.sh

@@ -0,0 +1,256 @@
+#!/usr/bin/env bash
+# agentverse-audit.sh — measure the health and composition of the Agentverse
+# agent directory.
+#
+# This is an AUDIT, not an exposé. It reports what is measurable and states what
+# it cannot know. Every number is reproducible by anyone holding an Agentverse
+# API key, including Fetch — that is the design. An accusation is deniable;
+# arithmetic is not.
+#
+# WHAT IT MEASURES
+#   Liveness     status, unresponsive flag, total vs RECENT interactions
+#   Quality      description, readme, declared protocols, rating
+#   Composition  owner concentration, generated-name clustering, categories
+#   Time         creation year, staleness of last update
+#
+# WHAT IT DELIBERATELY DOES NOT CLAIM
+#   - That any published agent count is wrong. Registered is not the same as
+#     active, and this measures ACTIVITY and COMPOSITION. Both can be true.
+#   - That bulk-created agents are illegitimate. Generating one agent per entry
+#     in a catalogue is a normal integration pattern. Clustering is REPORTED so a
+#     reader can judge what a headline count represents — not as an allegation.
+#   - That anyone acted in bad faith. Dormancy is normal in every registry: npm,
+#     the App Store and GitHub all look like this.
+#   - That the sample is uniformly random. It is not, and cannot be. See LIMITS.
+#
+# LIMITS — read before quoting any number
+#   1. SEARCH-BIASED SAMPLE. Agents come from POST /v1/search/agents, ranked by
+#      relevancy. No enumeration endpoint is exposed, so a uniform random sample
+#      is impossible. Many unrelated queries plus deep pagination reduce the skew;
+#      nothing removes it.
+#   2. THEIR FIELDS, NOT OURS. `status`, `rating` and the interaction counters are
+#      what the API returns. Their definitions are unpublished, so this measures
+#      "what Agentverse says about its own agents" — the honest framing.
+#   3. DUPLICATES ARE REAL. The directory returns the same agent repeatedly; this
+#      dedupes by address before counting.
+#   4. A SAMPLE IS NOT A CENSUS. Every figure is "of agents sampled".
+#   5. OWNER IDS ARE OPAQUE. One owner id is one account, which is not
+#      necessarily one person or one company.
+#
+# Usage:
+#   agentverse-audit.sh                # default depth, human report
+#   agentverse-audit.sh --json         # machine-readable receipt
+#   agentverse-audit.sh --pages 4      # pages per query (50 agents each)
+#   agentverse-audit.sh --self-test    # prove the counters can report health
+#
+# Env:
+#   AGENTVERSE_API_KEY  required. Absent → exit 3 (could not run), never a
+#                       fabricated zero.
+set -uo pipefail
+
+BASE="${AGENTVERSE_BASE:-https://agentverse.ai/v1}"
+LIMIT=50           # API hard-caps at 50
+PAGES=3
+JSON=0
+SELFTEST=0
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --json) JSON=1; shift ;;
+    --pages) PAGES="${2:-3}"; shift 2 ;;
+    --self-test) SELFTEST=1; shift ;;
+    -h|--help) sed -n '2,48p' "${BASH_SOURCE[0]}"; exit 0 ;;
+    *) echo "agentverse-audit: unknown flag $1" >&2; exit 2 ;;
+  esac
+done
+
+# Fixed probe set, spread across verticals rather than clustered in one. Fixed in
+# the script so a run is reproducible — hand-picking queries per run would let
+# anyone tune the result.
+QUERIES=(
+  agent data trading assistant payment finance search weather
+  news health travel game nft defi oracle chat image translate
+  storage compute music legal research market social crypto
+  bot llm model tool
+)
+
+if [[ $SELFTEST -eq 1 ]]; then
+  echo "agentverse-audit --self-test"
+  out=$(python3 - <<'PY'
+# A counter that cannot report a HEALTHY directory is theatre. Feed the reducer a
+# synthetic all-healthy, all-distinct-owner set and confirm it says so.
+agents = [{"address": f"a{i}", "status": "active", "type": "mailbox",
+           "total_interactions": 5, "recent_interactions": 2, "rating": 4.5,
+           "description": "d", "readme": "r", "protocols": ["p"],
+           "owner": f"owner{i}", "unresponsive": False} for i in range(10)]
+n = len(agents)
+active = sum(1 for a in agents if a["status"] == "active")
+rated  = sum(1 for a in agents if (a.get("rating") or 0) > 0)
+protos = sum(1 for a in agents if a.get("protocols"))
+owners = len({a["owner"] for a in agents})
+print(f"{active}/{n} {rated}/{n} {protos}/{n} owners={owners}")
+PY
+)
+  if [[ "$out" == "10/10 10/10 10/10 owners=10" ]]; then
+    echo "  ok   a healthy directory reports 100% and 10 distinct owners"
+    echo "       (the counters are not hardcoded to a pessimistic answer)"
+    exit 0
+  fi
+  echo "  BAD  reducer returned '$out'"; exit 1
+fi
+
+if [[ -z "${AGENTVERSE_API_KEY:-}" ]]; then
+  echo "agentverse-audit: AGENTVERSE_API_KEY unset — cannot run." >&2
+  echo "  An unrun audit is not an audit reporting zero. Exiting 3." >&2
+  exit 3
+fi
+
+RAW="$(mktemp)"; trap 'rm -f "$RAW"' EXIT
+nreq=0
+for q in "${QUERIES[@]}"; do
+  for ((p=0; p<PAGES; p++)); do
+    off=$((p * LIMIT))
+    body="$(printf '{"search_text":"%s","sort":"relevancy","direction":"asc","offset":%d,"limit":%d}' "$q" "$off" "$LIMIT")"
+    resp="$(curl -s -m 30 -X POST \
+        -H "Authorization: Bearer ${AGENTVERSE_API_KEY}" \
+        -H 'Content-Type: application/json' \
+        -d "$body" "$BASE/search/agents" 2>/dev/null)"
+    printf '%s\t%s\n' "$q" "$resp" >> "$RAW"
+    nreq=$((nreq+1))
+    sleep 0.35   # polite: this is their infrastructure
+  done
+done
+
+python3 - "$RAW" "$nreq" "$JSON" <<'PY'
+import json, re, sys
+from collections import Counter
+from datetime import datetime, timezone
+
+raw, nreq, as_json = sys.argv[1], int(sys.argv[2]), sys.argv[3] == "1"
+
+seen, agents, failed = set(), [], 0
+for line in open(raw, encoding="utf-8"):
+    _, _, payload = line.partition("\t")
+    try:
+        d = json.loads(payload)
+    except Exception:
+        failed += 1; continue
+    if not isinstance(d, dict) or "agents" not in d:
+        failed += 1; continue
+    for a in d.get("agents") or []:
+        addr = a.get("address")
+        if not addr or addr in seen:
+            continue
+        seen.add(addr); agents.append(a)
+
+n = len(agents)
+if n == 0:
+    print("agentverse-audit: no agents returned — cannot report. exit 3", file=sys.stderr)
+    sys.exit(3)
+
+def pct(k): return round(100.0 * k / n, 1)
+def yr(s):
+    try: return int(str(s)[:4])
+    except Exception: return None
+
+active   = sum(1 for a in agents if a.get("status") == "active")
+unresp   = sum(1 for a in agents if a.get("unresponsive"))
+ever     = sum(1 for a in agents if (a.get("total_interactions") or 0) > 0)
+recent   = sum(1 for a in agents if (a.get("recent_interactions") or 0) > 0)
+rated    = sum(1 for a in agents if (a.get("rating") or 0) > 0)
+desc     = sum(1 for a in agents if (a.get("description") or "").strip())
+readme   = sum(1 for a in agents if (a.get("readme") or "").strip())
+protos   = sum(1 for a in agents if a.get("protocols"))
+featured = sum(1 for a in agents if a.get("featured"))
+
+owners = Counter(a.get("owner") or "unknown" for a in agents)
+top10 = owners.most_common(10)
+top10_share = round(100.0 * sum(c for _, c in top10) / n, 1)
+top1_share = round(100.0 * top10[0][1] / n, 1) if top10 else 0.0
+
+# Agents minted in bulk share a stem: "hf-info-<model>", "test-bot-<n>". Strip a
+# trailing id/hash and count stems. REPORTED, not alleged — a catalogue
+# integration is legitimate; the reader decides what a headline count represents.
+def stem(name: str) -> str:
+    s = re.sub(r'[-_][0-9a-fA-F]{6,}$', '', name or '')
+    s = re.sub(r'[-_]\d+$', '', s)
+    parts = re.split(r'[-_\s]+', s)
+    return '-'.join(parts[:2]).lower() if len(parts) >= 2 else s.lower()
+
+stems = Counter(stem(a.get("name") or "") for a in agents)
+big_stems = [(s, c) for s, c in stems.most_common(10) if c >= 3]
+clustered = sum(c for _, c in stems.items() if c >= 3)
+
+years = Counter(y for y in (yr(a.get("created_at")) for a in agents) if y)
+now = datetime.now(timezone.utc)
+stale = 0
+for a in agents:
+    try:
+        d = datetime.fromisoformat(str(a.get("last_updated")).replace("Z", "+00:00"))
+        if (now - d).days > 180: stale += 1
+    except Exception:
+        pass
+
+cats  = Counter(a.get("category") or "none" for a in agents)
+types = Counter(a.get("type") or "unknown" for a in agents)
+
+result = {
+    "sampled": n, "requests": nreq, "failed_requests": failed,
+    "liveness": {"active": active, "active_pct": pct(active),
+                 "unresponsive": unresp,
+                 "ever_interacted": ever, "ever_interacted_pct": pct(ever),
+                 "recently_interacted": recent, "recently_interacted_pct": pct(recent)},
+    "quality": {"rated": rated, "rated_pct": pct(rated),
+                "has_description": desc, "has_description_pct": pct(desc),
+                "has_readme": readme, "has_readme_pct": pct(readme),
+                "declares_protocols": protos, "declares_protocols_pct": pct(protos),
+                "featured": featured},
+    "composition": {"distinct_owners": len(owners),
+                    "top_owner_share_pct": top1_share,
+                    "top10_owner_share_pct": top10_share,
+                    "top_owners": [{"owner": o[:12] + "…", "agents": c} for o, c in top10],
+                    "name_clustered_agents": clustered,
+                    "name_clustered_pct": pct(clustered),
+                    "top_name_stems": [{"stem": s, "agents": c} for s, c in big_stems]},
+    "time": {"created_by_year": dict(sorted(years.items())),
+             "not_updated_in_180d": stale, "not_updated_in_180d_pct": pct(stale)},
+    "types": dict(types), "categories": dict(cats.most_common(6)),
+}
+
+if as_json:
+    print(json.dumps(result, indent=2)); sys.exit(0)
+
+print(f"Agentverse directory audit — {n} unique agents from {nreq} requests")
+if failed: print(f"  NOTE {failed} request(s) returned no usable payload")
+print()
+print("LIVENESS")
+print(f"  active                  {active:>5} / {n}   {pct(active):>5}%")
+print(f"  ever interacted with    {ever:>5} / {n}   {pct(ever):>5}%")
+print(f"  RECENTLY interacted     {recent:>5} / {n}   {pct(recent):>5}%")
+print(f"  flagged unresponsive    {unresp:>5}")
+print()
+print("QUALITY")
+print(f"  carries a rating        {rated:>5} / {n}   {pct(rated):>5}%")
+print(f"  declares a protocol     {protos:>5} / {n}   {pct(protos):>5}%")
+print(f"  has a description       {desc:>5} / {n}   {pct(desc):>5}%")
+print(f"  has a readme            {readme:>5} / {n}   {pct(readme):>5}%")
+print()
+print("COMPOSITION")
+print(f"  distinct owners         {len(owners):>5}  for {n} agents")
+print(f"  largest owner holds     {top1_share:>5}% of the sample")
+print(f"  top 10 owners hold      {top10_share:>5}%")
+print(f"  in a name cluster (>=3) {clustered:>5} / {n}   {pct(clustered):>5}%")
+for s, c in big_stems[:5]:
+    print(f"      {s:<28} {c:>4}")
+print()
+print("TIME")
+print(f"  created by year         {dict(sorted(years.items()))}")
+print(f"  not updated in 180d     {stale:>5} / {n}   {pct(stale):>5}%")
+print()
+print(f"  types {dict(types)}")
+print()
+print("  Reproduce: bash .claude/scripts/agentverse-audit.sh --json")
+print("  SEARCH-BIASED SAMPLE, not a census. Fields are Agentverse's own.")
+print("  Registered is not the same as active — both can be true at once.")
+print("  Bulk-created agents are a normal integration pattern, not an allegation.")
+PY