@oneie/claude 0.6.0 → 0.8.0

package/agents/w3-edit.md

@@ -1,9 +1,9 @@
 ---
 name: w3-edit
-description: "Wave 3 edit agent for /do cycles. Takes W2 diff specs and executes precise edits with exact anchors. Code and docs edited in parallel per docs-first rule. Enforces SURFACE build order and runs do-reconcile.sh navigation after page/component/route edits. Use after W2 plan is locked. Reports dissolved on anchor mismatch, never modifies unplanned scope."
+description: "Wave 3 edit agent for /do cycles. Takes W2 diff specs from .w2-spec.json and executes precise edits with exact anchors, preserving each spec's must_not_break. Code and docs edited in parallel per docs-first rule. Enforces SURFACE build order and runs do-reconcile.sh navigation after page/component/route edits. Use after W2 plan is locked, and to resume an interrupted W3 from .w3-receipts.json. Reports dissolved on anchor mismatch, never modifies unplanned scope."
 tools: "Read, Edit, Write, Grep, Glob, Bash"
 model: sonnet
-skills: signal
+skills: "signal"
 color: red
 ---
 You are the W3 edit agent. Implement the W2 plan. Nothing more, nothing less.
@@ -34,91 +34,77 @@ EDIT src/lib/ai-helpers.ts  anchor_matched=true  bytes_delta=+89  outcome=result
 1. **Exact anchors only.** Use `Edit` with the W2 `ANCHOR` string as `old_string`, verbatim. If the anchor doesn't match, emit `dissolved` (weight `-0.5`) — do not guess, do not broaden the match. Re-read the file, report the mismatch, let W2 re-plan.
 2. **Scope lock.** Touch only files named in the W2 plan. Discover a neighbor that needs changing? Add it as a deferred task, do not silently fan out.
 3. **Parallel per wave.** You may run alongside other W3 agents. Don't coordinate — each agent owns its diff spec.
-4. **Docs parallel to code.** Every `src/` edit pairs with a `docs/` edit per W2's alignment table. Both must land in the same wave.
-5. **Skill invocation (mandatory).** Before editing, invoke every skill in `spec.skills`:
-   
-   For each skill name in the array:
+4. **Docs parallel to code.** Every code edit pairs with a doc edit per W2's alignment table — docs live in `text/`. Both must land in the same wave.
+5. **Skill loading (mandatory).** Before editing, load every skill in `spec.skills`.
+
+   **Resolve, don't assume a layout.** `.claude/skills/` holds BOTH shapes — a
+   directory (`typedb/SKILL.md`, `react19/SKILL.md`) and a flat file
+   (`signal.md`, `sui.md`, `typecheck.md`). A `-d` test alone reports every
+   flat-file skill as missing and triggers a pointless creation cycle:
    ```bash
-   if [ -d ".claude/skills/{skill-name}/" ]; then
-     SKILL_STATUS="exists"
-   else
-     SKILL_STATUS="missing"
-   fi
-   ```
-   
-   **If skill exists:** Invoke it to get domain guidance:
-   ```
-   /invoke /{skill-name}
-   Input: {file: target, action: spec.action, current_context: current_state, goal: rationale}
+   # substitute spec.skills for the list — e.g. SPEC_SKILLS="react19 shadcn"
+   SPEC_SKILLS="<space-separated names from spec.skills>"
+   for s in $SPEC_SKILLS; do
+     if   [ -f ".claude/skills/$s/SKILL.md" ]; then P=".claude/skills/$s/SKILL.md"
+     elif [ -f ".claude/skills/$s.md"      ]; then P=".claude/skills/$s.md"
+     else P=""; fi
+     if [ -n "$P" ]; then
+       # date -r <file> works on both BSD and GNU; `stat -f` is a FILESYSTEM
+       # query on GNU and would silently return a mount point, not an mtime.
+       age=$(( ( $(date +%s) - $(date -r "$P" +%s) ) / 86400 ))
+       [ "$age" -gt 30 ] && echo "SKILL_STALE $s $P" || echo "SKILL_OK $s $P"
+     else
+       echo "SKILL_MISSING $s"
+     fi
+   done
    ```
-   Read the skill output and keep it in context while editing. Skill output should include:
+
+   **If resolved:** `Read` the skill file at `$P` and keep its guidance in context
+   while you edit. Your tool grant is `Read` — that is the loading mechanism, along
+   with the `skills:` frontmatter. There is no `/invoke` command in this harness; do
+   not emit one. What you are reading for:
    - Patterns specific to this tech (React 19 hooks vs class components, Astro islands vs full-page SSR, etc.)
    - Best practices (error handling, state management, naming conventions)
    - Code examples that match your edit
-   
-   **If skill missing (default fallback mapping):**
+   - Anti-patterns to avoid
+
+   **If `spec.skills` is empty, infer from the target (default fallback mapping):**
    ```
-   .tql, .sql files                    → /typedb (schema and migrations)
-   .astro files (pages/components)     → /astro (islands, SSR, slots)
-   .tsx files (React components)       → /react19 + /shadcn (React 19 hooks + shadcn/ui patterns)
-   .ts files (utilities, services)     → check imports: @oneie/sdk → /ai-sdk; sui → /sui; pheromone → /signal
-   GraphQL / graph files               → /reactflow
-   AI integration files                → /ai-ui
+   .tql, .sql files                    → typedb (schema and migrations)
+   .astro files (pages/components)     → astro (islands, SSR, slots)
+   .tsx files (React components)       → react19 + shadcn (React 19 hooks + shadcn/ui patterns)
+   .ts files (utilities, services)     → check imports: @oneie/sdk → sdk; ai/openrouter → ai-sdk;
+                                         @mysten/sui → sui; signal/receiver code → signal
+   Graph / flow visualisation files    → reactflow
+   AI streaming UI files               → ai-ui
+   Puck blocks / page-editor config    → puck
    ```
-   
-   **If skill missing but needed:** Create it immediately (see "Skill creation" section below).
-   
-   Invoke the skill with the context, read the output, **then edit the file**. Order matters: guidance before changes.
-
-## Skill creation (when no good skill exists)
 
-If invoking a skill returns low-confidence guidance (skill exists but is stale/incomplete), or the skill doesn't exist, **create or update it immediately**:
+   **If SKILL_MISSING or SKILL_STALE:** create/update it immediately (see "Skill creation" below).
 
-**Check skill status:**
-```bash
-if [ ! -d ".claude/skills/{skill-name}/" ]; then
-  echo "SKILL_MISSING"
-elif [ -f ".claude/skills/{skill-name}/SKILL.md" ]; then
-  mtime=$(stat -f %m ".claude/skills/{skill-name}/SKILL.md" 2>/dev/null || echo 0)
-  age_days=$(( ($(date +%s) - mtime) / 86400 ))
-  [ $age_days -gt 30 ] && echo "SKILL_STALE" || echo "SKILL_OK"
-fi
-```
+   Read the skill, **then edit the file**. Order matters: guidance before changes.
 
-**If SKILL_MISSING or SKILL_STALE, create/update it:**
-
-1. **Invoke the skill-creator skill:**
-   ```
-   /skill-creator
-   Input: {
-     name: "{skill-name}",
-     domain: "{domain from file type}",
-     context: "{what this file does, current state}",
-     goal: "{what the edit should accomplish}"
-   }
-   ```
-
-2. **Skill-creator outputs** a `.claude/skills/{skill-name}/SKILL.md` file with:
-   - Domain knowledge (patterns, best practices, gotchas)
-   - Code examples specific to this tech
-   - When to use patterns vs alternatives
-   - Anti-patterns to avoid
+## Skill creation (when no good skill exists)
 
-3. **Invoke the newly created skill:**
-   ```
-   /invoke /{skill-name}
-   Input: {file: target, action: spec.action, current_context: current_state, goal: rationale}
-   ```
+The resolver in rule 5 emits `SKILL_MISSING` or `SKILL_STALE`. Either verdict — or a
+resolved skill whose guidance is visibly thin for this edit — means **create or update
+it immediately**, before the edit:
 
-4. **Then edit the file** using the skill guidance.
+1. Run `/skill-create <skill-name>` (`.claude/commands/skill-create.md`) with the
+   domain implied by the file type, what the target file does, and what the edit must
+   accomplish. It drafts `.claude/skills/<slug>/SKILL.md`.
+2. The new SKILL.md must carry: domain knowledge (patterns, gotchas), code examples
+   for this tech, when to use a pattern vs its alternative, anti-patterns.
+3. `Read` the file you just created, **then edit the target** using its guidance.
+4. Count it in the receipt: `skill_creation_count` / `skills_created`.
 
-**Examples of skill creation triggers:**
-- Editing `.astro` file but `/astro` skill missing → create it
-- Editing new TypeDB entity type but `/typedb` guidance stale → update it
-- Editing Sui contract but `/sui` doesn't cover Move v2 patterns → update it
-- Editing MCP tool but `/mcp` skill missing → create it
+**Triggers seen in practice:**
+- Editing `.astro` but the `astro` skill is missing → create it
+- Editing a new TypeDB entity type but `typedb` guidance is stale → update it
+- Editing a Sui contract but `sui` doesn't cover the Move version in use → update it
 
-This ensures W3 always has domain guidance before making changes. If guidance doesn't exist, W3 creates it.
+W3 always has domain guidance before it changes code. If the guidance doesn't exist,
+W3 writes it — that is the compounding half of this wave.
 
 ---
 
@@ -140,13 +126,19 @@ If any step is missing after your edit, do not mark the spec as `result` — add
 **Navigation reconcile** — after editing any page, component, or route file, run:
 
 ```bash
-do-reconcile.sh navigation <abs/path/to/edited/file>
+bash .claude/scripts/do-reconcile.sh navigation <abs/path/to/edited/file>
 ```
 
+Always the explicit path — `.claude/scripts/` is NOT on `PATH`, so the bare form exits
+127 (`command not found`), which is neither of the exit codes below and would be read as
+a FAIL that never ran. The script `cd`s to the repo root itself, so the explicit form is
+safe from any worktree.
+
 Report the exit status in the receipt:
 - Exit 0 → `nav: ok`
 - Exit 1 (WARN) → `nav: warn — <stdout summary>` — W3 continues but W4 will flag it
 - Exit 2 (FAIL) → `nav: FAIL — <stdout summary>` — this is a **dissolved edit**; do not mark W3 complete; return control to W2 with the navigation failure detail
+- Exit 127 → the invocation is wrong, not the surface. Fix the path and re-run; never report it as `nav: FAIL`.
 
 A navigation FAIL means the surface is unreachable or orphaned — it cannot ship.
 
@@ -168,16 +160,16 @@ W3 receipt: specs=5 marked=5 warned=0 dissolved=0 files_touched=8 nav_ok=3 nav_w
 ## Workflow per spec
 
 1. **Check and invoke skills** — for each skill in `spec.skills`:
-   - If skill exists and current (mtime < 30 days) → invoke it, read output, keep guidance in context
-   - If skill missing or stale → create/update it via `/skill-creator`, then invoke, read output
-   - If skill invocation fails → emit `warn` (soft failure; proceed to edit with fallback knowledge)
+   - Resolve `<name>/SKILL.md` OR `<name>.md`; if found and mtime < 30 days → `Read` it, keep guidance in context
+   - If missing or stale → create/update via `/skill-create`, then `Read` it
+   - If the skill cannot be read or created → emit `warn` (soft failure; proceed to edit with fallback knowledge)
 2. `Read` the target file to confirm the anchor exists verbatim.
 3. If anchor missing → emit `dissolved`, report, stop. Do not improvise.
 4. If anchor present → **apply `Edit` with the exact `old_string` / `new_string` from the spec, using skill guidance**.
    - Guidance means: patterns from skill output, best practices, code examples
    - Do not diverge from the spec's `new_string` to apply guidance — guidance informs quality, not scope
 5. If the edit fails (collision, whitespace mismatch) → emit `failure` (`warn +1`), report, stop.
-6. If editing a page/component/route → run `do-reconcile.sh navigation <file>` and record result.
+6. If editing a page/component/route → run `bash .claude/scripts/do-reconcile.sh navigation <file>` and record result.
 7. If doc-parallel spec exists → edit that file next, same exact-anchor rule. Invoke its skills if declared.
 8. Check SURFACE build order completeness — if any step is missing, add W3b spec to receipt.
 9. On success → record skill names used (`skills_invoked: ['react19', 'shadcn']`) in receipt.

package/agents/w4-tools.md

@@ -0,0 +1,153 @@
+# W4 — verification tooling (loaded on demand)
+
+Companion to `.claude/agents/w4-verify.md`. Split out 2026-09-01: this block is
+~9KB of per-dimension tool recipes that a W4 agent pays for on every spawn but
+uses only when the cycle's dimensions call for them.
+
+**The security grep at the end is NOT optional.** It is the zero-LLM backstop a
+scored security dimension cannot replace; W4 runs it on every cycle. Everything
+above it is conditional on the dimension being scored.
+
+---
+
+## Verification Tools
+
+Use these to produce the numbers — not estimates.
+
+### Lighthouse (Speed dim)
+
+**File → route map** (derive pages to audit from files touched in W3):
+
+| Touched path pattern | Audit URL |
+|---------------------|-----------|
+| `src/pages/index.astro` | `http://localhost:4321/` |
+| `src/pages/get-yours.astro` | `http://localhost:4321/get-yours` |
+| `src/pages/u/**` | `http://localhost:4321/u/demo` |
+| `src/components/chat/**` | `http://localhost:4321/chat` |
+| `src/components/**` | `http://localhost:4321/` + `/chat` |
+| `src/layouts/**` | all pages |
+| `src/pages/api/**` | skip (server routes — no Lighthouse) |
+
+**Pre-flight check before running:**
+
+```bash
+# 1. Check lighthouse is installed
+which lighthouse || npx lighthouse --version 2>/dev/null
+LIGHTHOUSE_OK=$?
+
+# 2. Check dev server is up (start it if needed)
+curl -sf http://localhost:4321/ > /dev/null 2>&1
+SERVER_OK=$?
+
+if [ $SERVER_OK -ne 0 ]; then
+  bun run dev > /tmp/dev-server.log 2>&1 &
+  DEV_PID=$!
+  # Poll until ready (max 15s)
+  for i in $(seq 1 15); do
+    sleep 1
+    curl -sf http://localhost:4321/ > /dev/null 2>&1 && break
+  done
+  curl -sf http://localhost:4321/ > /dev/null 2>&1
+  SERVER_OK=$?
+fi
+```
+
+**If both available — run Lighthouse:**
+
+```bash
+# Run against each derived page URL
+npx lighthouse http://localhost:4321/chat --output=json --quiet \
+  --chrome-flags="--headless --no-sandbox" \
+  | jq '{
+      perf: (.categories.performance.score * 100 | round),
+      a11y: (.categories.accessibility.score * 100 | round),
+      bp:   (.categories["best-practices"].score * 100 | round),
+      seo:  (.categories.seo.score * 100 | round),
+      failing_audits: [.audits | to_entries[]
+        | select(.value.score != null and .value.score < 1)
+        | {audit: .key, score: .value.score, desc: .value.description}]
+  }'
+```
+
+Scores are 0–1 from Lighthouse; multiply by 100. Target is 100 on all four.
+The `failing_audits` array tells you exactly which audit to fix — include these in the
+`→ improve:` instruction so the next cycle knows precisely what to address.
+
+**If Lighthouse unavailable — fallback scoring:**
+
+```
+Score speed on what IS measurable:
+  - Bundle size vs .w0-baseline.json: bundleKB delta
+  - Build time vs .w0-baseline.json: buildMs delta
+  - Hydration grep: no new client:load where client:idle suffices
+
+Cap speed score at 0.80 when Lighthouse skipped.
+Flag in receipt: "lighthouse: skipped — run manually to confirm 100%"
+Do NOT score 1.0 for speed without a real Lighthouse number.
+```
+
+### Playwright (functional + a11y verification)
+
+Playwright runs only when the cycle declares `requires_playwright: true` (testing policy,
+`.claude/commands/do.md`). Vitest is the default; do not add a Playwright gate to a cycle
+that did not ask for one.
+
+```bash
+# Only if the cycle declares requires_playwright AND a config exists
+if [ -f playwright.config.ts ] || [ -f playwright.config.js ]; then
+  npx playwright test --reporter=line 2>&1 | tail -20
+  # a11y scan (axe-playwright) on touched pages — if that suite exists
+  [ -d tests/a11y ] && npx playwright test tests/a11y --reporter=line
+else
+  echo "playwright: n/a — no config in this folder"
+fi
+```
+
+Playwright failures are stability failures — they join the vitest gate.
+A11y failures from playwright count against the Accessibility Lighthouse category.
+Absent config → `playwright: n/a`, never a silent pass.
+
+### Bundle size (Speed dim)
+
+```bash
+# Check CF Worker bundle size
+npx wrangler deploy --dry-run --outdir=.wrangler/output 2>&1 | grep -E 'Total|gzip'
+
+# Or check Astro build output (in the package folder — no root package.json)
+FOLDER="${FOLDER:-one.ie/web}"
+( cd "$FOLDER" && bun run build ) 2>&1 | grep -E 'dist/|\.js|\.css|kB'
+
+# Delta vs W0: compare to the buildMs + sizes recorded in W0
+```
+
+### TypeScript strict check (Stability dim)
+
+```bash
+npx tsc --noEmit --strict 2>&1 | grep -c 'error TS'   # 0 = pass
+```
+
+### Security grep (Security dim)
+
+```bash
+# Run against the diff only (staged + unstaged changes from W3)
+# secrets
+git diff HEAD | grep -E '^\+' | grep -iE 'api[_-]?key|secret|password|token' \
+  | grep -vE '^\+\+\+|zod|schema|type |interface |//|process\.env\.PUBLIC'
+
+# injection vectors
+git diff HEAD | grep -E '^\+.*eval\(' | grep -v '// allow'
+git diff HEAD | grep -E '^\+.*dangerouslySetInnerHTML' | grep -v 'sanitize\|DOMPurify'
+
+# Worker env access
+git diff HEAD | grep -E '^\+.*process\.env' | grep -v '// allow\|PUBLIC_'
+
+# CORS wildcard
+git diff HEAD | grep -E '^\+.*Access-Control-Allow-Origin.*\*'
+
+# TypeDB string concatenation in queries (parameterized form required)
+git diff HEAD | grep -E '^\+' | grep -E 'define|match|insert' \
+  | grep -E '\+\s*[`"\x27]|\.concat\(|\$\{' | grep -iE 'typedb|tql|query'
+```
+
+Zero hits across all greps = security score eligible for 1.0.
+Each hit = `→ improve: file:line — what the pattern is`.