@tw93/waza 3.25.0 → 3.28.0

package/skills/design/SKILL.md

@@ -11,16 +11,47 @@ Prefix your first line with 🥷 inline, not as its own paragraph.
 
 If it could have been generated by a default prompt, it is not good enough.
 
+## Outcome Contract
+
+- Outcome: a usable interface or visual fix with a clear point of view and no incoherent layout, text, or responsive breakage.
+- Done when: the real rendered surface or generated artifact has been checked against the user's visual goal and the relevant viewport states.
+- Evidence: screenshots, rendered UI, source components, design tokens, accessibility constraints, and user-provided references.
+- Output: the implemented visual change or a precise visual review with the remaining verification gap named.
+
 **Output language rule:** Never use em-dash (—) in any output from this skill. Use commas, colons, or periods instead.
 
 **Chinese gut-feel complaints**: when the user says "很傻", "很怪", "突兀", "不协调", "不和谐" about a visual, treat it as an aesthetic rejection, not a debugging symptom. Route to Screenshot Iteration Mode, not to `/hunt`.
 
+**Document & print typography → Kami.** When the deliverable is a shippable document rather than a product UI surface (report, slide deck, resume, long-form or print-oriented page, paged PDF), do not hand-roll an over-designed document layout here. Suggest the user run it through Kami (`tw93/Kami`), a document design system with a fixed constraint language and templates, and let Kami draft the detailed plan. Screen 排版 (app surfaces, components, web pages) stays in this skill.
+
 ## Durable Context Preflight
 
 See [rules/durable-context.md](../../rules/durable-context.md) for when to read durable context, the read-order budget, and the memory-type mapping.
 
 For `/design`, visual constraints are `decision`, `preference`, and `principle` entries; reusable product and UI patterns are `pattern` and `learning`. Current screenshots, rendered output, code, design tokens, and user feedback override memory. Reuse durable visual preferences and mature interaction patterns, but still name the current visual problem from the screenshot or source before changing code.
 
+## Visual Quick-Fix Mode
+
+Activate when the user asks for a narrow visual repair with a concrete symptom: overflow, clipped or wrapped text, misalignment, spacing imbalance, contrast/readability, localized text not fitting, or compact responsive breakage. This is for fixing an existing surface, not redesigning it.
+
+Flow:
+
+1. Read the current UI evidence: screenshot, rendered page, native view, or responsible component.
+2. Name the exact visual defect in one sentence.
+3. Make the smallest material, geometry, spacing, contrast, typography, or text-fit change that fixes that defect.
+4. Verify the real running surface or generated artifact. Check long words, localized strings, compact states, and at least one narrow viewport when applicable.
+5. If the fix touches three or more components, changes product behavior, or reveals a direction problem, stop and switch to Screenshot Iteration Mode or Lock the Direction First.
+
+**Spacing unification rule.** If a magic spacing or sizing value has been adjusted three times and the layout still looks off, stop tuning. Replace the N independent padding / gap / margin / size values with one shared named token (`Spacing.s4`, `--gap-content`, `gap-4`). Outer container padding defaults to the same value as inner element gap. Asymmetry that survives tuning is structural, not numeric, so more rounds of magic numbers will not converge. Reduce the count of independent values first, then argue about the specific value.
+
+**Fixed-height action slot, uniform typography.** Any container that swaps children based on state (status bar, action slot, toolbar row, menu item) must use one font size across every state. Vary fill, stroke, opacity, color, or icon, never font size. A 1pt height delta between `secondary 13px` and `primary 14px` becomes visible jitter at the state transition. CTA pill buttons in the same slot use the same size (typically 14px), distinguished by background and border, not by typography.
+
+**Completion screen layout.** Operation-complete surfaces show the single result the user came for: the actual reclaimed size / processed count / changed state. Long explanations belong in a details overlay opened from a summary row, not in the primary completion line. Do not add a separate "Review" button next to the summary row when one tap on the row already opens details; do not show an empty "0 skipped" entry point. If there is no skipped or failed item, hide the details affordance entirely.
+
+**Safety-bound action design.** For cleanup, deletion, uninstall, reset, or permission-changing surfaces, do not make the UI feel simpler by hiding recoverability. Bulk select, auto-select, one-tap delete, or "recommended" destructive defaults are only appropriate when each row is understandable to the target user and carries enough identity to verify safety (name, source, owner, path, preview, or recovery implication as relevant). If rows are opaque identifiers, inferred leftovers, or machine-only paths, prefer review-first UI, current-target scoping, disabled destructive affordances, or explanatory grouping over faster batch controls. A feature request for fewer clicks is not enough to remove the user's ability to verify what will change.
+
+**Quiet product boundary.** Fewer clicks and richer controls are not automatically better. Remove misleading affordances before adding alternate controls, prefer quiet defaults for diagnostics and alerts, and fix unstable motion cadence before changing speed or adding a new motion preference. If the current UI implies an action, state, or promise it cannot support, remove that implication first.
+
 ## Screenshot Iteration Mode
 
 Activate when the user sends a screenshot or image alongside a complaint ("这里很丑", "这个不对", "fix this", "looks wrong"). The existing product is the direction. Skip the five-question direction lock.
@@ -56,7 +87,7 @@ Before writing any code, ask the user directly, using the environment's native q
 2. **What is the aesthetic direction?** Name it precisely: dense editorial, raw terminal, ink-on-paper, brutalist grid, warm analog. "Clean and modern" is not a direction. If the user names a reference site or product ("feels like Linear / Claude.ai / Vercel"), do not accept it as a direction -- extract 3 concrete properties from it: button radius philosophy, surface depth treatment (shadow vs background step vs border), and accent color family. Name those instead.
 
    **Shortcut for well-known brands**: see "Brand preset flow" in `references/design-reference.md`. Ask first, run the preset, then decompose against the generated file.
-3. **What is the one thing this leaves in memory?** A typeface, color system, unexpected motion, asymmetric layout. Pick one and make it obvious.
+3. **What is the design signature?** A typeface, color system, unexpected motion, asymmetric layout. Pick one and make it obvious.
 4. **What are the hard constraints?** Framework, bundle size, contrast minimums, keyboard accessibility.
 5. **What is the signature micro-interaction?** Scale on press, staggered reveal, or contextual icon animation. Pick one and know exactly how it's implemented.
 
@@ -73,6 +104,10 @@ Lift exact values: hex codes, spacing scale entries, font stacks, border radii.
 
 Only attach the target component folder or package. Exclude `.git`, `node_modules`, `dist`, and lock files. Dragging in an entire monorepo pollutes the context with irrelevant code and degrades output quality.
 
+### Existing-native-app exception (do not propose wholesale platform restyling)
+
+When the target is an existing macOS / iOS / Android native app that already has a coherent visual direction, do not propose a wholesale port to a newer platform style (macOS 26 Liquid Glass, iOS 18 frosted material, Material You, Fluent Design, etc.) as the default improvement plan. Wholesale restyling reads as "I do not have a specific design intent, here is the platform's." Default to incremental polish on the existing direction: spacing, alignment, hover and focus states, typography hierarchy, copy tightening, motion timing. Only propose a platform-style migration when the user has explicitly asked for it in this turn, or when the existing direction is broken in a way that incremental polish cannot fix. State the existing direction in one sentence before proposing changes so the user can correct the read.
+
 ### App shell exception (sidebar + main workspace)
 
 If question 1 is an app shell (Slack, Linear, Notion class), load the "App shell rules" section in `references/design-reference.md` and apply those constraints before proceeding.
@@ -90,7 +125,7 @@ Summarize the direction as three lines before writing any code:
 
 For production or multi-page UIs, expand the thesis into the 9-section DESIGN.md scaffold in `references/design-reference.md` (theme, palette, typography, components, layout, depth, do/don't, responsive, prompt guide). For a single component, the three lines are sufficient.
 
-## Non-Negotiable Constraints
+## Hard Rules
 
 `references/design-reference.md` is already loaded during direction lock. It owns the full rules: typography, OKLCH color, motion timings, layout defaults, CSS-pattern bans, accessibility baseline, and complexity matching. Apply them. Do not restate them here.
 
@@ -108,7 +143,9 @@ Give at least 3 variations across genuinely different dimensions (density, typog
 | Chose glassmorphism, ignored the mobile constraint | `backdrop-filter` is expensive on low-power devices. Name the tradeoff. |
 | Light-mode app: white panel on white background, visually indistinguishable | Adjacent nested surfaces must differ visually. Either background step (sidebar vs main ≥4% lightness difference) or shadow minimum `0 1px 3px rgba(0,0,0,0.10)`. |
 | Fixed visual polish by redesigning the whole surface | Locate the concrete visual delta first, then make the smallest material, opacity, geometry, or typography change that addresses it. |
+| Added a setting or louder control to solve UI noise | Remove the misleading affordance or choose a quiet default first |
 | English looked fine, localized text overflowed | Test long words and localized strings before handoff, especially inside buttons, tabs, nav, and compact cards. |
+| Relied on `…` truncation to fit text in a fixed-width slot | Guarantee fit instead: compact the format, cap to whole segments, or hard-trim with no glyph. Metric and label footers must never tail-truncate into an ellipsis. |
 
 ## Aesthetic Review
 

package/skills/design/references/design-reference.md

@@ -123,6 +123,13 @@ When extending an existing interface, first spend time understanding its visual
 
 If swapping in different content would make the new component look out of place, the vocabulary was not matched closely enough.
 
+### Responsive & Screen Verification
+- Verify the rendered surface, not a type check or CSS-balance read. Several regressions (early wraps, orphaned separator dots, table overflow) are invisible in source and only show in the render. Screenshot at phone (375px, plus 320px for buttons) and desktop (1280px), in every shipped locale.
+- Line widows: eliminate 1-2 word last lines by trimming the copy so the block rebalances, not by adding a `max-width` cap (a cap narrower than its container wraps early and leaves empty space on the right, which reads as a premature break). Detect objectively: flag any text block whose last line is under ~13% of its widest line; eyeballing misses them, and nested `<code>` hides them from greps.
+- Mobile CTA resting state: natural width, left-aligned to the surrounding text edge, height unchanged. Centering reads as floating; full-width `flex: 1` reads heavy; dropping button height to relieve a "too full" feel treats a width problem as a height one.
+- Spacing is a system, not a per-gap value. Run section spacing as one responsive ladder; when a page reads too airy or too tight, scale the whole set by a single factor across all breakpoints rather than tuning one gap. Asymmetry that survives tuning is structural.
+- Long-form and documentation surfaces stay light: a borderless prev/next text pager (not bordered cards), a sidebar active state as a thin rail rather than a filled block, and build-time zero-runtime-JS code highlighting (bake static spans, plain code stays the source) over a shipped highlighter.
+
 ## Data Visualization Surfaces
 
 For dashboards, analytics views, chart-heavy interfaces, or number-dense displays, load `references/design-data-viz.md`. It owns dashboard defaults, chart selection, number alignment, and product-benchmark extraction.
@@ -140,6 +147,16 @@ Reject: Inter, DM Sans, DM Serif Display, DM Serif Text, Outfit, Plus Jakarta Sa
 3. Reject all three.
 4. Pick a typeface from a named foundry (Klim, Commercial Type, Colophon, Grilli Type, OH no Type, Village, etc.) or an open-source option with a clear personality that matches the brand words. Be able to explain why that specific typeface in one sentence.
 
+## CJK & Multilingual Type
+
+When the interface mixes Chinese, Japanese, or Korean with Latin, Latin-only type rules silently break the CJK text. Apply these before handoff:
+
+- **Latin face first, system CJK face after** in the stack, so each script renders with correct glyphs: `font-family: -apple-system, "SF Pro Text", "PingFang SC", "Noto Sans SC", sans-serif;`. Latin runs use the Latin face; Han characters fall through to the CJK face.
+- **Give CJK body text more line-height than Latin**: roughly 1.7–1.8 for reading. Dense Hanzi needs more vertical room than the 1.4–1.5 that suits Latin body copy.
+- **Tag runs with `lang="zh"` / `lang="ja"` / `lang="en"`** so the browser picks the right font and line-breaking. Mixed-language paragraphs break badly without it.
+- **Serif reading modes need an explicit CJK serif fallback.** Most Latin "reading serif" webfonts carry no CJK glyphs, so a serif toggle silently drops Chinese back to a sans and looks broken. Pair them: `"Newsreader", "Songti SC", "Noto Serif SC", serif`.
+- **Do not apply negative letter-spacing to CJK runs.** The display-type tracking rule above is Latin-only; tightening tracking on Hanzi cramps the glyphs and reads as a rendering bug. Scope tracking to `lang="en"` runs.
+
 ## Color System: OKLCH Rules
 
 - Use OKLCH instead of HSL. OKLCH is perceptually uniform: equal numeric changes produce equal perceived changes across the spectrum.

package/skills/design/references/design-tokens.md

@@ -1,4 +1,6 @@
-# Design Tokens: Color, Typography, and Motion
+# Design Tokens: Color and Typography
+
+Motion rules live in [design-reference.md](./design-reference.md) under Animation and Motion Specifics. This file owns color and typography only.
 
 ## Color System: OKLCH Rules
 
@@ -41,13 +43,3 @@ Reject: Inter, DM Sans, DM Serif Display, DM Serif Text, Outfit, Plus Jakarta Sa
 - `-webkit-font-smoothing: antialiased; -moz-osx-font-smoothing: grayscale` once on root layout (macOS only)
 - `font-variant-numeric: tabular-nums` for counters, timers, prices, number columns
 - Letter-spacing: roughly -0.022em for display sizes (32px+), -0.012em for mid-range (20-28px), normal at 16px and below
-
-## Motion Specifics
-
-- No bounce or elastic easing. Use exponential ease-out: `cubic-bezier(0.16,1,0.3,1)` for natural deceleration.
-- Animate `transform` and `opacity` only. Every other property triggers layout or paint.
-- For height reveals: `grid-template-rows: 0fr` to `1fr` (avoids `height: auto` animation trap).
-- Icon swaps: 120ms cross-fade with `opacity` and subtle `scale(0.9)` to `scale(1)`.
-- Scale on press: `scale(0.96)` on active/press via CSS transitions.
-- Page-load guard: `initial={false}` on animated presence wrappers for toggles and tabs (prevents enter animations on first render).
-- Honor `prefers-reduced-motion`: disable or reduce animations when set.

package/skills/health/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: health
-description: "Runs a budget-aware Agent Health audit for Codex, Claude Code, Pi, agent instructions, hooks/MCP, verifier surfaces, and AI maintainability. Use when users ask 检查claude/检查codex/检查pi/配置检查/健康度 or report agents ignoring instructions, missing validation, or code becoming hard to maintain. Not for debugging code or reviewing PRs."
+description: "Runs a budget-aware agent-assisted engineering health audit for instruction/config drift, hooks/MCP, verifier surfaces, and AI maintainability. Use when users ask 检查claude/检查codex/检查pi/配置检查/健康度 or report agents ignoring instructions, missing validation, or code becoming hard to maintain. Not for debugging code or reviewing PRs."
 when_to_use: "检查claude, 检查codex, 检查pi, Codex 配置, Pi 配置, AGENTS.md, config.toml, agent instructions, 健康度, 配置检查, 配置对不对, AI coding 腐化, 代码变烂, 维护性, 上下文混乱, 验证缺失, 验证命令失真, Claude ignoring instructions, Pi coding agent, check config, settings not working, audit config"
 dispatch_intent: "Codex/Claude/Pi ignoring instructions, agent config audit, hooks/MCP broken, health token usage, AI coding code rot, hotspot ownership, unclear context, missing verification, stale verifier output"
 ---
 
-# Health: Agent Config and AI Maintainability
+# Health: Agent-Assisted Engineering Health
 
 Prefix your first line with 🥷 inline, not as its own paragraph.
 
@@ -14,6 +14,18 @@ Audit the current project's agent setup and AI coding maintainability against th
 
 Find violations. Identify the misaligned layer. Calibrate to project complexity only.
 
+## Outcome Contract
+
+- Outcome: a budget-aware health report that separates agent configuration risk from AI maintainability risk.
+- Done when: each finding names the misaligned layer, the concrete evidence, and a copy-pasteable action or diagnostic command.
+- Evidence: collected health script output, tracked project instructions, runtime config summaries, verifier logs, hooks/MCP surfaces, and live probes when needed.
+- Output: prioritized findings with status, impact, and next action, or a clear clean bill with residual risk.
+
+Two lanes share one report:
+
+- **Agent config health**: Codex/Claude/Pi instruction drift, permissions, hooks, MCP, skills, and memory supply chain.
+- **AI maintainability health**: project context surface, verifier wrapper, generated-artifact checks, hotspot ownership, and stale or misleading durable docs.
+
 **Output language:** Check in order: (1) project agent instructions (`AGENTS.md` before runtime-specific files); (2) global agent instructions; (3) user's recent language; (4) English.
 
 **Budget posture:** Start with the summary audit. Escalate automatically when the user asks for a deep, full, complete, thorough, "深入", "完整", "彻底", or "继续跑完" audit, when the user explicitly mentions AI coding code rot, Codex/Claude config drift, unclear context, missing verification, verifier output that points at stale paths, or "代码变烂", when current project instructions or remembered user preference says to run deep health checks by default, when the project is Complex, or when the summary pass exposes a critical ambiguity that cannot be resolved locally. Otherwise do not read full conversation extracts or launch inspector subagents. Tell the user before escalating because deep health audits can consume significant token quota.
@@ -28,13 +40,11 @@ For `/health`, audit expectations are `decision`, `preference`, and `principle`
 
 Pick one. Apply only that tier's requirements.
 
-
-| Tier         | Signal                                  | What's expected                                |
-| ------------ | --------------------------------------- | ---------------------------------------------- |
-| **Simple**   | <500 files, 1 contributor, no CI        | CLAUDE.md only; 0-1 skills; hooks optional     |
-| **Standard** | 500-5K files, small team or CI          | CLAUDE.md + 1-2 rules; 2-4 skills; basic hooks |
-| **Complex**  | >5K files, multi-contributor, active CI | Full six-layer setup required                  |
-
+| Tier | Signal | What's expected |
+|---|---|---|
+| **Simple** | <500 files, 1 contributor, no CI | CLAUDE.md only; 0-1 skills; hooks optional |
+| **Standard** | 500-5K files, small team or CI | CLAUDE.md + 1-2 rules; 2-4 skills; basic hooks |
+| **Complex** | >5K files, multi-contributor, active CI | Full six-layer setup required |
 
 ## Step 1: Collect data
 
@@ -74,23 +84,27 @@ The collector includes both runtime-specific and agent-agnostic surfaces:
 
 Test every MCP server: call one harmless tool per server. Record `live=yes/no` with error detail. Respect `enabled: false` (skip without flagging). For API keys, only check if the env var is set (`echo $VAR | head -c 5`), never print full keys.
 
-## Security Baseline Checks
+## Step 1c: Safety and security checks
+
+These run after collection and before the Step 2 analysis. The first two apply to every audit; the third only to projects with long-running or autonomous agents.
+
+### Security Baseline Checks
 
 Run these on every audit, regardless of tier. They are the floor, not the ceiling.
 
-**Deny-list floor.** The project's agent settings should deny, at minimum: credential and key directories (SSH, cloud providers, GPG, gh CLI), secret files (`.env`, `credentials*`, `secrets*`), pipe-to-shell installers (`curl ... | bash`, `wget ... | sh`), and outbound shells (`ssh`, `scp`, `nc`). Flag missing categories as Critical findings; let the reviewer fill in the exact paths from the project's environment.
+**Deny-list floor.** Apply this only when the project or runtime exposes agent permission settings, hook settings, MCP settings, allowed/denied tools, or a documented autonomous-agent launcher. In that case, the settings should deny, at minimum: credential and key directories (SSH, cloud providers, GPG, gh CLI), secret files (`.env`, `credentials*`, `secrets*`), pipe-to-shell installers (`curl ... | bash`, `wget ... | sh`), and outbound shells (`ssh`, `scp`, `nc`). Report this as one concise WARN with the missing categories and suggested fix; let the reviewer fill in exact local paths from the environment. If no agent settings surface exists, report the deny-list as not applicable rather than a failure.
 
 **Environment override surface.** Treat the following as attack surface, report when set in tracked files or shipped settings without a justification comment: API base-URL overrides (redirect all traffic to a third party), auto-trust flags for project-local MCP servers, wildcard tool allowlists (`allowedTools: ["*"]`), and permission-skip flags (`--dangerously-skip-permissions` or equivalents). Print file:line and the key name only; never print secrets.
 
-## Memory and Skill Supply Chain
+### Memory and Skill Supply Chain
 
 Treat agent memory and third-party skills as supply-chain artifacts. They run with the user's privileges.
 
 **Memory hygiene.** Audit the project's long-term agent memory store for secrets, tokens, or credentials (Critical), and for entries written by untrusted runs (subagent invoked on attacker-controlled input, /loop iteration over external content); recommend rotation after such runs. For high-risk one-off runs (untrusted PDFs, uncontrolled scraping, third-party scripts), recommend disabling memory persistence for that session entirely.
 
-**Skill supply chain.** Third-party skills, plugins, and MCP servers run with the user's privileges. For each one not authored in this repo, check: source pinned to a release tag (not `main` or a branch), hook handlers do not write to credential directories, MCP servers have explicit user consent (not auto-trusted by wildcard). Report unpinned sources or unreviewed hook handlers as Structural, not Critical, unless an active exploit signal is present.
+**Skill supply chain.** Third-party skills, plugins, and MCP servers run with the user's privileges. For each one not authored in this repo, check: source pinned to a release tag or revision (not `main`, a branch, or a remote git marketplace left tracking its latest head), hook handlers do not write to credential directories, MCP servers have explicit user consent (not auto-trusted by wildcard). Report unpinned sources or unreviewed hook handlers as Structural, not Critical, unless an active exploit signal is present.
 
-## Long-Running Agent Stop Conditions
+### Long-Running Agent Stop Conditions
 
 For projects that use `/loop`, autonomous agents, or any long-running agent flow, the project must define explicit stop conditions. An agent that never stops is a budget and safety incident waiting to happen.
 
@@ -101,7 +115,7 @@ Audit for these four hard stop signals; flag the absence of each as a Structural
 3. **Cost or token budget exceeded.** Project should declare a per-run budget (tokens, API spend, wall-clock minutes). Loop exits when the budget is hit, not when work is done.
 4. **External blockers.** Merge conflict on the target branch, dependency lock the agent cannot resolve, missing credential, network unreachable. Any of these halt the loop and ask the user, not retry forever.
 
-The stop conditions should live in tracked project docs (`AGENTS.md`, the loop's launch script, or a dedicated config), not only in the agent's prompt. Prompts are forgettable; tracked config is enforceable. Recommend hooks (PostToolUse on the relevant tools) over prompt instructions when the project supports them: a hook physically cannot be skipped, a prompt instruction can.
+The stop conditions should live in tracked project docs (`AGENTS.md`, the loop's launch script, or a dedicated config), not only in the agent's prompt. Prompts are forgettable; tracked config is enforceable. Recommend hooks (PostToolUse on the relevant tools) over prompt instructions when the project supports them: a hook physically cannot be skipped, a prompt instruction can. Confirm the host's hook coverage before recommending one: some agents only fire PostToolUse for a subset of tools (for example, a runtime may match shell/Bash only), so a fixup that must run after file edits belongs on a Stop or session-end hook there instead.
 
 ## Step 2: Analyze
 
@@ -155,6 +169,20 @@ bash skills/health/scripts/check-agent-context.sh . summary
 
 **AI-maintainability gaps.** Use `AI MAINTAINABILITY SUMMARY` in summary mode and `AI MAINTAINABILITY DETAIL` in deep mode. Report `FAIL` when the project has no executable verification command, no agent instruction surface for a non-trivial repo, or broken doc references. Report `WARN` when instructions exist but lack a project map, verification guidance, boundary/non-goal language, when TODO/HACK markers are concentrated, when large source hotspots lack ownership/boundary and verification guidance, or when durable docs contain raw one-off review reports, scorecards, dated line references, or diagnostic dumps instead of stable invariants. Treat missing `docs/`, `specs/`, `.specify/`, `HANDOFF.md`, `CHANGELOG`, issue templates, and PR templates as informational unless project complexity makes them necessary for handoff. The action for stale reports is to extract stable rules into public instructions, rules, references, or verifier scripts, then remove or archive the transient report.
 
+**Conversation-derived guidance.** When a health audit reads recent agent conversations, do not recommend copying the conversation or a scorecard into docs. Recommend a candidate-matrix pass instead:
+
+| Field | Question |
+|---|---|
+| Repeated failure | Did this recur across fixes, releases, agents, or user reports? |
+| Durable invariant | Can the lesson be stated as a stable rule, not a dated incident summary? |
+| Target layer | Should it live in project instructions, a Waza skill, a global rule, or private memory? |
+| Verifier | Is there a deterministic command, script, artifact check, or runtime smoke that can enforce it? |
+| Redaction risk | Does the lesson require local paths, issue numbers, customer details, machine state, secrets, or unpublished release facts? |
+
+Layering rule: project-specific commands, app names, artifact names, and release rituals stay in the project; reusable workflows such as cancelled-release review gates or native-freeze evidence ladders belong in Waza skills; universal honesty and verification rules belong in global CLAUDE/AGENTS; private user preferences and one-machine facts stay in memory. If the lesson cannot pass the redaction-risk field, keep it out of public guidance.
+
+**Concentrated fix chains.** Run `git log --oneline --since='2 weeks ago' | grep -i fix` and group by area (the prefix before `:` or `(`). When the same area has 3+ fix commits in a short window, it signals a missing structural invariant: each fix is a guess at a rule that was never written down. Report a Structural `WARN` with the area name, fix count, and recommend adding an explicit rule to `AGENTS.md` / `CLAUDE.md` / project rules that captures the invariant those fixes were converging toward. A concentrated fix chain that touches the same file 4+ times is a stronger signal than scattered fixes across different files.
+
 **Hotspot ownership gaps.** In deep mode, read `HOTSPOT OWNERSHIP SURFACE`. If a largest source file exceeds the hotspot threshold and `AGENTS.md` / `CLAUDE.md` / shared instruction files do not name who owns the hotspot, what boundary should stay stable, and which verification command covers it, report a Structural `WARN`. Do not treat documented large files as code rot by size alone; some modules are intentionally large.
 
 **Missing stable verifier wrapper.** If the repo exposes multiple verification commands through CI, scripts, or manifests but `Makefile` has no `check`, `test`, or `verify` target, report a Structural `WARN`. This is an AI-maintainability gap because agents need one stable default entrypoint, not because the project is broken.
@@ -217,15 +245,14 @@ If no issues: `All relevant checks passed. Nothing to fix.`
 
 ## Gotchas
 
-
-| What happened                                                               | Rule                                                                                                                                                                                                                                                                                           |
-| --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Missed the local override                                                   | Always read `settings.local.json` too; it shadows the committed file                                                                                                                                                                                                                           |
-| Subagent timeout reported as MCP failure                                    | MCP failures come from the live probe, not data collection                                                                                                                                                                                                                                     |
-| Reported issues in wrong language                                           | Honor CLAUDE.md Communication rule first                                                                                                                                                                                                                                                       |
-| Flagged intentionally noisy hook as broken                                  | Ask before calling a hook "broken"                                                                                                                                                                                                                                                             |
+| What happened | Rule |
+|---|---|
+| Missed the local override | Always read `settings.local.json` too; it shadows the committed file |
+| Subagent timeout reported as MCP failure | MCP failures come from the live probe, not data collection |
+| Reported issues in wrong language | Honor CLAUDE.md Communication rule first |
+| Flagged intentionally noisy hook as broken | Ask before calling a hook "broken" |
 | Hook seemed not to fire, but it did -- a later UI element rendered above it | Hook firing order is not visual order. Before re-editing the hook config: (a) confirm with `--debug` or by piping output, (b) check whether a diff dialog, permission prompt, or other UI element rendered on top and pushed the hook output offscreen, (c) only then suspect the hook itself. |
-| `/health` burned too much quota on first run                                | Stay in summary mode first. Full conversation extracts and inspector subagents are deep-audit tools, not the default path for Standard projects.                                                                                                                                                 |
-| Treated missing specs/docs as a failure                                     | Decision artifacts are optional by default. Escalate missing docs/specs only when the tier, active handoff risk, or user request makes them necessary.                                                                                                                                           |
-| Treated an ignored AGENTS/CLAUDE file as durable project truth              | Report whether the rule is tracked and distributed. Local overlays can inform the audit, but durable fixes belong in public repo docs or shipped skill/rule files.                                                                                                                               |
-| Treated a review scorecard as maintainability documentation                 | Scorecards are snapshots. Extract the invariant and verification path, then remove or archive the report instead of calling the score itself a durable rule.                                                                                                                                     |
+| `/health` burned too much quota on first run | Stay in summary mode first. Full conversation extracts and inspector subagents are deep-audit tools, not the default path for Standard projects. |
+| Treated missing specs/docs as a failure | Decision artifacts are optional by default. Escalate missing docs/specs only when the tier, active handoff risk, or user request makes them necessary. |
+| Treated an ignored AGENTS/CLAUDE file as durable project truth | Report whether the rule is tracked and distributed. Local overlays can inform the audit, but durable fixes belong in public repo docs or shipped skill/rule files. |
+| Treated a review scorecard as maintainability documentation | Scorecards are snapshots. Extract the invariant and verification path, then remove or archive the report instead of calling the score itself a durable rule. |

package/skills/health/agents/inspector-context.md

@@ -22,7 +22,7 @@ rules/ checks:
 
 Skill checks:
 - SIMPLE: 0–1 skills is fine.
-- ALL tiers: If skills exist, descriptions should be <12 words and say when to use.
+- ALL tiers: If skills exist, descriptions should be concise, triggerable, include `Use when`, include `Not for`, and avoid overlapping triggers.
 - STANDARD+: Low-frequency skills may use `disable-model-invocation: true`, but Claude Code plugin skills should not rely on it until upstream invocation bugs are fixed.
 
 MEMORY.md checks, STANDARD+:

package/skills/health/scripts/check_agent_context.py

@@ -20,6 +20,10 @@ from pathlib import Path
 SENSITIVE_RE = re.compile(r"(api[_-]?key|token|secret|password|credential)", re.IGNORECASE)
 PROJECT_RE = re.compile(r'^\[projects\."(.+)"\]\s*$')
 TABLE_RE = re.compile(r'^\[([A-Za-z0-9_.@"\-/]+)\]\s*$')
+OPERATIONAL_RULE_RE = re.compile(
+    r"(Git Safety|Public Issue Replies|Investigation Honesty|Verification|Response Style|Commit|Security)",
+    re.IGNORECASE,
+)
 
 
 def rel(path: Path, root: Path) -> str:
@@ -121,6 +125,20 @@ def claude_delegates_to_agents(path: Path) -> bool:
     return any("AGENTS.md" in line for line in meaningful)
 
 
+def has_operational_rules(path: Path) -> bool:
+    text = read(path, 40_000)
+    if not text:
+        return False
+    return len(set(m.group(1).lower() for m in OPERATIONAL_RULE_RE.finditer(text))) >= 2
+
+
+def looks_identity_only(path: Path) -> bool:
+    text = read(path, 40_000)
+    if not text:
+        return False
+    return "nian-identity:start" in text and not has_operational_rules(path)
+
+
 def parse_codex_config(
     path: Path,
 ) -> tuple[dict[str, str], list[str], list[str], list[str], list[str]]:
@@ -161,7 +179,7 @@ def parse_codex_config(
         if "=" not in line:
             continue
         key, value = [part.strip() for part in line.split("=", 1)]
-        if section == "features" and value.lower() == "true":
+        if section == "features" and value.split("#", 1)[0].strip().strip('"').lower() == "true":
             features.append(key)
         elif section.startswith('projects."') and key == "trust_level":
             project = section[len('projects."'): -1]
@@ -344,6 +362,25 @@ def main() -> int:
     if not global_claude.is_file() and not claude.is_file():
         claude_findings.append("Claude instruction surface not found")
 
+    if (
+        global_claude.is_file()
+        and has_operational_rules(global_claude)
+        and global_codex_agents.is_file()
+        and looks_identity_only(global_codex_agents)
+    ):
+        codex_findings.append(
+            "global Codex AGENTS.md has identity/memory context but lacks operational rules present in global Claude CLAUDE.md"
+        )
+    codex_config_text = read(codex_config) if codex_config.is_file() else ""
+    if (
+        'sandbox_mode = "danger-full-access"' in codex_config_text
+        and 'approval_policy = "never"' in codex_config_text
+        and "deny" not in codex_config_text.lower()
+    ):
+        codex_findings.append(
+            "Codex high-permission mode lacks a deny floor; add denies for secrets, credentials, pipe-to-shell installers, and outbound shells"
+        )
+
     conflict_findings: list[str] = []
     if agents.is_file() and claude.is_file() and not claude_delegates:
         conflict_findings.append("AGENTS.md and CLAUDE.md both exist; verify they do not diverge")

package/skills/health/scripts/check_maintainability.py

@@ -66,6 +66,12 @@ VERIFICATION_WORD_RE = re.compile(
 )
 
 
+# The file-walk helpers below are deliberately duplicated in
+# skills/check/scripts/audit_signals.py. Both scripts ship standalone
+# (see packaging.allowlist) and run inside an arbitrary target project, so
+# they import only stdlib. Do not hoist them into a shared scripts/
+# module: it is dev-only, not on the ship allowlist, and would couple a
+# standalone tool to the install layout.
 def rel(path: Path, root: Path) -> str:
     try:
         return path.resolve().relative_to(root).as_posix()

package/skills/health/scripts/collect-data.sh

@@ -8,7 +8,7 @@
 #   python3 not on PATH     -> MCP/hooks/allowedTools sections print "(unavailable)"; do not flag those areas
 #   settings.local.json absent -> hooks, MCP, allowedTools all show "(unavailable)"; normal for global-settings-only projects
 #   MEMORY.md path          -> built via sed on pwd; unusual chars produce wrong project key; verify manually if (none) seems wrong
-#   Conversation scope      -> only 2 most recent .jsonl files sampled; fewer than 2 = [LOW CONFIDENCE]
+#   Conversation scope      -> 2 most recent PREVIOUS .jsonl sampled (live session skipped); fewer than 2 = [LOW CONFIDENCE]
 #   MCP token estimate      -> assumes ~25 tools/server, ~200 tokens/tool; treat as directional, not precise
 #   Tier misclassification  -> .next/, __pycache__, .turbo/ can inflate file count; recheck manually if tier feels wrong
 set -euo pipefail
@@ -293,9 +293,10 @@ sample_jsonl_prefix() {
   ' "$file"
 }
 
-extract_messages_from_file() {
-  local file="$1"
-  sample_jsonl_prefix "$file" | jq -r '
+# Shared jq filter: collapse one transcript record to a single trimmed text
+# line, dropping meta and tool-result noise. Defined once and prepended to both
+# extract_* programs below so the flattening logic lives in exactly one place.
+JQ_FLATTEN='
     def flatten:
       if (.isMeta // false) or (.toolUseResult? != null) then
         empty
@@ -311,6 +312,11 @@ extract_messages_from_file() {
         | sub("^ "; "")
         | sub(" $"; "")
       end;
+'
+
+extract_messages_from_file() {
+  local file="$1"
+  sample_jsonl_prefix "$file" | jq -r "$JQ_FLATTEN"'
     (.type // .role // "") as $kind
     | (flatten) as $text
     | if ($text | length) == 0 then
@@ -329,22 +335,7 @@ extract_messages_from_file() {
 
 extract_signals_from_file() {
   local file="$1"
-  sample_jsonl_prefix "$file" | jq -r '
-    def flatten:
-      if (.isMeta // false) or (.toolUseResult? != null) then
-        empty
-      else
-        (.message.content // .content // .text // "")
-        | if type == "array" then
-            [ .[] | if type == "object" and .type == "text" then .text elif type == "string" then . else empty end ] | join(" ")
-          elif type == "string" then .
-          else empty
-          end
-        | gsub("[\\r\\n]+"; " ")
-        | gsub("  +"; " ")
-        | sub("^ "; "")
-        | sub(" $"; "")
-      end;
+  sample_jsonl_prefix "$file" | jq -r "$JQ_FLATTEN"'
     def is_correction:
       test("(?i)(\\bdon'\''t\\b|\\bdo not\\b|\\bplease don'\''t\\b|\\binstead\\b|\\bnext time\\b|\\bremember\\b|\\buse\\b.*\\binstead\\b|\\bnot\\b.*\\bbut\\b)")
       or test("(不要再|请不要|不要|别再|下次|记得|改成|改为|而不是|别用|去掉|统一成)");

package/skills/hunt/SKILL.md

@@ -11,6 +11,13 @@ Prefix your first line with 🥷 inline, not as its own paragraph.
 
 A patch applied to a symptom creates a new bug somewhere else.
 
+## Outcome Contract
+
+- Outcome: the root cause is identified before any fix is applied.
+- Done when: one sentence explains the cause, every observed symptom fits it, and the fix or handoff is verified against a reproducible check.
+- Evidence: source trace, repro command or UI path, logs or state, targeted test/build output, and runtime evidence for UI or native defects.
+- Output: root cause, fix or handoff, verification result, and any unswept sibling risks.
+
 **Do not touch code until you can state the root cause in one sentence:**
 > "I believe the root cause is [X] because [evidence]."
 
@@ -36,8 +43,11 @@ For `/hunt`, diagnostic constraints are `decision`, `preference`, and `principle
 - **After three failed hypotheses, stop.** Use the Handoff format below to surface what was checked, what was ruled out, and what is unknown. Ask how to proceed.
 - **Verify before claiming.** Never state versions, function names, or file locations from memory. Run `sw_vers` / `node --version` / grep first. No results = re-examine the path.
 - **External tool failure: diagnose before switching.** When an MCP tool or API fails, determine why first (server running? API key valid? Config correct?) before trying an alternative.
+- **System/tooling symptoms need a lower-layer baseline.** Before blaming the visible app, generated file, or top-level feature, measure the raw lower layer first: OS capture versus post-processing, runtime service versus UI, compiler/toolchain versus test assertion, network/API versus client handling. Retire hypotheses that the baseline disproves instead of circling them.
 - **Pay attention to deflection.** When someone says "that part doesn't matter," treat it as a signal. The area someone avoids examining is often where the problem lives.
 - **Visual/rendering bugs: static analysis first.** Trace paint layers, stacking contexts, and layer order in DevTools before adding console.log or visual debug overlays. Logs cannot capture what the compositor does. Only add instrumentation after static analysis fails.
+- **Behavioral / lifecycle / async bugs: instrument first, not after failure.** Window lifecycle, event delivery, navigation, focus, timer, state-machine, and async-ordering bugs almost never yield to static reading alone. Do not wait for a failed fix to add logs. The moment your hypothesis involves "this callback fires before/after that one", "this state should be X when Y runs", or "this object should still be alive here", **add the log immediately as part of forming the hypothesis**, before writing any fix. A hypothesis without runtime evidence is a guess; two guesses in a row is the hard-stop signal. Distinguish from visual-rendering bugs (compositor behavior needs DevTools, not logs) and pure-logic bugs (wrong formula, off-by-one) where static analysis is sufficient.
+- **Tuning magic numbers past round three: stop, unify.** When a spacing / sizing / threshold value has been adjusted three times and still looks wrong, the bug is structural, not numeric. Replace the N independent values with one named token (`Spacing.s4`, `--gap-content`, etc.) and verify the asymmetry was hiding a missing constraint. Asymmetry that survives tuning is structural; more tuning will not converge.
 - **Fix the cause, not the symptom.** If the fix touches more than 5 files, pause and confirm scope with the user.
 
 ## Fix Scope Discipline
@@ -48,6 +58,7 @@ If the bug genuinely needs a refactor first (e.g. the cause cannot be addressed
 
 Activate when: "以前是好的", "之前是好的", "used to work", "上一次提交还是对的", "broke after update", or the user remembers a specific good commit or version.
 
+0. Protect the user's worktree first: run `git status --short --branch -uall`. If modified, staged, or untracked files exist, do not bisect in the current checkout. Create a temporary detached worktree from the same HEAD, run bisect there, then `git bisect reset` and remove the temporary worktree when done. If a temporary worktree is impossible, stop and ask for explicit cleanup/stash approval.
 1. Find candidate good tag: `git tag --sort=-version:refname | head -10` or ask the user for the last known-good commit.
 2. Define a non-interactive pass/fail test command before starting bisect. Bisect is worthless without a reproducible check.
 3. Run: `git bisect start && git bisect bad HEAD && git bisect good <tag-or-hash>`
@@ -91,7 +102,7 @@ If the blast surfaces unrelated bugs, list them but do not fix in this PR unless
 
 ## Confirm or Discard
 
-Add one targeted instrument: a log line, a failing assertion, or the smallest test that would fail if the hypothesis is correct. Run it. If the evidence contradicts the hypothesis, discard it completely and re-orient with what was just learned. Do not preserve a hypothesis the evidence disproves.
+The instrument-first rule lives in Hard Rules (behavioral/async bugs) above; this is what to do with its result. Run the one probe that would fail if the hypothesis were wrong, then read it. If the evidence contradicts the hypothesis, discard it completely and re-orient on what the probe just showed. Do not stack a fix onto a disproven hypothesis, and do not keep one just because the code "looks like" the cause.
 
 ## Runtime Evidence Ladder
 
@@ -107,6 +118,26 @@ Compile-only is not enough for UI, native-app, visual, rendering, or generated-a
 
 For recurring classes of failures, load `references/failure-patterns.md` before adding a second fix.
 
+## Native App Freeze Mode
+
+Activate when a desktop or mobile native app reports beachball, not responding, tab-switch freeze, first-open lag, idle wake stall, overlay lockup, or a screenshot shows a frozen app.
+
+Evidence to collect before changing code:
+
+1. Exact user path and version: first launch versus warm launch, the tab or window transition, idle duration, permissions, display count, and any setting that makes the freeze disappear.
+2. Runtime capture while frozen: `sample <process>`, recent app logs, CPU and memory footprint, thread count, and whether the main thread is blocked, spinning, or allocating.
+3. First-frame surface: view body work, first `.task`, synchronous icon or metadata lookup, filesystem scans, URL parent walks, notification callbacks, and app/window wake handlers.
+4. Blast search after the fix: grep the same API shape across the repo, especially path parent walks, synchronous icon loading, metadata reads in render paths, and callbacks that run on the main thread.
+
+Common native freeze traps:
+
+- Launch, terminate, permission, audio, display, or workspace notifications doing path walks, icon lookup, filesystem scans, or process enumeration on the main thread.
+- First paint hydrating a full app list, directory tree, media thumbnail set, or system status table before showing an interactive shell.
+- An input-lock or full-screen overlay without a guaranteed teardown path for Escape, app deactivation, permission denial, process termination, and window close.
+- Timer or sampler work that survives hidden windows, long idle periods, sleep/wake, or app reactivation.
+
+Compile-only and source-only checks are insufficient for this mode. The outcome must include the runtime capture, the root-cause frame or state transition, the focused regression guard, and any sibling matches that were fixed or explicitly left safe.
+
 ## Targeted Logging
 
 Use logs as a scalpel, not as noise. Before adding a log, write the question it answers:
@@ -128,6 +159,7 @@ If adding logs changes the behavior, treat that as evidence of a timing, lifecyc
 |---------------|------|
 | Patched client pane instead of local pane | Trace the execution path backward before touching any file |
 | MCP not loading, switched tools instead of diagnosing | Check server status, API key, config before switching methods |
+| Blamed the visible app before measuring the raw system/tooling layer | Measure the lower layer first, then retire ruled-out hypotheses explicitly |
 | Orchestrator said RUNNING but TTS vendor was misconfigured | In multi-stage pipelines, test each stage in isolation |
 | Race condition diagnosed as a stale-state bug | For timing-sensitive issues, inspect event timestamps and ordering before state |
 | Added logs everywhere and still could not explain the bug | Rewrite each log as a yes/no question. Delete logs that do not rule a hypothesis in or out |

package/skills/hunt/references/failure-patterns.md

@@ -56,6 +56,51 @@ Checks:
 - Reject paths outside the allowed root after symlink resolution.
 - Reproduce from a non-default cwd and through any UI entry point that supplies paths.
 
+## CLI Effect Scope Drift
+
+Signals: preview, dry-run, size, count, or report output is computed from one predicate, but execution mutates a broader or different set.
+
+Checks:
+- Trace display, dry-run, and mutation predicates to the same source of truth.
+- Compare planned paths or records with executor input in a regression test.
+- Assert partial failures report the exact skipped and completed items.
+
+## CLI Wrapper Or PATH Drift
+
+Signals: source-tree invocation works, but the installed command, package wrapper, PATH shim, completion, or package-manager install path runs old code or a different binary.
+
+Checks:
+- Inspect built package contents, shebang, executable bit, and wrapper target.
+- Reproduce through a temp prefix or package-manager install path, not only from source.
+- Check PATH order and use absolute system-tool paths where wrappers should not intercept.
+
+## Interactive Stdin Or TTY Hang
+
+Signals: CI stalls, spinner never finishes, a subprocess reads from the script body, or an auth prompt appears in non-interactive mode.
+
+Checks:
+- Reproduce with stdin redirected and with TTY/non-TTY paths separated.
+- Add test-mode or no-auth guards around real prompts and system changes.
+- Stub external prompt tools through PATH when timeout wrappers exec real binaries.
+
+## Signal Or Partial-Failure Mapping
+
+Signals: cancel, timeout, SIGINT, or SIGTERM is reported as success or as a normal business failure; temp files, locks, or operation logs make retries look complete.
+
+Checks:
+- Classify interrupted execution separately from success and expected validation failures.
+- Assert temp cleanup, lock release, and operation-log state after interruption.
+- Test retry and idempotency after a partial write.
+
+## CLI Stream Contract Regression
+
+Signals: automation breaks after human logs, progress output, JSON shape, stdout/stderr routing, or exit-code behavior changes.
+
+Checks:
+- Assert exit code, stdout, and stderr separately in CLI tests.
+- Keep human diagnostics off stdout for machine-readable modes.
+- Snapshot or parse JSON/schema output and include non-interactive coverage.
+
 ## Snapshot Rebuild Drops Carried Field
 
 Signals: live data shows up at the data source and on the wire but a downstream view sees it empty; the field has a default value (`var x: [T] = []`, `var y: Int? = nil`) that lets memberwise init compile without it; the symptom appears only on the path where the snapshot is rebuilt (icon resolution, decoration, redaction), not on a fresh fetch.
@@ -73,3 +118,12 @@ Checks:
 - Read the tool's man page for cold-start semantics. `top -l 2`, `iostat -d 2`, `vm_stat 1 2`, etc. all share this shape.
 - Slice the output to the latest sample (`.suffix(perSampleSize)` on parsed lines, or look for the second instance of the header row).
 - When in doubt, raise `-l` to 3 and confirm sample 2 and 3 agree; sample 1 stays zero.
+
+## Aggregation Key Variant
+
+Signals: a count, log roll-up, event tally, or per-category breakdown is short by some entries; the missing items share a trait (a system-derived path, a localized string, a prefixed command name); the base-form key matches but a derived variant (`<base>-system`, a suffix, a prefix) is silently dropped.
+
+Checks:
+- Before adding a category, grep every write site that produces this class of key and enumerate the real variants, not just the base form.
+- Match with `hasPrefix` / a regex / an explicit variant list rather than exact equality on the base key.
+- Add a fixture row for each known variant so a future key shape that escapes the matcher fails the test instead of the aggregate.