@softspark/ai-toolkit 4.30.3 → 4.32.0

package/CHANGELOG.md

@@ -7,6 +7,129 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v4.32.0 - Context budget: scoped rules, scoped language skills, doctor budget checks (2026-09-04)
+
+### Added
+
+- **`install --language-skills detected|all`.** Language knowledge skills
+  (`<lang>-rules`, `<lang>-patterns`) for languages no registered project uses
+  are turned off through `skillOverrides` in `~/.claude/settings.json`. The
+  entries the toolkit wrote are tracked in `state.json` and restored when a
+  newly registered project brings the language back; a user's own override is
+  never touched; with no registered project on disk nothing is disabled. `all`
+  restores everything and persists the choice.
+- **`doctor` check 12, Context Budget.** Estimated resident tokens of the
+  model-visible skill listing (against `skillListingBudgetFraction`), the agent
+  listing, and always-loaded user memory, plus skills with zero recorded use in
+  both Claude Code's counters and the toolkit's `stats.json`. Read-only; prints
+  the `skillOverrides` key to paste.
+- **`doctor` check 13, Permission Rules.** Warns on `permissions.allow`
+  wildcards that pre-approve execution or writes: interpreters, task runners,
+  package installs, `gh api`, `curl`/`wget`, `git fetch`/`pull`, destructive
+  commands, `find -exec`. Never edits.
+- **`validate.py` skill description budget.** Error over 1024 characters (the
+  Agent Skills cap), warning over 400, and an error for an unquoted description
+  containing `: ` or ` #` (strict YAML drops every field, `allowed-tools`
+  included). Applied to plugin-pack skills too.
+- **`git-team` common rule.** Branching, pull-request, and review conventions
+  moved out of `git-workflow` into a rule that ships with `--profile strict`
+  only, via a new `profiles:` frontmatter gate. See `DECISIONS.md`.
+- **One frontmatter parser.** `scripts/frontmatter.py` now parses the whole
+  toolkit subset (scalars, quoted scalars, `>-`/`|` blocks, block and flow
+  lists, nested maps) strictly and is the only parser; twelve private
+  strip/parse copies in `validate.py`, `doctor.py`, `install_steps/ai_tools.py`,
+  `claude_app.py`, `compile_slm.py`, `surface_manifest.py`, `instruction_core.py`,
+  `check_split.py`, `codex_skill_adapter.py`, `generate_opencode_skills.py`, and
+  `generate_language_rules_skills.py` are gone. Every shipped `app/` and `kb/`
+  Markdown file parses under the strict grammar (pytest corpus test).
+- **Repo dev tooling, stdlib runtime.** `requirements-dev.txt` + `pytest.ini`
+  + `mypy.ini` (pytest, ruff, mypy) and a `python-quality` CI job:
+  `npm run test:py` (348 pytest tests under `tests/python/`), `npm run lint:py`
+  (ruff `E,F`, rule set in `package.json`), `npm run typecheck:py` (mypy
+  `--strict` over an allowlist). No `pyproject.toml`: the toolkit's own
+  `quality-gate.sh` reads one as "Python project, run `ruff check .`", which
+  is not what an npm-first repo wants. Nothing is added to the published
+  package or to user machines. See `DECISIONS.md` for why no runtime
+  dependency.
+
+### Changed
+
+- **Common rules are path-scoped from their source.** `app/rules/common/*.md`
+  may declare `paths:`; the generated `.claude/rules/ai-toolkit-*.md` copies it.
+  `testing` and `performance` load only for matching files; `coding-style`,
+  `git-workflow`, and `security` stay always-on. The `.claude/CLAUDE.md` index
+  now lists which rules are always-on and which are path-scoped instead of
+  claiming lazy loading for all of them.
+- **Stop hooks `quality-check.sh` and `save-session.sh` run with
+  `"async": true`.** Both are advisory and always exit 0; the linter was the
+  bulk of a 3.3 s median Stop chain. `quality-gate.sh` (exit 2) and
+  `stop-search-check.sh` stay synchronous.
+- **`git-workflow` is the solo-safe core** (commit format, no secrets, `main`
+  deployable, tags, recovery). Version 2.0.0.
+
+### Fixed
+
+- **`quality-gate.sh` runs ruff only for projects that configured it.** A bare
+  `pyproject.toml` (build metadata, pytest/mypy tables) used to trigger
+  `ruff check .` on every Stop under whatever ruff configuration the machine
+  resolves; found when this repository's own gate went red on 348 unrelated
+  findings. Ruff now needs `ruff.toml`, `.ruff.toml`, or a `[tool.ruff]` table.
+- **Codex/DSH skill sync no longer flattens nested frontmatter.** Native
+  (non-adapted) skills had their frontmatter re-rendered line by line, which
+  turned a `hooks:` block into stray top-level `PreToolUse:` / `- matcher:`
+  lines. The frontmatter now passes through verbatim.
+- **Hook merge de-duplicates legacy untagged toolkit hooks by command identity.**
+  Scheduling fields (`async`, `timeout`, `statusMessage`, ...) no longer defeat
+  the match, so adding one in `app/hooks.json` does not leave existing installs
+  running the old and the new copy side by side. Fixed in both
+  `scripts/merge-hooks.py` and `scripts/inject_hook_cli.py`.
+- **Test count.** Bats increased from 1931 to 1966; 348 pytest tests added under
+  `tests/python/` (run by the new `python-quality` CI job).
+
+### Ecosystem
+
+- Ecosystem doctor run for this minor release: 12 tools drifted since the
+  v4.30.3 snapshot, all class A (content edits with no heading delta) or class
+  C (Cline gained a "Resources" heading, Codex CLI a "ChatGPT Work" heading;
+  neither adds a surface the toolkit integrates). Tracked versions moved:
+  Claude Code 2.1.252 -> 2.1.260 (its hooks documentation now lists the
+  `async` command-hook field this release relies on), Codex CLI 0.151.0 ->
+  0.153.2. No generator changed; snapshot refreshed.
+
+## v4.31.0 - Toolkit rules reach every editor (2026-09-03)
+
+### Added
+
+- The five top-level rule files in `app/rules/` ship as knowledge skills,
+  generated by `scripts/generate_toolkit_rules_skills.py` and wired as
+  `npm run generate:toolkit-rules`. Ten bats tests cover generation,
+  idempotence, and the content of the new rule.
+- `app/rules/edit-discipline.md`: change files with the `edit` and `write`
+  tools rather than rewriting them through `bash`, and show `git diff` before
+  reporting a file-changing task as done.
+
+### Fixed
+
+- **Every toolkit rule was inert outside Claude Code.** They existed only as
+  Claude Code user-level files under `~/.claude/rules/`, and the global
+  `CLAUDE.md` carried a pointer to them rather than their content — a Claude
+  Code idiom that assumes `/memory`. DeepSeek Harness reads `AGENTS.md`,
+  `AGENTS.local.md`, `CLAUDE.md` and `CLAUDE.local.md` and has no
+  rules-directory support at all, so under DSH the rules were named in an
+  injected file and never loaded. That is why an agent there kept rewriting
+  tracked files with `sed` while a rule forbidding exactly that sat unread.
+
+  Skills are discovered by every editor that reads the shared catalogue, and
+  the catalogue injects each skill's *description* into the session. The
+  descriptions are therefore written as the rule itself in one imperative
+  line: in context whether or not the body is loaded.
+
+  Verified against a live DSH session — the agent loaded `edit-discipline`
+  unprompted, used `write` and `edit` instead of `bash`, and rendered the
+  change as a diff.
+
+---
+
 ## v4.30.3 - Copilot health-check compatibility (2026-09-02)
 
 ### Fixed

package/README.md

@@ -1,30 +1,35 @@
 # ai-toolkit
 
-> AI coding toolkit with machine-enforced safety, 109 skills, 44 agents, lifecycle hooks, persona presets, opt-in plugin packs, and benchmark tooling. DSH is available as a separate explicit developer-preview target.
+> AI coding toolkit with machine-enforced safety, 114 skills, 44 agents, lifecycle hooks, persona presets, opt-in plugin packs, and benchmark tooling. DSH is available as a separate explicit developer-preview target.
 
 [![CI](https://github.com/softspark/ai-toolkit/actions/workflows/ci.yml/badge.svg)](https://github.com/softspark/ai-toolkit/actions/workflows/ci.yml)
 [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
-[![Skills](https://img.shields.io/badge/skills-109-brightgreen)](app/skills/)
+[![Skills](https://img.shields.io/badge/skills-114-brightgreen)](app/skills/)
 [![Agents](https://img.shields.io/badge/agents-44-blue)](app/agents/)
-[![Tests](https://img.shields.io/badge/tests-1921%20passing-success)](tests/)
-
-## What's New in v4.30.3
-
-**v4.30.3** corrects the post-release health check for the managed DSH and
-plugin-owned MCP release:
-
-- `ai-toolkit doctor` now extracts `1.0.80` from the official Copilot CLI output
-  `GitHub Copilot CLI 1.0.80.` instead of treating sentence punctuation as an
-  invalid SemVer suffix.
-- Complete-token validation remains fail closed for malformed versions such as
-  `1.2.3.4`, invalid prerelease identifiers, and leading-zero numeric fields.
-- The DSH cold-add regression keeps its legacy-timeout coverage with macOS CI
-  process-startup headroom, removing the release-blocking timing flake.
-- Release tags now require green Ubuntu and macOS branch CI for the exact commit
-  before the publish workflow can start.
-- The release retains the explicit DSH lifecycle, plugin-owned MCP/rules, portable
-  recovery gates, and the exact DSH package set published in v4.30.2. Test count:
-  1920 -> 1921.
+[![Tests](https://img.shields.io/badge/tests-1966%20passing-success)](tests/)
+
+## What's New in v4.32.0
+
+**v4.32.0** cuts what every session pays for before you type, and adds the
+checks that keep it cut:
+
+- Common rules are path-scoped from their source: `testing` and `performance`
+  load only for matching files, and the project `.claude/CLAUDE.md` index says
+  which rules are always-on instead of claiming lazy loading for all of them.
+- Language knowledge skills follow your projects: `install --language-skills
+  detected` (default) turns off `<lang>-rules`/`<lang>-patterns` skills for
+  languages no registered project uses, reversibly, and restores them when a
+  project brings the language back.
+- `ai-toolkit doctor` gains a Context Budget check (est. resident tokens,
+  zero-use skills) and a Permission Rules check (over-broad `permissions.allow`
+  wildcards). Both read-only.
+- One strict frontmatter parser replaces twelve private copies; `validate.py`
+  now rejects descriptions over 1024 characters or unquoted ones containing
+  `: `. Every shipped Markdown file parses under the strict grammar.
+- Team-only git conventions moved to a `git-team` rule that ships with
+  `--profile strict`; `quality-gate.sh` lints with ruff only when the project
+  configured ruff; advisory Stop hooks run in the background. Test count:
+  1931 -> 1966 bats + 348 pytest.
 
 See [CHANGELOG.md](CHANGELOG.md) for full history.
 
@@ -60,7 +65,9 @@ ai-toolkit install
 npx @softspark/ai-toolkit install
 ```
 
-**That's it.** Claude Code picks up 109 skills, 44 agents, quality hooks, and the safety constitution automatically.
+**That's it.** Claude Code picks up 114 skills, 44 agents, quality hooks, and the safety constitution automatically.
+
+Language knowledge skills (`rust-rules`, `kotlin-patterns`, ...) are scoped to the languages your registered projects use: once you have run `ai-toolkit install --local` in at least one project, the global install turns the other languages' skills off through `skillOverrides` in `~/.claude/settings.json` so their descriptions stop loading into every session. A new project in a new language turns its skills back on. `ai-toolkit install --language-skills all` keeps every language skill on and remembers that choice; `ai-toolkit doctor` shows the resulting context budget.
 
 **Windows:** WSL is the recommended runtime. Native Windows works when Git Bash is available for hook scripts; dependency hints cover `winget`, Chocolatey, and Scoop. See [Windows Support](kb/reference/windows-support.md).
 
@@ -186,7 +193,7 @@ See [CLI Reference](kb/reference/cli-reference.md) for all commands and options.
 |-----------|-------|-------------|
 | `skills/` (task) | 32 | Slash commands: `/commit`, `/build`, `/deploy`, `/test`, `/mcp-builder`, ... |
 | `skills/` (hybrid) | 31 | Slash commands with agent knowledge base |
-| `skills/` (knowledge) | 46 | Domain knowledge auto-loaded by agents (includes 13 `<lang>-rules` skills) |
+| `skills/` (knowledge) | 51 | Domain knowledge auto-loaded by agents (includes 13 `<lang>-rules` skills) |
 | `agents/` | 44 | Specialized agents across 10 categories |
 | `hooks/` | 28 entries / 14 events + statusLine | Quality gates, path safety, prompt governance, loop guard, session lifecycle |
 | `plugins/` | 2 packs | Opt-in packs that install files of their own (memory, enterprise) |
@@ -202,7 +209,7 @@ See [CLI Reference](kb/reference/cli-reference.md) for all commands and options.
 ai-toolkit/
 ├── app/
 │   ├── agents/          # 44 agent definitions
-│   ├── skills/          # 109 skills (task / hybrid / knowledge)
+│   ├── skills/          # 114 skills (task / hybrid / knowledge)
 │   ├── rules/           # Source rules synced into Claude/editor rule files
 │   ├── hooks/           # Hook scripts (29 entries, 14 lifecycle events)
 │   ├── claude-app/      # Generated Chat/Cowork plugin rules, hooks, instructions
@@ -341,7 +348,7 @@ Need multi-agent coordination?
 | opencode Compatibility | [kb/reference/opencode-compatibility.md](kb/reference/opencode-compatibility.md) |
 | GitHub Copilot Compatibility | [kb/reference/copilot-compatibility.md](kb/reference/copilot-compatibility.md) |
 | DSH Compatibility | [kb/reference/dsh-compatibility.md](kb/reference/dsh-compatibility.md) |
-| Maintenance SOP | [kb/procedures/maintenance-sop.md](kb/procedures/maintenance-sop.md) |
+| Maintenance SOP | [kb/procedures/sop-maintenance.md](kb/procedures/sop-maintenance.md) |
 
 ---
 

package/app/.claude-plugin/plugin.json

@@ -3,7 +3,7 @@
   "name": "ai-toolkit",
   "displayName": "AI Toolkit",
   "description": "Professional-grade engineering skills, agents, rules, and lifecycle guardrails for Claude Code, Claude Chat, and Cowork.",
-  "version": "4.30.3",
+  "version": "4.32.0",
   "author": {
     "name": "SoftSpark",
     "url": "https://github.com/softspark"

package/app/agents/code-reviewer.md

@@ -59,6 +59,13 @@ Before reviewing, gather context using available tools:
 - Secrets management
 - IAM/permissions scope
 
+### 5. Frontend & UI Craft (Anti-Slop Audit)
+- Generic AI tells: gradient text headlines, purple/blue washes, 3-column card clichés, nested cards
+- Missing interactive states: lacking focus-visible, active, disabled, loading, error, success
+- Input stability: layout shifts caused by changing border-widths
+- Mobile responsiveness: horizontal scroll risk, clickable affordance text wrapping
+- Fabricated content: invented metrics, fake testimonials, mock OS/browser chrome
+
 ## Review Checklist
 
 ### Security (check first)
@@ -78,6 +85,13 @@ Before reviewing, gather context using available tools:
 - [ ] Tests cover critical paths
 - [ ] Documentation is accurate
 
+### Frontend & UI Craft
+- [ ] No gradient headlines (`background-clip: text`) or purple/blue gradient heroes
+- [ ] Interactive elements implement all 8 states
+- [ ] Inputs maintain constant 1px border-width (zero layout shift)
+- [ ] Mobile responsive: `overflow-x: clip`, single-line button text
+- [ ] No invented metrics, fake testimonials, or mock chrome
+
 ### Performance
 - [ ] No obvious N+1 queries
 - [ ] Resources are properly cleaned up

package/app/agents/frontend-specialist.md

@@ -104,15 +104,17 @@ hybrid_search_kb("[UI patterns, accessibility]")
 - Image optimization
 - Bundle analysis
 
-### Design Craft (impeccable-inspired — guidance, not mandate)
-Frontend is craft as much as system. Seven domains, one concrete rule each:
-- **Typography** — reject Arial/Inter defaults; pair display + text on a modular scale; enable OpenType features when they serve content
-- **Color** — prefer OKLCH; tint neutrals; no pure `#000`; verify gray-on-color contrast
-- **Spatial** — consistent spacing scale (4/8/12/16/24/32/48); do not nest cards in cards
-- **Motion** — no bounce/elastic easing; stagger reveals; respect `prefers-reduced-motion`
-- **Interaction** — replace default focus outlines, never just remove; loaders show progress; errors name the remedy
-- **Responsive** — mobile-first; `clamp()` for fluid type; container queries for component-level behavior
-- **UX Writing** — button labels = verb + object; errors = cause + remedy; empty states earn their screen
+### Design Craft & Anti-Slop Standards
+Frontend is craft as much as system. Core non-negotiables:
+- **Typography (2+1 Rule)** — Reject Inter/system-default with no pairing; pair display + text on a modular scale; display headers are strictly roman (`font-style: normal`, never italic emphasis words in headlines); max 3 font families, outlier face in at most 2 slots.
+- **Color & Locked Tokens** — Prefer OKLCH; tint neutral surfaces toward anchor hue (>=0.005 chroma); no pure `#000`/`#fff`; lock tokens to CSS variables (`var(--color-accent)`) without inline hex/rgb improvisation; accent area <=5% of viewport.
+- **Spatial & Macrostructures** — Reject default-attractor rhythm (Hero → 3 features → CTA → footer); choose distinct macrostructures (Bento Grid, Long Document, Marquee, Stat-Led, Workbench, FAQ, Manifesto); do not nest cards in cards or use thick side stripes.
+- **8 Interactive States** — Every interactive component MUST implement all 8 states: default, hover, focus-visible, active, disabled, loading, error, success.
+- **Input Stability (Zero Layout Shift)** — Constant 1px `border-width` across all states; reserve 2px transparent outline at rest; input height = button height (>=44px floor); reserve 1lh helper text slot.
+- **Responsive Non-Negotiables** — Mobile-first (320px–768px verified); `overflow-x: clip` on `html` and `body`; clickable buttons/links never wrap to 2 lines; image grid tracks use `minmax(0, 1fr)`.
+- **Motion** — No bounce/elastic easing; GPU-accelerated transforms; faster exit than enter; respect `prefers-reduced-motion`.
+- **Content Honesty & No Fake Chrome** — Never invent metrics, testimonials, or fake logos; do not hand-draw fake browser/phone frames.
+- **Pre-Emit Self-Critique** — Score output 1–5 on Philosophy, Hierarchy, Execution, Specificity, Restraint, Variety (all >=3).
 
 ### AI-Native UI (inspired by 21st.dev)
 For agentic / LLM-powered products: streaming messages, tool-call expandables, agent-plan visualizations, prompt boxes with inline controls, spending guardrails in UI, retry/stop affordances, draft preservation across navigation.
@@ -122,13 +124,13 @@ For agentic / LLM-powered products: streaming messages, tool-call expandables, a
 ### Component Design
 ✅ Single responsibility per component
 ✅ Props interface with TypeScript
-✅ Accessible by default (ARIA, keyboard)
-✅ Responsive mobile-first
+✅ Accessible by default (ARIA, keyboard, focus-visible)
+✅ Responsive mobile-first with 8 interactive states
 ✅ Error boundaries for failure handling
 
 ❌ Don't create god components
-❌ Don't inline all styles
-❌ Don't skip accessibility
+❌ Don't inline all styles or improvise tokens mid-render
+❌ Don't skip accessibility or interactive states
 
 ### State Management
 ✅ Colocate state near usage
@@ -138,7 +140,7 @@ For agentic / LLM-powered products: streaming messages, tool-call expandables, a
 
 ### Performance
 ✅ Lazy load routes and heavy components
-✅ Optimize images (next/image, @nuxt/image)
+✅ Optimize images (next/image, @nuxt/image, fetchpriority for LCP)
 ✅ Minimize bundle size
 ✅ Use virtualization for long lists
 
@@ -147,18 +149,19 @@ For agentic / LLM-powered products: streaming messages, tool-call expandables, a
 ### Engineering
 ❌ **Prop drilling** → Use context or state management
 ❌ **Unnecessary re-renders** → Memoize appropriately
-❌ **Layout shift** → Reserve space, use skeleton
+❌ **Layout shift** → Reserve space, use skeleton, constant 1px input borders
 ❌ **Giant components** → Split into smaller units
 
-### Taste (the LLM defaults — reject on sight)
-❌ Arial / Inter / system-default type with no intentional pairing
-❌ Gray text on colored backgrounds (contrast failure)
-❌ Pure `#000` black — use tinted near-black
-❌ Cards nested inside cards — flatten with type + spacing hierarchy
-❌ Bounce / elastic easing curves (feel dated)
-❌ Purple gradients (the generic-LLM tell)
-❌ Motion that ignores `prefers-reduced-motion`
-❌ Generic stock illustrations for empty states
+### Taste & AI-Slop (Reject on Sight)
+❌ Saturated purple-to-pink/blue full-bleed gradient heroes or gradient headline text (`background-clip: text`)
+❌ 3-equal-column cards with icon-above-heading tiles (the generic AI template)
+❌ Cards nested inside cards or cards with thick side-stripe borders
+❌ Missing interactive states (only styling default + hover, forgetting focus/active/disabled/error/loading)
+❌ Changing `border-width` on input focus/hover causing layout shifts
+❌ Italic headings or single-word italic emphasis in headlines
+❌ Pure `#000` / `#fff` flat backgrounds with zero tint
+❌ Invented metrics ("+47% conversion"), fake testimonials, or placeholder stock logos
+❌ Re-drawn fake browser bars / phone chrome
 ❌ Emoji standing in for proper icons
 
 ## 🔴 MANDATORY: Post-Code Validation

package/app/agents/infrastructure-validator.md

@@ -18,7 +18,7 @@ Ensure deployments are successful, services are healthy, and rollback procedures
 ```python
 # ALWAYS call this FIRST - NO TEXT BEFORE
 smart_query(query="deployment validation: {service}")
-get_document(path="procedures/maintenance-sop.md")
+get_document(path="procedures/sop-maintenance.md")
 hybrid_search_kb(query="health check {service}", limit=10)
 ```
 
@@ -172,7 +172,7 @@ deployment:
   status: successful
   rollback_tested: yes
 kb_references:
-  - kb/procedures/maintenance-sop.md
+  - kb/procedures/sop-maintenance.md
 next_agent: documenter
 instructions: |
   Update deployment documentation with any changes

package/app/claude-app/hooks/hooks.json

@@ -151,7 +151,8 @@
         "hooks": [
           {
             "type": "command",
-            "command": "AI_TOOLKIT_DIR=\"${CLAUDE_PLUGIN_ROOT}\" \"${CLAUDE_PLUGIN_ROOT}/hooks/quality-check.sh\""
+            "command": "AI_TOOLKIT_DIR=\"${CLAUDE_PLUGIN_ROOT}\" \"${CLAUDE_PLUGIN_ROOT}/hooks/quality-check.sh\"",
+            "async": true
           }
         ]
       },
@@ -160,7 +161,8 @@
         "hooks": [
           {
             "type": "command",
-            "command": "AI_TOOLKIT_DIR=\"${CLAUDE_PLUGIN_ROOT}\" \"${CLAUDE_PLUGIN_ROOT}/hooks/save-session.sh\""
+            "command": "AI_TOOLKIT_DIR=\"${CLAUDE_PLUGIN_ROOT}\" \"${CLAUDE_PLUGIN_ROOT}/hooks/save-session.sh\"",
+            "async": true
           }
         ]
       },

package/app/claude-app/skills/ai-toolkit-rules/SKILL.md

@@ -23,7 +23,10 @@ Shared AI development toolkit — lifecycle hooks, safety constitution, multi-pl
 
 ## Path Safety
 - NEVER guess or hallucinate user home directory paths
-- Use `~` or `$HOME` instead of hardcoded `/Users/<username>/` or `/home/<username>/`
+- Use `~` or `$HOME` instead of a hardcoded `/Users` or `/home` prefix followed
+  by a user name. The literal prefix is deliberately not written out here: the
+  plugin export scans shipped files for exactly that pattern, so an example of
+  the mistake would be indistinguishable from the mistake.
 - When an absolute path is needed, run `echo $HOME` first to get the correct value
 
 ## User Preferences
@@ -32,6 +35,46 @@ Shared AI development toolkit — lifecycle hooks, safety constitution, multi-pl
 - **Methodology:** Provide >=3 alternatives. Use Socratic questioning.
 - **Review:** Apply "Devil's Advocate" critique to decisions.
 
+## Source: `app/rules/edit-discipline.md`
+
+# Edit Discipline & Reviewable Changes
+
+## Edit files with the editing tools, not the shell
+
+Use the `edit` and `write` tools to change a file. Do not rewrite tracked files
+through `bash` with `sed`, `awk`, `tee`, a heredoc, or `>` redirection.
+
+This is not a style preference. A shell rewrite is opaque to the host: the
+session records a command, not a change. An `edit` call records which file
+changed and how, so the interface can render it, a reviewer can read it, and a
+later turn can cite it. A `sed` line records none of that, and the only way to
+find out what happened is to read the file again.
+
+The shell remains correct for what it is for: running builds, tests, linters,
+git, package managers, and generators that own their own output.
+
+## Show the change before calling the work done
+
+Before reporting a file-changing task as finished, show what changed:
+
+```bash
+git diff -- <paths>          # tracked files
+git status --short           # what is new or removed
+```
+
+Paste the diff into the reply, or state precisely why it is too large and
+summarise it by file with the counts. A task that reports success without
+showing the change asks the reader to take the result on trust, and the reader
+is the one who has to decide whether to commit it.
+
+For an untracked file, show the content you wrote, not a description of it.
+
+## Why both halves matter together
+
+Editing through the tools makes a change *recordable*; showing the diff makes it
+*reviewed*. Either alone leaves the person deciding whether to ship blind to
+something they are accountable for.
+
 ## Source: `app/rules/git-conventions.md`
 
 # Git Conventions
@@ -164,27 +207,22 @@ Default response mode for this project is **concise**. The `brand-voice` skill (
 - Magic numbers/strings: use named constants.
 - Mutable global state: use dependency injection instead.
 
-## Source: `app/rules/common/git-workflow.md`
+## Source: `app/rules/common/git-team.md`
 
-# Git Workflow Rules
+# Git Team Workflow Rules
 
-## Commit Messages
-- Use conventional commits: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`.
-- First line: imperative mood, max 72 chars (`feat: add user registration endpoint`).
-- Body (optional): explain *why*, not *what*. The diff shows what.
-- Reference tickets: `fix: prevent duplicate orders (PROJ-456)`.
-
-## Commit Practices
-- Commit small, atomic changes. One commit = one logical change.
-- Never commit: secrets, `.env` files, build artifacts, large binaries.
-- Never commit broken code to `main`. Use feature branches.
-- Squash fixup commits before merging to keep history clean.
+These rules assume more than one person merges into `main`. They ship only with
+the `strict` profile; a solo maintainer who commits straight to `main` is not
+doing anything wrong, and a reviewer that keeps flagging "use a feature branch"
+in that setting is noise. The solo-safe core (commit format, no secrets, no
+force-push) lives in `git-workflow`.
 
 ## Branching
-- `main` is always deployable. Protect it with required reviews and CI.
-- Feature branches: `feat/user-registration`, `fix/order-total-calc`.
+- Protect `main` with required reviews and CI. Never commit broken code to it.
+- Work on feature branches: `feat/user-registration`, `fix/order-total-calc`.
+- Rebase feature branches on `main` before opening a PR to keep linear history.
+- Squash fixup commits before merging to keep history clean.
 - Delete branches after merge. Stale branches are clutter.
-- Rebase feature branches on main before PR to keep linear history.
 
 ## Pull Requests
 - Keep PRs small: <400 lines changed. Split large features into stacked PRs.
@@ -197,6 +235,25 @@ Default response mode for this project is **concise**. The `brand-voice` skill (
 - Approve with comments if nits only. Block for: bugs, security, missing tests.
 - Respond to reviews within 24 hours. Do not let PRs rot.
 
+## Source: `app/rules/common/git-workflow.md`
+
+# Git Workflow Rules
+
+Solo-safe core: everything here holds whether one person or twenty merge into
+`main`. Branching, pull-request, and review conventions for teams live in
+`git-team` and ship only with the `strict` profile.
+
+## Commit Messages
+- Use conventional commits: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`.
+- First line: imperative mood, max 72 chars (`feat: add user registration endpoint`).
+- Body (optional): explain *why*, not *what*. The diff shows what.
+- Reference tickets: `fix: prevent duplicate orders (PROJ-456)`.
+
+## Commit Practices
+- Commit small, atomic changes. One commit = one logical change.
+- Never commit: secrets, `.env` files, build artifacts, large binaries.
+- `main` is always deployable: run the project's gates before every commit that lands there.
+
 ## Tags and Releases
 - Use semantic versioning: MAJOR.MINOR.PATCH.
 - Tag releases: `git tag v1.2.3`. Automate changelog from commits.

package/app/hooks/quality-gate.sh

@@ -98,8 +98,15 @@ if [ -f .claude/test-cohesion-map.json ] || \
 fi
 
 if [ -f pyproject.toml ] || [ -f setup.py ]; then
-    if require_command ruff; then
-        run_required "ruff found errors" "head -30" ruff check .
+    # Lint only what the project itself configured. A bare pyproject.toml
+    # (build metadata, pytest/mypy tables) says nothing about ruff, and running
+    # `ruff check .` under whatever config the machine resolves turns the Stop
+    # gate red on findings the project never signed up for (v4.32.0 postmortem:
+    # 348 findings in a repo whose ruff rule set lives in a package.json script).
+    if [ -f ruff.toml ] || [ -f .ruff.toml ] || grep -qs '^\[tool\.ruff' pyproject.toml; then
+        if require_command ruff; then
+            run_required "ruff found errors" "head -30" ruff check .
+        fi
     fi
     if [ -d src ] && [ "$PROFILE" = "strict" ]; then
         if require_command mypy; then

package/app/hooks.json

@@ -167,7 +167,8 @@
                 "hooks": [
                     {
                         "type": "command",
-                        "command": "\"$HOME/.softspark/ai-toolkit/hooks/quality-check.sh\""
+                        "command": "\"$HOME/.softspark/ai-toolkit/hooks/quality-check.sh\"",
+                        "async": true
                     }
                 ]
             },
@@ -177,7 +178,8 @@
                 "hooks": [
                     {
                         "type": "command",
-                        "command": "\"$HOME/.softspark/ai-toolkit/hooks/save-session.sh\""
+                        "command": "\"$HOME/.softspark/ai-toolkit/hooks/save-session.sh\"",
+                        "async": true
                     }
                 ]
             },

package/app/personas/frontend-lead.md

@@ -8,26 +8,34 @@
 - Names specific failure modes; rejects vague advice like "use good design"
 
 ## Design Craft Priorities
-Impeccable frontend covers seven domains. One concrete rule per domain (guidance, not mandate):
+Core frontend craft covers eight domains (guidance, not mandate):
 
-1. **Typography** — Reject Arial/Inter as defaults. Pair display + text faces on a modular scale (e.g., 1.125 / 1.25 / 1.333). Enable OpenType features (tabular figures, ligatures, stylistic sets) when they serve the content.
-2. **Color & Contrast** — Prefer OKLCH over HSL/RGB for perceptual uniformity. Tint neutrals toward the brand hue (pure grays feel sterile). Never pure `#000` — use tinted near-black. Gray-on-color frequently fails contrast; verify.
-3. **Spatial** — Consistent spacing scale (e.g., 4/8/12/16/24/32/48), not ad-hoc pixel values. Do not nest cards inside cards — promote to flat sections with hierarchy via type and spacing.
-4. **Motion** — Easing conveys mass and intent. Avoid bounce/elastic curves (feel dated). Stagger sequential reveals. Always respect `prefers-reduced-motion`.
-5. **Interaction** — Replace default focus outlines; never just remove them. Loading states show progress, not just spinners. Errors name the remedy, not just the failure.
-6. **Responsive** — Mobile-first. Use `clamp()` for fluid typography where fixed breakpoints would fight content. Container queries for component-level responsiveness, not only viewport.
-7. **UX Writing** — Button labels = verb + object ("Save changes", not "OK"). Error messages = cause + remedy. Empty states earn their screen with value, not apologies.
+1. **Typography (2+1 Rule)** — Reject Arial/Inter as unconsidered defaults. Pair display + text faces on a modular scale. Display headers are strictly roman (`font-style: normal`, never single-word italic emphasis in headlines). Max 3 font families; outlier face used in at most 2 slots.
+2. **Color & Locked Tokens** — Prefer OKLCH over HSL/RGB for perceptual uniformity. Tint neutrals toward the brand hue (pure grays feel sterile; minimum 0.005 chroma). Never pure `#000` or `#fff`. Lock tokens to CSS variables (`var(--color-accent)`) without mid-render inline hex/rgb improvisation. Keep accent area <=5% of viewport.
+3. **Spatial & Macrostructures** — Consistent spacing scale (e.g., 4/8/12/16/24/32/48), not ad-hoc pixel values. Break the repetitive Hero → 3 features → CTA → footer template by choosing intentional macrostructures (Bento Grid, Long Document, Marquee, Stat-Led, Workbench, FAQ, Manifesto). Do not nest cards inside cards or use thick side stripes.
+4. **Motion** — Easing conveys mass and intent. Avoid bounce/elastic curves (feel dated). Stagger sequential reveals. Exit faster than enter. Always respect `prefers-reduced-motion`.
+5. **Interaction & 8 States** — Every interactive element implements all 8 states: default, hover, focus-visible, active, disabled, loading, error, success. Maintain constant 1px `border-width` on inputs across all states (zero layout shift) with a reserved 2px transparent outline. Input height equals button height (>=44px floor).
+6. **Responsive Non-Negotiables** — Mobile-first (320px–768px verified). Apply `overflow-x: clip` on `html` and `body` (never `hidden`). Buttons, nav links, and CTAs never wrap to 2 lines. Use `minmax(0, 1fr)` for image grid tracks.
+7. **UX Writing** — Button labels = verb + object ("Save changes", not "OK"). Error messages = cause + remedy. Empty states earn their screen with value, not apologies. Never invent fake metrics or testimonials.
+8. **Pre-Emit Self-Critique** — Score output 1–5 on Philosophy, Hierarchy, Execution, Specificity, Restraint, Variety (all >=3).
 
-## Anti-Patterns (Taste Failures)
+## Anti-Patterns (Taste & AI-Slop Failures)
 The LLM defaults — reject on sight:
+- Saturated purple-to-pink/blue full-bleed gradient heroes or gradient headline text (`background-clip: text`)
+- Cliché 3-equal-column cards with icon-above-heading tiles
+- Cards nested inside cards or cards with thick side-stripe borders
 - Arial / Inter / system-default typography with no intentional pairing
+- Italic headings or single-word italic emphasis in headlines
+- Changing `border-width` on input focus/hover causing layout shifts
+- Missing interactive states (only styling default + hover)
+- Buttons or links wrapping to two lines on mobile
 - Gray text on colored backgrounds (contrast failure)
-- Pure `#000` black (use tinted near-black instead)
-- Cards nested inside cards
+- Pure `#000` black or `#fff` flat surfaces (use tinted neutrals)
 - Bounce / elastic easing curves
-- Purple gradients (the generic-LLM tell)
 - Motion that ignores `prefers-reduced-motion`
 - Generic stock illustrations for empty states
+- Fake re-drawn browser bars or phone chrome
+- Invented metrics ("+47% conversion"), fake testimonials, or placeholder stock logos
 - Emoji standing in for proper icons (outside branded contexts)
 - Everything centered because no layout opinion was formed
 

package/app/rules/claude-toolkit-rules.md

@@ -11,7 +11,10 @@ Shared AI development toolkit — lifecycle hooks, safety constitution, multi-pl
 
 ## Path Safety
 - NEVER guess or hallucinate user home directory paths
-- Use `~` or `$HOME` instead of hardcoded `/Users/<username>/` or `/home/<username>/`
+- Use `~` or `$HOME` instead of a hardcoded `/Users` or `/home` prefix followed
+  by a user name. The literal prefix is deliberately not written out here: the
+  plugin export scans shipped files for exactly that pattern, so an example of
+  the mistake would be indistinguishable from the mistake.
 - When an absolute path is needed, run `echo $HOME` first to get the correct value
 
 ## User Preferences