cue-ai 0.9.0 → 0.9.2

package/resources/skills/skills/meta/skill-simplify/phases/02-optimize.md

@@ -0,0 +1,104 @@
+# Phase 2: Optimize
+
+Apply the Phase 1 plan with Edit, in priority order, then write the result.
+Preserve every functional element. When in doubt, keep the original.
+
+## Objective
+
+- Run every operation in order: delete, merge, simplify, format.
+- Keep every functional element from the Phase 1 inventory.
+- Fix the flagged format issues.
+- Write the optimized content back to the target file.
+
+## Step 2.1: Apply operations in order
+
+**Priority 1, delete** (safest, highest impact):
+
+| Target | Action |
+|--------|--------|
+| Duplicate Overview | Remove `## Overview` if it restates the frontmatter description |
+| ASCII flowchart | Remove if a phase table or structure already covers it |
+| "When to use" / "Use Cases" | Remove |
+| Best Practices section | Remove if it duplicates Core Rules |
+| Duplicate folder tree | Remove the ASCII tree if an Output Artifacts table covers it |
+| "Next Phase" prose | Remove when a table or TodoWrite handles flow |
+| Standalone example sections | Remove if the logic is already shown inline |
+| Descriptive code blocks | Remove if nearby prose or a table covers the content |
+
+**Priority 2, merge** (structural):
+
+| Target | Action |
+|--------|--------|
+| Similar AskUserQuestion blocks | One block with a mode parameter |
+| Repeated Option A/B/C routing | One dispatch |
+| Sequential single-line commands | One code block |
+| Repeated TodoWrite blocks | Template once, the rest as one-line comments |
+| Duplicate error handling | One `## Error handling` table |
+| Equivalent template variants | One template plus a comment naming the dropped variant, for example `// variant: multi-perspective adds Perspective` |
+| Multiple output-artifact tables | One combined table with a phase column |
+
+**Priority 3, simplify** (compress descriptive content):
+
+| Target | Action |
+|--------|--------|
+| Verbose comments | One line, drop obvious restatements |
+| Display-format blocks | Convert a logging-only block to a prose sentence describing the output shape |
+| Wordy intros | Drop the preamble |
+| Prompt padding | Drop generic advice from agent or exploration prompts |
+| Long success-criteria lists | Trim to the essential 5 to 7, drop the obvious |
+
+**Priority 4, format fixes**:
+
+| Target | Action |
+|--------|--------|
+| Nested backtick literals | Convert the block to prose, or use a four-backtick fence |
+| Hardcoded option lists | Replace with dynamic generation: name the source and the generation logic |
+| Handoff without steps | Add concrete steps referencing the target command's interface |
+| Unclosed brackets | Match the brackets |
+| Undefined variables | Add the declaration or link the source |
+
+## Step 2.2: Language unification (only if needed)
+
+If the file mixes languages in functional comments, unify the non-functional
+text to the majority language. Never change variable names, function names,
+schema fields, or error message strings inside code.
+
+## Step 2.3: Write the result
+
+Apply edits with Edit on the target file. After writing, record the new line
+count for the report:
+
+```bash
+NEW_LINES=$(wc -l < "$FILE")
+SAVED=$(( ORIGINAL_LINES - NEW_LINES ))
+PCT=$(( SAVED * 100 / ORIGINAL_LINES ))
+echo "Reduced $FILE: $ORIGINAL_LINES -> $NEW_LINES (-${PCT}%)"
+```
+
+## Step 2.4: Keep a change record
+
+Track what changed so Phase 3 can explain a WARN and a human can audit:
+
+```
+optimizationRecord = {
+  deletedSections: [ ... ],          // section names removed
+  mergedGroups:    [ { from, to } ], // what folded into what
+  simplifiedAreas: [ { section, strategy } ],
+  formatFixes:     [ { line, type, fix } ],
+  linesBefore: ORIGINAL_LINES,
+  linesAfter:  NEW_LINES
+}
+```
+
+## Key rules
+
+1. Never modify a functional code block beyond compressing its comments and
+   whitespace.
+2. Descriptive blocks may be deleted only when prose or a table covers them.
+3. Never change a function signature, variable name, or schema field.
+4. A merge must keep every original branch. The unified version handles every
+   case the originals did.
+5. When uncertain, keep the original. Conservative beats clever here.
+6. Format fixes change presentation only, never semantics.
+
+Hand Phase 3 the `optimizationRecord` and the original snapshot path.

package/resources/skills/skills/meta/skill-simplify/phases/03-check.md

@@ -0,0 +1,145 @@
+# Phase 3: Integrity check
+
+Re-extract the inventory from the optimized file with the same logic as Phase
+1, compare counts category by category, validate format, and report PASS,
+WARN, or FAIL. Revert on FAIL. This phase is the entire reason the skill is
+safe to run, do not skip it.
+
+## Objective
+
+- Re-run the Phase 1 extraction on the optimized content.
+- Compare counts with role-aware classification.
+- Confirm no new format issues appeared.
+- Report a result with actionable detail.
+- Restore the original when a critical element is missing.
+
+## Step 3.1: Re-extract
+
+```bash
+NEW_LINES=$(wc -l < "$FILE")
+```
+
+Read the optimized file fresh and rebuild the inventory using the exact same
+rules from `01-analysis.md` steps 1.2, 1.2.1, 1.2.2, 1.2.3. Same extraction,
+same role classification, same counting. A different method here would make
+the comparison meaningless.
+
+## Step 3.2: Compare, role-aware
+
+Diff each category as `after - before`. The category decides the verdict.
+
+**CRITICAL**, must not decrease, any drop is a FAIL:
+
+```
+functionalCodeBlocks  dataStructures  routingBranches  errorHandlers
+conditionalLogic  askUserQuestions  inputModes  outputArtifacts
+skillInvocations
+```
+
+**MERGE_AWARE**, a decrease is a WARN that needs coverage proof:
+
+```
+agentCalls  codeBlocks
+```
+
+**EXPECTED_DECREASE**, a decrease is the goal, always OK:
+
+```
+descriptiveCodeBlocks  todoWriteBlocks  phaseHandoffs  tables  schemas
+```
+
+Verdict per category:
+
+```
+for each category:
+  diff = after - before
+  if CRITICAL:     status = diff < 0 ? FAIL : OK   ; FAIL sets hasCriticalLoss
+  if MERGE_AWARE:  status = diff < 0 ? WARN : OK   ; WARN sets hasWarning
+  else:            status = OK
+```
+
+## Step 3.3: Deep verification
+
+**CRITICAL drop**: name exactly what was lost. For each FAIL category, list the
+before-items that have no match in the after-inventory using the matching
+rules below. That list is what you report to the user.
+
+**MERGE_AWARE drop**: check the merged version covers every original variant.
+For each dropped item, look for a merge comment in a surviving item that names
+it, for example `// variant: multi adds Perspective`. If a dropped item has no
+such comment anywhere, it is truly lost. Promote that category to FAIL and set
+`hasCriticalLoss`. Otherwise the WARN stands and the merge is fine.
+
+## Step 3.4: Format validation
+
+Re-scan the optimized `functional` blocks for format issues. Any issue that
+exists now but did not exist in the Phase 1 list is a NEW issue introduced by
+the edit, and a new issue is a FAIL.
+
+| Check | Detection | On failure |
+|-------|-----------|------------|
+| Bracket matching | Count `{([` vs `})]` per block | FAIL, fix or revert |
+| Variable consistency | `${var}` used but never declared | WARNING, note it |
+| Structural completeness | Body has an entry but no return, Write, or output | WARNING |
+| Nested backticks | Backtick literal inside a code fence | WARNING if pre-existing, FAIL if new |
+| Schema field preservation | After fields match before fields | FAIL if any field lost |
+
+## Step 3.5: Report
+
+```
+status = hasCriticalLoss ? FAIL : (hasWarning ? WARN : PASS)
+```
+
+Show a table with every category: before, after, delta, status. Highlight the
+FAIL and WARN rows. Add a one-line format summary: issues resolved, new issues
+(should be zero). Report lines before, lines after, and the percentage saved.
+
+## Step 3.6: Act on the result
+
+```bash
+case "$STATUS" in
+  FAIL)
+    cp "$FILE.simplify.bak" "$FILE"        # restore the original
+    echo "FAIL: critical element lost or new format issue. Reverted."
+    ;;
+  WARN)
+    echo "WARN: merge or descriptive decrease. Verify the merge covers every case."
+    # keep the edit, show the merge justification from optimizationRecord
+    ;;
+  PASS)
+    rm -f "$FILE.simplify.bak"             # safe to drop the backup
+    echo "PASS: every functional element preserved. ${SAVED} lines saved."
+    ;;
+esac
+```
+
+On FAIL, restore and report which category dropped and which elements were
+lost. Do not patch in place after a FAIL, restore first, then a human decides.
+
+## Element matching rules
+
+How a before-element is judged present in the after-inventory:
+
+| Element | Match on |
+|---------|----------|
+| codeBlocks | Same language plus first meaningful line, ignoring whitespace and comments |
+| agentCalls | Same agentType plus prompt keyword overlap above 60% |
+| dataStructures | Same variable name, or same field set |
+| routingBranches | Same condition, normalized |
+| errorHandlers | Same error type or pattern |
+| conditionalLogic | Same condition plus same outcome set |
+| askUserQuestions | Same question count plus similar option labels |
+| inputModes | Same mode identifier |
+| outputArtifacts | Same file path pattern or artifact name |
+| skillInvocations | Same skill name |
+| todoWriteBlocks | Same phase names, order-independent |
+| phaseHandoffs | Same target phase reference |
+| tables | Same column headers |
+| schemas | Same schema name or field set |
+
+Merge coverage (`coversElement`):
+
+- Agent calls: a surviving template carries a `// For multi:` or
+  `// variant:` comment naming the missing variant.
+- Code blocks: a surviving block carries a comment noting the alternative was
+  folded in.

package/resources/skills/skills/meta/smart-loader/scripts/smart-lookup.sh

@@ -195,10 +195,19 @@ resolve_active_profile
 
 loaded_set=""
 if [ "$EXCLUDE_LOADED" -eq 1 ] && [ -n "$active_profile" ]; then
-  runtime="$HOME/.config/cue/runtime/$active_profile/claude/skills"
-  if [ -d "$runtime" ]; then
-    loaded_set=$(find "$runtime" -mindepth 2 -maxdepth 2 -name "*" -print 2>/dev/null \
-      | sed "s|^$runtime/||" | sort -u)
+  # Preferred: the materializer's manifest of loaded <category>/<slug> ids. The
+  # runtime skills/ dir is now flat (skills/<slug>), so the old depth-2 find no
+  # longer reflects category identity — the manifest does.
+  manifest="$HOME/.config/cue/runtime/$active_profile/claude/.cue-skills"
+  if [ -f "$manifest" ]; then
+    loaded_set=$(sort -u "$manifest" 2>/dev/null)
+  else
+    # Fallback for runtimes built before the manifest (nested <category>/<slug>).
+    runtime="$HOME/.config/cue/runtime/$active_profile/claude/skills"
+    if [ -d "$runtime" ]; then
+      loaded_set=$(find "$runtime" -mindepth 2 -maxdepth 2 -name "*" -print 2>/dev/null \
+        | sed "s|^$runtime/||" | sort -u)
+    fi
   fi
 fi
 is_loaded() {

package/resources/skills/skills/meta/verify-council/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: verify-council
+description: >-
+  Use when finishing a visual or hard-to-reverse change, or the user says
+  "council", "panel of agents", or "visually verify". Runs independent verifier
+  lanes plus a real-screen proof, token-scaled.
+tags: [meta, verification, review, workflow]
+category: meta
+version: 1.0.0
+requires_mcps: []
+allowed-tools: []
+triggers:
+  - "verify with a council"
+  - "council of agents"
+  - "panel of agents"
+  - "verify harder"
+  - "visually verify"
+  - "prove it visually"
+  - "second opinion on this change"
+---
+
+# verify-council
+
+The closing "VERIFIED" step is where false confidence hides. One auditor shares
+the author's blind spots, and a visual claim "checked" by reading the render
+code is at best `[INFERRED]`, never `[VERIFIED]`. This skill replaces the single
+self-check with a small **council** of independent verifier lanes that run in
+parallel, one of which drives the **real screen** and reports a measured value.
+
+It is the panel upgrade to `/verify` (one auditor). Use `/verify` for a quick
+single check; use this when the change is visual, decision-critical, or hard to
+reverse, and you want diverse lenses plus a real-screen proof.
+
+## When to activate
+
+Run the council as the last step of a turn when **all three** hold (the
+`/verify` triage gate):
+
+1. **Decision-relevant**: the user will act on the result.
+2. **Hard to reverse**: being wrong costs real recovery (shipped bug, wrong
+   layout, broken contract).
+3. **Mechanically checkable**: a fresh agent can confirm by reading files,
+   running a command, or measuring the rendered screen.
+
+Skip it for cosmetic or one-line changes: an inline `[VERIFIED]` with a quoted
+line is enough. In minimal-safe-mode, ask before spawning the lanes.
+
+Also activate on: "council", "panel of agents", "verify harder", "visually
+verify".
+
+## Phase 0: triage and mechanical gate (free, no agents)
+
+Run the deterministic checks **first**. They are free and catch most breakage
+before a single agent is paid for.
+
+```bash
+bun test <touched-files>     # or the project's test runner
+bun run typecheck            # tsc --noEmit
+bun run lint                 # biome / eslint
+```
+
+If any gate fails, stop and fix it. Reviewing broken code with agents wastes
+tokens. Then classify the change surface, which decides the lanes:
+
+- `code`: logic only, no rendered surface.
+- `tui`: a terminal UI (cue picker, dashboards drawn to the pane).
+- `web`: the `web/` dashboard or any browser surface.
+
+## Phase 1: the council (parallel, scoped, cheap models)
+
+Spawn only the lanes the change needs. Each lane gets the **diff and the list of
+claims**, not the repo, and returns a structured verdict. Lanes run on a cheap
+model (sonnet); the author adjudicates on the strong one.
+
+| Lane | When | What it does | Returns |
+|---|---|---|---|
+| A correctness | always | Re-derives each logic claim against the diff, neutral prompt, no shared context | PASS / FAIL / PARTIAL + quoted line |
+| B red-team | always for code | Runs the CRITICAL/HIGH review pass over the diff | findings or `REVIEW_CLEAN` |
+| C visual | surface is `tui` or `web` | Drives the real screen and measures it (see below) | observed value vs claim |
+| D skeptic | claim is hard to reverse | Independent refuter, told to REFUTE, default refuted when unsure | refuted? + reason |
+
+The visual lane is the one that turns yellow into green:
+
+- **TUI**: drive the actual terminal with the `cue-tty-watch` MCP: launch the
+  app in a tmux pane (`tmux_pane`), `send_keys_tmux` to reach the target state,
+  `screenshot`, then `find_text` or `ask_about_image` to assert the rendered
+  claim (footer string present, columns aligned).
+- **Web**: drive the dev server with the `lightpanda` MCP: `goto` the URL,
+  `eval` `getComputedStyle()` / `getBoundingClientRect()`, and return the
+  measured pixel values.
+
+## Phase 2: adjudication (author, strong model)
+
+The lanes surface disagreement; the **source settles** it. For every FAIL,
+PARTIAL, or finding:
+
+- Re-read the source at its **absolute** path. Quote the exact line, do not
+  paraphrase. Use `grep -H` (never `-h`) so a match is credited to the right
+  file.
+- If the source confirms the lane, issue a `[CORRECTION]` per the liedetector
+  protocol and fix it.
+- If the source contradicts the lane, the source wins; the lane finding was a
+  hallucination, no correction.
+- A claim earns `[VERIFIED]` only when its lane PASSed with quoted or measured
+  evidence. A **visual** claim needs the Phase 1 measurement, never a code read.
+
+Fix every real CRITICAL and HIGH, re-run the relevant Phase 0 gate to prove the
+fix, then write the confidence audit and sign off.
+
+## Running it
+
+**Preferred (Claude Code): the Workflow engine.** It encodes the adaptive
+fan-out, schema-validated verdicts, and the parallel barrier in one place. Pass
+the capped diff, the claim list, and the surface as `args`:
+
+```text
+Workflow({
+  scriptPath: ".../meta/verify-council/references/workflow.js",
+  args: { diff, claims, surface, hardToReverse, appCmd, url }
+})
+```
+
+Read the returned verdicts and run Phase 2 yourself. The engine spends nothing
+on adjudication, keeping the strong model out of the fan-out.
+
+**Fallback (no Workflow tool, e.g. Codex): manual fan-out.** Spawn the same
+lanes with the Agent tool, one per lane, using the neutral prompts in
+[references/lane-prompts.md](references/lane-prompts.md). The protocol is
+identical; only the orchestration differs.
+
+## Token discipline
+
+This runs "each time" only because it stays cheap:
+
+- Mechanical gate short-circuits before any agent; triage early-exits trivial
+  diffs to zero agents.
+- Lanes see the diff and claims, capped at 60k chars, not the repo.
+- Adaptive count: 2 lanes default, plus the visual lane only when visual, plus
+  the skeptic only when hard to reverse.
+- Cheap model for lanes; strong model only for adjudication.
+- One parallel barrier, so wall-clock is the slowest lane, not the sum.
+- Each lane carries a fixed floor (~35k tokens for agent boot + tool registry),
+  so the council pays off only for genuinely high-stakes changes. For the rest, a
+  clean mechanical gate is the right answer: do not convene a council for a diff
+  the test suite already proves.
+- Pass the diff INLINE, not via a fetch command. An inline diff gives the lane
+  nothing to roam toward; handed only a command, an agent tends to explore the
+  wider repo (more tokens, unscoped findings).
+
+## Rules
+
+- Never tag a visual claim `[VERIFIED]` from a code read. The visual lane's
+  measured value is the only path to green for layout, spacing, or rendered text.
+- Never trust a FAIL on its own. Re-read the source at its absolute path and
+  quote the line before acting.
+- Never skip Phase 0. Paying agents to review code that fails its own tests is
+  the most wasteful mistake here.
+- Never spawn the heavy lanes for a cosmetic diff. Match the lane count to the
+  stakes.
+- In minimal-safe-mode, ask before spawning the council.
+
+## Example
+
+A TUI footer + column-alignment change to the cue profile picker
+(`src/lib/picker.ts`). Surface is `tui` and the layout is hard to reverse, so
+the council runs correctness + red-team + visual.
+
+```text
+1. Phase 0 (free):   bun test src/lib/picker.test.ts  → 155 pass
+                     bun run typecheck                → clean
+2. Phase 1 (council): correctness + red-team over the diff, plus the visual lane:
+   cue-tty-watch launches the picker in a tmux pane, keys to the combine screen,
+   screenshots it, find_text "⏎ enter to continue" → present; columns aligned.
+3. Phase 2 (author): no FAILs to adjudicate → the footer claim moves from
+   🟡 [INFERRED] (read the render code) to 🟢 [VERIFIED] (measured on screen).
+```
+
+## See also
+
+- `/verify`: the single-auditor fast path this skill scales up.
+- `/code-review-deep`: the standalone diff review that lane B reuses.
+- `meta/liedetector`: the confidence-tag output contract Phase 2 writes in.

package/resources/skills/skills/meta/verify-council/references/lane-prompts.md

@@ -0,0 +1,103 @@
+# Lane prompts (Agent-tool fallback)
+
+Use these when the Workflow tool is unavailable (e.g. Codex). Spawn one Agent
+per lane, in parallel, each on a cheap model (sonnet). They are the same prompts
+the Workflow engine builds inline; this file is the human-readable canonical
+copy. Fill in `<DIFF>`, `<CLAIMS>`, `<URL>`, `<APP_CMD>` before spawning.
+
+Every lane shares this preamble:
+
+```text
+You are an INDEPENDENT verifier with no shared context. Do not edit anything.
+Several assertions below may be false — do not assume they are correct.
+For each claim return PASS / FAIL / PARTIAL / NA with evidence that QUOTES the
+exact line or MEASURES the value. A remembered or paraphrased line is not evidence.
+Return a terse list: one claim id + verdict + one evidence line each.
+
+SCOPE: the change under review is EXACTLY <DIFF> (or the verbatim output of the one
+command you are given). Do not open or report on any file outside it; discard any
+finding you cannot tie to a line shown there. Reviewing the wider repo wastes the
+token budget.
+CLAIMS: answer exactly the claim ids listed, verbatim. Do not invent, rename, or add
+ids. If a claim cannot be judged from the change, mark it NA.
+```
+
+The scope + claim-binding lines matter: without them a lane drifts into a free-form
+repo review, which both blows the token budget and leaves the caller's actual claims
+unverified.
+
+## Lane A — correctness (always)
+
+```text
+Lane: correctness. Re-derive each claim strictly from the diff.
+
+CLAIMS:
+<CLAIMS>
+
+--- DIFF ---
+<DIFF>
+--- END DIFF ---
+```
+
+## Lane B — red-team (always for code)
+
+```text
+Lane: red-team. Review ONLY the diff for blocking defects.
+  CRITICAL: security holes, data loss, crashes, injection, broken auth.
+  HIGH:     real bugs, broken contracts, race conditions, wrong logic.
+List each as a finding with severity. Skip LOW/style nits.
+If there are no CRITICAL or HIGH defects, reply exactly: REVIEW_CLEAN.
+
+--- DIFF ---
+<DIFF>
+--- END DIFF ---
+```
+
+## Lane C — visual proof (only when the surface is rendered)
+
+A code read is not acceptable here. Only a screenshot or a measured value counts.
+
+TUI surface:
+
+```text
+Lane: visual proof. Surface: TUI.
+Use the cue-tty-watch MCP tools (find them with ToolSearch): launch the app in a
+tmux pane with `<APP_CMD>`, send_keys_tmux to reach the target screen, screenshot
+it, then find_text / ask_about_image to assert each claim against what is on screen.
+
+VISUAL CLAIMS:
+<CLAIMS>
+```
+
+Web surface:
+
+```text
+Lane: visual proof. Surface: WEB.
+Use the lightpanda MCP tools (find them with ToolSearch): goto <URL>, then eval
+getComputedStyle() / getBoundingClientRect() on the relevant selectors and return
+the MEASURED pixel values for each claim.
+
+VISUAL CLAIMS:
+<CLAIMS>
+```
+
+## Lane D — skeptic (only when the change is hard to reverse)
+
+```text
+Lane: skeptic. Your job is to REFUTE the riskiest claim, not confirm it. Default
+each claim to FAIL ("refuted") unless the diff makes it undeniable. Be adversarial.
+
+CLAIMS:
+<CLAIMS>
+
+--- DIFF ---
+<DIFF>
+--- END DIFF ---
+```
+
+## Adjudication (back on the strong model)
+
+The lanes surface disagreement; the source settles it. For every FAIL / PARTIAL /
+finding: re-read the source at its absolute path, quote the exact line (`grep -H`,
+never `-h`), and let the source win. Tag a claim `[VERIFIED]` only when its lane
+PASSed with quoted or measured evidence; a visual claim needs Lane C's measurement.