tsykvas_rails_template 0.1.0

data/lib/generators/tsykvas_rails_template/install/templates/.claude/commands/tsykvas-claude.md

@@ -0,0 +1,262 @@
+# /tsykvas-claude
+
+Bootstrap and tailor `CLAUDE.md` + `.claude/docs/` to **this** project.
+
+If `CLAUDE.md` doesn't exist yet, run `claude init` first to seed Claude's
+own opinionated overview of the host. Then run `bundle exec rake tsykvas:probe`
+for a deterministic inventory, integrate the gem's fenced sections into
+`CLAUDE.md` (preserving anything Claude wrote outside the fences), and
+**generate** host-specific docs (architecture, code-style, commands, testing,
+ui-components, etc.) from the gem's reference templates.
+
+Supports `--dry-run` to print a unified diff without writing.
+
+---
+
+## Phase 0a — Bootstrap CLAUDE.md if missing
+
+Check whether `CLAUDE.md` exists at the repo root:
+
+```bash
+test -f CLAUDE.md && echo "exists" || echo "missing"
+```
+
+- **Exists** → continue to Phase 0b.
+- **Missing** → run `claude init` (the built-in Claude Code command, NOT a
+  shell command — invoke it the same way the user would). It produces a
+  baseline `CLAUDE.md` with project overview / commands / architecture
+  inferred from the codebase. Wait for it to complete, then continue.
+
+Why first: every subsequent phase assumes `CLAUDE.md` exists. The gem's
+fence-based rewrite preserves user-authored content outside the fences;
+running `claude init` first gives us a richer baseline (project name,
+commands, conventions Claude inferred) for later phases to wrap fences
+around — instead of starting from a blank shell.
+
+If the user invoked `/tsykvas-claude` immediately after `bin/rails g
+tsykvas_rails_template:install` (which creates a CLAUDE.md from the gem's
+template), `claude init` is skipped — the file already exists.
+
+## Phase 0b — Inventory the host project (deterministic)
+
+Always run the Ruby probe first:
+
+```bash
+bundle exec rake tsykvas:probe
+```
+
+Output (schema v=2):
+
+```json
+{
+  "schema_version": 2,
+  "ruby_version": "3.4.7",
+  "rails_version": "8.0.2",
+  "default_branch": "main",
+  "api_only": false,
+  "engine_host": false,
+  "template_engine": "slim",
+  "auth": { "method": "devise", "devise": true, ... },
+  "authorization": "pundit",
+  "has_api_v1": false,
+  "has_bootstrap": false,
+  "test_framework": "rspec",
+  "background_jobs": ["solid_queue"],
+  "databases": ["primary"],
+  "concept_folders": ["home", "crm"],
+  "application_controller_includes": ["Pundit::Authorization", "OperationsMethods"]
+}
+```
+
+Bind this Hash to `probe`. If `probe.api_only` is true, skip every
+HTML-rendering doc. If `probe.engine_host` is true, treat the host as
+a Rails Engine (skip Application-only instructions).
+
+If the probe rake task is missing, the host hasn't run
+`rails g tsykvas_rails_template:install`. Stop and tell the user.
+
+(After Phase 0a + 0b are done, treat what follows as starting from "Phase 1".)
+
+If the host project has its own `README.md`, read it once for "what is this
+app" copy that should seed the project-overview section.
+
+## Phase 1 — Read existing state
+
+For `CLAUDE.md`:
+
+- If it doesn't exist → fresh-install case; you'll write it from
+  `.claude/docs/tsykvas_rails_template.md` cross-doc index plus the
+  fenced-section template.
+- If it exists with `<!-- tsykvas-template:start v=X section=NAME -->` /
+  `<!-- tsykvas-template:end -->` markers → you'll **only rewrite content
+  inside those markers**. User-authored content above, between, or below
+  the fences is sacred.
+- If it exists **without** any fences (the user ran `claude init` before
+  the gem's install, then ran `:install` which now leaves CLAUDE.md
+  alone) → you'll **add** the gem's fenced sections to a sensible position
+  (after user's existing content, separated by a horizontal rule).
+  Don't touch user prose.
+
+For `.claude/docs/`:
+
+- All 20 docs ship at install (under `.claude/docs/<name>.md`).
+- The 3 gem-canonical (`tsykvas_rails_template.md`, `forms.md`,
+  `companions.md`) are kept **verbatim**.
+- The other 17 may be **refreshed** in fenced sections to reflect the
+  host's actual stack (concept folder names, gem versions, default
+  branch, locale config). The reference content is project-agnostic
+  and ships scrubbed of any specific domain — refreshing is purely
+  about swapping in real values where the templates use placeholders.
+
+## Phase 2a — Plan CLAUDE.md fence integration
+
+Target sections (each its own fence in `CLAUDE.md`):
+
+| Fence section | What goes inside |
+|---|---|
+| `project-overview` | 5–8 bullets pulled from `probe.ruby_version`, `probe.rails_version`, `probe.template_engine`, `probe.auth`, `probe.background_jobs`, `probe.test_framework`, `probe.default_branch`, `probe.databases`. |
+| `architecture` | One paragraph; do not mention gems the host doesn't have (e.g. don't claim Bootstrap if `probe.has_bootstrap` is false). |
+| `must-know-rules` | Pull from `code-style.md` (after Phase 2b generates it) and **always preserve** the `<Concept>::Form` rule with a link to `.claude/docs/forms.md`. |
+| `routing` | Drop rows whose target doc was not generated (e.g. `api-endpoints.md` if `probe.has_api_v1` is false; `modal-refactoring.md` if `probe.has_bootstrap` is false). |
+| `slash-commands`, `subagents` | Verbatim from the gem template unless host has added/removed files in `.claude/{commands,agents}/`. |
+| `communication` | Verbatim default unless user has a stated preference. |
+
+**Budget: `CLAUDE.md` must end up ≤ 100 lines.** Plan within that budget
+before writing anything. Roughly: project-overview ≤ 8 lines, architecture
+≤ 8 lines, must-know-rules ≤ 12 lines, routing table 4–10 rows, slash-
+commands + subagents tables compact, communication ≤ 4 lines. If a section
+needs more, push the overflow into a new `.claude/docs/<topic>.md` and
+link it from the routing table. Phase 5 will reject the rewrite if
+`wc -l CLAUDE.md` > 100.
+
+## Phase 2b — Plan `.claude/docs/` refresh
+
+All 20 docs already ship at install under `.claude/docs/`. Your job here
+is **light refresh**: swap in probe-driven values where the shipped
+template uses placeholders. **Do not trim, summarise, or rewrite the
+shipped content.** The depth is intentional — that's why it ships.
+
+| Doc | Refresh strategy |
+|---|---|
+| `architecture.md` | Replace example concept names (`Crm::Property`, `Admin::User`) with the host's actual top-level `concept_folders` if different. |
+| `concepts-refactoring.md` | Keep verbatim — pure architecture walkthrough. |
+| `routing-and-namespaces.md` | Replace example concept names with host's real ones. Keep the example route patterns. |
+| `code-style.md` | Verify references to `.rubocop.yml`, `lefthook.yml`, `.github/workflows/*` resolve to files that actually exist; otherwise mark them with a TODO note. |
+| `commands.md` | If `Procfile.dev` exists, point to `bin/dev`. Otherwise note that the watcher must be run separately. Verify test/lint commands match `bin/`. |
+| `testing.md` + `testing-examples.md` | Confirm `probe.test_framework` (rspec / minitest). Replace any framework-specific snippets accordingly. |
+| `ui-components.md` | Verbatim — Bootstrap is the gem default. |
+| `stimulus-controllers.md` | Verbatim if `app/javascript/controllers/` exists; otherwise add a note that Stimulus is not currently wired. |
+| `forms.md` | **Keep verbatim** (gem-canonical). |
+| `companions.md` | **Keep verbatim** (gem-canonical). |
+| `tsykvas_rails_template.md` | **Keep verbatim** (gem-canonical). |
+| `authentication.md` | Confirm `probe.auth.method`. If `:devise`, leave as is. If custom/warden/jwt/basic_auth, replace the Devise-specific section with the host's actual auth source. |
+| `design-system.md` | Verbatim — generic Bootstrap-default starting point. Host customises to taste. |
+| `i18n.md` | Replace the example default-locale references with the host's actual default locale (read from `config/application.rb`). |
+| `database.md` | Reflect actual `config/database.yml` adapters (postgres / sqlite / mysql / multi-DB). Replace the `<app_name>` placeholder with the actual host app name. |
+| `background-jobs.md` | Confirm `probe.background_jobs`. If SolidQueue, leave as is. If Sidekiq / GoodJob / etc., replace the queue-class references. |
+| `security.md` | Reflect host's actual Brakeman / bundler-audit / CSP setup. |
+| `deployment.md` | If `config/deploy.yml` exists, replace `<your-app>` placeholders with host app name + image. If only `Dockerfile`, mark Kamal sections as optional. |
+| `documentation.md` | Verbatim — generic standards doc. |
+
+For each doc you refresh:
+
+1. Read `.claude/docs/<name>.md` from the host.
+2. Identify placeholder patterns (`<your-app>`, `<app_name>`, `Crm::Property`, `Admin::User`) and probe-driven hooks.
+3. Substitute real values. Do **not** summarise or trim sample code; the
+   shipped depth is intentional and project-agnostic, so it stays.
+4. Write back to `.claude/docs/<name>.md`.
+
+For each doc that's already correct (no placeholders to substitute):
+mark `keep-verbatim` in the change log.
+
+## Phase 3 — Show the plan and wait for confirmation
+
+If `--dry-run`:
+
+1. Build the new content for every fence section + every doc to generate
+   in memory.
+2. Print a unified diff (`diff -u` style) for every file that would change.
+3. Exit. Do not write.
+
+Otherwise present a compact plan table with **four action types**:
+
+| File | Action | Reason |
+|---|---|---|
+| `CLAUDE.md` (`project-overview` fence) | rewrite-fence | seed from probe |
+| `CLAUDE.md` (no fences yet) | create-fence | install left it untouched; integrate gem sections |
+| `.claude/docs/architecture.md` | refresh | swap example concept names for host's actual `concept_folders` |
+| `.claude/docs/deployment.md` | refresh | replace `<your-app>` with host service name |
+| `.claude/docs/forms.md` | keep-verbatim | gem-canonical |
+| … | … | … |
+
+Ask:
+
+> Proceed with N changes? (yes / no / dry-run / diff <file>)
+
+- `yes` → apply.
+- `no` → abort.
+- `dry-run` → switch to dry-run mode and print the full diff.
+- `diff <file>` → show the proposed diff for one file, then re-prompt.
+
+## Phase 4 — Apply
+
+For `CLAUDE.md`:
+- If fences exist: replace **only** the content between matching
+  `<!-- tsykvas-template:start ... -->` and `<!-- tsykvas-template:end -->`
+  markers. Leave content above the first marker, between fences, and below
+  the last marker untouched.
+- If no fences exist: append the gem's fenced sections after the user's
+  existing content, separated by `\n\n---\n\n`. Don't modify user prose.
+
+For `.claude/docs/`:
+- `keep-verbatim` files (the 3 gem-canonical + any doc with no placeholders to substitute): no-op.
+- `refresh` files: write the placeholder-substituted content to `.claude/docs/<name>.md`. Do not trim or summarise.
+
+## Phase 5 — Verify (mandatory; failure = roll back)
+
+Before declaring success, run all of:
+
+1. **CLAUDE.md ≤ 100 lines (HARD GATE).** Run `wc -l CLAUDE.md`. If
+   the result is > 100, the rewrite is rejected — `CLAUDE.md` sits in
+   every Claude session's context, so each extra line is a per-prompt
+   token tax. Re-plan, re-confirm, then re-apply.
+2. **Link integrity.** Every `[…](.claude/docs/X.md)` in `CLAUDE.md`
+   resolves to a real file. Every slash command listed exists in
+   `.claude/commands/`. Every agent listed exists in `.claude/agents/`.
+3. **Fence balance.** Every `tsykvas-template:start` has a matching
+   `tsykvas-template:end`. No unclosed or orphan markers.
+4. **Code health.** Run `bin/rails zeitwerk:check`.
+5. **Probe re-run match.** Re-run the probe. The deterministic fields it
+   reports should still match the values that drove this rewrite. (If the
+   user edited Gemfile during the run, abort.)
+
+If any check fails, restore the pre-write state from your in-memory
+snapshot and report which check failed. **Never leave the repo in a
+half-rewritten state.**
+
+## Phase 6 — Self-update
+
+If you discover during this run that the gem's shipped templates have
+diverged from what the host needs (e.g., a new must-know rule that should
+live in every project), make a note in your memory file under
+`memory/feedback_*.md` so future runs of this command in other repos start
+from a better baseline.
+
+---
+
+## Constraints
+
+- **Never edit content outside fence markers without explicit user
+  confirmation.** Treat unfenced content as user-authored.
+- **Never edit `.claude/*.md` or `CLAUDE.md` without the Phase 3 confirmation
+  prompt.** No silent runs.
+- **Never skip Phase 0.** The probe is the source of truth.
+- **`CLAUDE.md` must stay ≤ 100 lines.** Hard rule, enforced at Phase 5.
+- Use relative paths for all internal links: `.claude/docs/architecture.md`,
+  not absolute URLs.
+- Do not commit. The user runs `/pushit` (or `git commit` themselves) when
+  they are happy with the diff.
+- **Preserve gem-canonical docs verbatim.** `tsykvas_rails_template.md`,
+  `forms.md`, and `companions.md` ship with the gem and are the canonical
+  reference. If a section feels out of date, that's a gem update (bump the
+  gem version), not a project tailoring.

data/lib/generators/tsykvas_rails_template/install/templates/.claude/commands/update-docs.md

@@ -0,0 +1,78 @@
+Check if documentation in `docs/` matches current code changes and update or create docs as needed.
+
+## Step 1: Identify what changed
+
+Compare current branch against `main`:
+
+```bash
+git diff main --name-only 2>&1
+```
+
+If working directly on `main` with uncommitted changes:
+
+```bash
+git diff --name-only 2>&1
+git diff --cached --name-only 2>&1
+```
+
+## Step 2: Understand the changes
+
+Read the changed files and understand what flows or features were added or modified. Focus on:
+
+- New controllers, operations, components
+- Changed model logic (validations, callbacks, scopes)
+- New or modified routes
+- New mailers or jobs
+- Configuration changes that affect behavior
+- New integrations or external services
+
+## Step 3: Audit existing documentation
+
+Check what documentation already exists:
+
+```bash
+find docs/ -name "*.md" -type f 2>&1
+```
+
+For each changed flow, determine:
+
+1. **No doc exists** — a new doc file is needed
+2. **Doc exists but is outdated** — the doc needs updating
+3. **Doc exists and is current** — no action needed
+
+## Step 4: Present findings and ask for confirmation
+
+Show a table:
+
+| Flow / Feature | Doc file | Status | Action needed |
+|----------------|----------|--------|---------------|
+| ... | `docs/...` or *none* | Current / Outdated / Missing | None / Update / Create |
+
+Then ask:
+
+> Found N doc(s) that need attention. Proceed?
+> 1. Yes, update/create all
+> 2. Let me pick which ones
+> 3. Skip
+
+**Wait for user response.** Do NOT make any changes without confirmation.
+
+## Step 5: Update or create documentation
+
+For **new docs**:
+- Create in `docs/<domain>/` matching the feature domain (existing domains: `admin`, `crm`, `screener`, `shared`, `base` — or root for cross-cutting)
+- Use clear markdown with sections: overview, how it works, configuration (if any), examples
+- Keep it concise and practical — document behavior, not internal code structure
+- Use the same style and level of detail as existing docs in `docs/` and the template in `.claude/docs/documentation.md`
+
+For **existing docs**:
+- Update only the sections affected by the changes
+- Do not rewrite unrelated sections
+- Add new sections if the change introduces new behavior
+
+## Rules
+
+- Documentation language: English
+- Never delete documentation without asking
+- Keep docs focused on **what the feature does and how to use it**, not internal code structure
+- If unsure whether a change warrants documentation — include it in the table and let the user decide

data/lib/generators/tsykvas_rails_template/install/templates/.claude/commands/update-rules.md

@@ -0,0 +1,102 @@
+Check if `.claude/docs/` or `CLAUDE.md` need updating after changes to base classes, application controller, or policies.
+
+## Step 1: Detect changes to watched files
+
+Check if any of these files were modified:
+
+```bash
+git diff main --name-only -- \
+  app/concepts/base/ \
+  app/controllers/concerns/operations_methods.rb \
+  app/controllers/application_controller.rb \
+  app/policies/application_policy.rb \
+  app/policies/admin/base_policy.rb \
+  app/policies/crm/base_policy.rb \
+  app/policies/screener/base_policy.rb \
+  2>&1
+```
+
+If on `main` with uncommitted changes:
+
+```bash
+git diff --name-only -- \
+  app/concepts/base/ \
+  app/controllers/concerns/operations_methods.rb \
+  app/controllers/application_controller.rb \
+  app/policies/application_policy.rb \
+  app/policies/admin/base_policy.rb \
+  app/policies/crm/base_policy.rb \
+  app/policies/screener/base_policy.rb \
+  2>&1
+git diff --cached --name-only -- \
+  app/concepts/base/ \
+  app/controllers/concerns/operations_methods.rb \
+  app/controllers/application_controller.rb \
+  app/policies/application_policy.rb \
+  app/policies/admin/base_policy.rb \
+  app/policies/crm/base_policy.rb \
+  app/policies/screener/base_policy.rb \
+  2>&1
+```
+
+**If none of these files changed — stop here. No action needed.**
+
+## Step 2: Understand what changed
+
+Read the diffs for each changed file:
+
+```bash
+git diff main -- <file> 2>&1
+```
+
+Understand what was added, removed, or modified in terms of:
+
+- New methods or method signatures
+- Changed behavior of existing methods
+- New conventions or patterns
+- Removed or deprecated features
+
+## Step 3: Audit current rules
+
+Read the relevant doc files and `CLAUDE.md`. Map each change to the doc file it affects:
+
+| Changed file | Doc file |
+|---|---|
+| `app/concepts/base/operation/base.rb` | `.claude/docs/architecture.md`, `.claude/docs/concepts-refactoring.md` |
+| `app/concepts/base/operation/result.rb` | `.claude/docs/architecture.md` |
+| `app/concepts/base/operation/sortable.rb` | `.claude/docs/architecture.md` |
+| `app/concepts/base/component/base.rb` | `.claude/docs/architecture.md`, `.claude/docs/ui-components.md` |
+| `app/concepts/base/component/btn.rb` (or `btn_config.rb`) | `.claude/docs/ui-components.md` |
+| `app/concepts/base/component/table/*.rb` | `.claude/docs/ui-components.md` |
+| `app/concepts/base/component/title_row.rb` | `.claude/docs/ui-components.md` |
+| `app/controllers/concerns/operations_methods.rb` | `.claude/docs/architecture.md`, `.claude/docs/concepts-refactoring.md` |
+| `app/controllers/application_controller.rb` | `CLAUDE.md`, `.claude/docs/architecture.md` |
+| `app/policies/application_policy.rb` | `.claude/docs/architecture.md` |
+| `app/policies/<domain>/base_policy.rb` | `.claude/docs/architecture.md` |
+
+## Step 4: Present proposed changes — MANDATORY
+
+**You MUST present a table of all proposed changes and get explicit confirmation before editing ANY file in `.claude/` or `CLAUDE.md`.**
+
+Show:
+
+| Doc file | Section | Current text (summary) | Proposed change | Why |
+|----------|---------|----------------------|-----------------|-----|
+| ... | ... | ... | ... | ... |
+
+Then ask:
+
+> Proposed N change(s) to docs/instructions. Apply them?
+> 1. Yes, apply all
+> 2. Let me pick which ones
+> 3. Skip all
+
+**Wait for user response. Do NOT make any changes without explicit confirmation.**
+
+## Rules
+
+- **NEVER edit `.claude/` or `CLAUDE.md` without user confirmation.** This is non-negotiable.
+- Keep docs concise — do not add unnecessary text that wastes tokens.
+- Only document patterns that Claude needs to follow. If it's obvious from the code, don't add a rule for it.
+- Remove outdated rules when the underlying code changes.
+- Prefer updating existing sections over adding new ones.

data/lib/generators/tsykvas_rails_template/install/templates/.claude/commands/update-tests.md

@@ -0,0 +1,135 @@
+Audit RSpec coverage for all `.rb` files changed on this branch vs `main`, then write or update specs where coverage is missing.
+
+Follow project conventions from `.claude/docs/testing.md` and `.claude/docs/testing-examples.md`.
+
+## Step 1: Find changed `.rb` files
+
+```bash
+git diff main --name-only 2>&1 | grep '\.rb$'
+```
+
+If `main` does not exist as a remote ref, fall back to:
+
+```bash
+git diff origin/main --name-only 2>&1 | grep '\.rb$'
+```
+
+If working directly on `main` with uncommitted changes:
+
+```bash
+git diff --name-only 2>&1 | grep '\.rb$'
+git diff --cached --name-only 2>&1 | grep '\.rb$'
+```
+
+From the output, collect only files under `app/` (skip `spec/`, `db/migrate/`, `config/`, `lib/` unless they contain real business logic).
+
+## Step 2: Filter — skip files with no testable logic
+
+For each changed `app/**/*.rb` file, read the actual diff and the full file. **Skip** the file if it matches any of these:
+
+- Component `.rb` that only defines `initialize` (parameter wrapper, no methods)
+- Migration file
+- Pure configuration (`config/`, `initializers/`)
+- Empty class with no methods beyond `initialize` and `attr_reader`/`attr_accessor`
+- Route file, `application.rb`, or similar framework glue
+
+**Include** everything else: operations, services, models, controllers, jobs, policies, concerns with logic.
+
+## Step 3: Audit each file
+
+For every included file, do all three:
+
+1. **Read the diff** — `git diff main -- <file>` — understand exactly what changed or was added
+2. **Find the spec** — mirror the `app/` path under `spec/`:
+   - `app/concepts/admin/user/operation/index.rb` → `spec/concepts/admin/user/operation/index_spec.rb`
+   - `app/services/foo.rb` → `spec/services/foo_spec.rb`
+   - `app/controllers/admin/users_controller.rb` → `spec/controllers/admin/users_controller_spec.rb` or `spec/requests/admin/users_spec.rb`
+   - `app/models/user.rb` → `spec/models/user_spec.rb`
+   - `app/jobs/foo_job.rb` → `spec/jobs/foo_job_spec.rb`
+   - `app/policies/crm/company_policy.rb` → `spec/policies/crm/company_policy_spec.rb`
+3. **Verify coverage** — read the spec (if it exists) and confirm every new/changed public method, branch, and business logic path introduced by the diff is tested. Do not assume coverage — read the spec line by line.
+
+## Step 4: Present findings before writing
+
+Show a table of files that need action:
+
+| File | Spec | Status | Action |
+|------|------|--------|--------|
+| `app/...` | `spec/...` | Missing / Incomplete | Create / Update |
+
+Then ask:
+
+> Found N file(s) that need test coverage. Proceed?
+> 1. Yes, write/update all
+> 2. Let me pick which ones
+> 3. Skip
+
+**Wait for user response before writing any specs.**
+
+## Step 5: Write or update specs
+
+Work through each file **one at a time**:
+
+### Writing a new spec
+
+- `# frozen_string_literal: true` at the top
+- `require 'rails_helper'`
+- Use `described_class`, not the class name directly
+- Use `let` / `let!`, FactoryBot with Faker
+- Structure: `describe '.call'` → `context 'when ...'` → `it '...'`
+- Cover: happy path, authorization failure (`raise_error(Pundit::NotAuthorizedError)`), error branches, edge cases
+- Declare `type:` explicitly (this project does NOT enable `infer_spec_type_from_file_location!`)
+
+### Updating an existing spec
+
+- Add new `context` blocks for new branches; do not rewrite existing passing tests
+- Keep the same describe/context depth and naming style as the rest of the file
+
+### Skip spec creation if:
+
+- The file contains only component initialization (no logic methods)
+- The change is cosmetic (rename, whitespace, comment)
+
+## Step 6: Run the specs
+
+After writing/updating, run **only the affected spec files**:
+
+```bash
+bundle exec rspec <spec_file_1> <spec_file_2> ... --format documentation 2>&1
+```
+
+Do **not** run the full suite — run only the files you touched.
+
+## Step 7: Fix failures
+
+For each failing example:
+
+1. Read the failure message and backtrace
+2. Read the source file and the spec
+3. Determine root cause: bug in the spec (wrong stub, wrong expectation) or bug in the source code
+4. Fix the appropriate file
+5. Re-run only that spec to confirm: `bundle exec rspec <file>:<line> 2>&1`
+
+If a failure reveals a real source code bug — fix the source and note it in the final report.
+
+## Step 8: Report
+
+After all specs pass, report:
+
+```
+## Test Coverage Update
+
+| File | Spec | Action taken | Result |
+|------|------|--------------|--------|
+| app/... | spec/... | Created / Updated / Skipped | ✅ X examples, 0 failures |
+```
+
+If any spec still fails after fix attempts — show the failure and ask for guidance.
+
+## Rules
+
+- Never run the full suite (`bundle exec rspec`) — run only changed spec files
+- Never delete existing passing tests
+- Use `instance_double` over plain `double` wherever the interface is known
+- Write tests in English
+- Keep tests focused — one logical assertion per `it` block