@bonesofspring/ai-rules 0.2.20 → 0.2.22

package/presets/cursor/svelte/rules/tests-unit.mdc

@@ -6,37 +6,86 @@ alwaysApply: false
 impact: MEDIUM
 ---
 
-# Shared testing rules
+<!-- shared-core: testing/testing-principles.md -->
 
-- **File names:** new tests — **`*.spec.ts`**. Do not rename existing `*.test.ts` without a task.
-- **Runner:** Vitest (or as in the project). Components — **`@testing-library/svelte`** (not `@vue/test-utils`, not React Testing Library as default).
-- Assert **behavior**, not internals.
-- **`describe` / `it` naming:** formulate titles **in Russian**, each sentence capitalized (as with ESLint `jest/valid-title` if enabled). <!-- i18n-keep: E5 -->
+# Testing principles
 
-```typescript
-// ✅
-it('Возвращает пустой список. Пользователь не авторизован', () => {}) // <!-- i18n-keep: E5 -->
+Stack-agnostic; concrete paths, runners, and selectors live in the stack adapter (`## Stack notes`).
 
-// ❌
-it('Returns empty list when user is guest', () => {})
-```
+## Behavior vs. implementation
 
-# Components
+- Verify **behavior and business rules**, not implementation or internal details.
 
-- `render` from `@testing-library/svelte`.
-- Interactions: `userEvent` from `@testing-library/user-event` when that is the repo convention.
+## File naming
 
-# Isolation
+- For **new** tests use `*.spec.ts` / `*.spec.tsx`. Do not rename existing `*.test.ts` / `*.test.tsx` without a separate task (legacy).
 
-- Mock `$lib/api` / stores per neighbor patterns.
-- Do not mock the feature’s public contract without need.
+## Runner and matchers
 
-# HTTP / mappers
+- Use the project's runner (Jest or Vitest are common); components — the project's Testing Library integration. Reuse existing matchers — no new micro-framework.
 
-- Changes to the shared HTTP client — behavior tests next to `src/lib/clients/**`.
-- DTO→domain mappers — unit tests for edge cases.
+## Test title locale
+
+- Consumer apps **may use the project locale** (often Russian) — clear business phrases stating what is checked and the expected outcome.
+- When ESLint enforces the locale (e.g. `jest/valid-title`): each sentence must start with a **capital letter** (including after `.`, `!`, `?`); a space after `.` followed by a lowercase letter is forbidden ("capital after period" violation).
+
+Good (Russian locale in consumer app):
+
+- `it('Возвращает пустой список. Пользователь не авторизован', () => {})` <!-- i18n-keep: E5 --> (Returns empty list. User is not authorized)
+
+Bad (no capital after period; or wrong locale for configured ESLint):
+
+- `it('Возвращает пустой список. пользователь не авторизован', () => {})` <!-- i18n-keep: E5 -->
+- `it('Returns empty list when user is guest', () => {})` (wrong locale if ESLint enforces Russian)
+
+## Isolation and mocks
+
+- Mock at the **public-contract boundary**; use the project's accepted HTTP/API/store mock approach. Do not mock what is part of the feature's public contract if that breaks the test's meaning.
+
+## Coverage of cross-cutting modules
+
+- When changing a **shared cross-cutting module** (e.g. HTTP client body parsing, headers, error / auth handling) — **update or add behavior tests** covering success, error, and edge branches relevant to the module under change.
+
+## Data transformation coverage
+
+- Data transformation functions with computed fields and branches must have unit tests covering edge cases (boundary values, missing fields, unexpected value combinations).
+
+## Reuse fixtures over ad-hoc random data
+
+- Prefer shared fixtures / handlers from the project's accepted mocks module; do not duplicate interfaces in tests. Use the API response types (DTO types) and the **target domain types** from the project's public type surface.
 
-# Placement
+## E2E: one canonical scenario plan per feature
 
-- UI: neighboring `*.spec.ts` (no required `__tests__/` inside the component).
-- Other modules — as neighbors do.
+- For each feature keep a **single canonical scenario plan** (distinct from implementation specs; the stack adapter names the file — typically `*.cases.md`).
+
+## E2E: scenario ↔ test traceability
+
+- Every scenario has a corresponding test. **Do not weaken** assertions to match an outdated implementation — tests must reflect business expectations from the plan. Colocate plan and executable tests in the same directory.
+
+## E2E: page objects / shared helpers
+
+- Prefer page objects and shared helpers over scattered selectors and per-test setup duplication.
+
+## E2E: stable identifiers (PREFIX-XXX)
+
+- When scenarios need stable IDs, prefix the title with `PREFIX-XXX`: `PREFIX` = first letters of words in the entity under test (Latin uppercase); `XXX` = sequential number with three digits and leading zeros. Within one `PREFIX`, numbers must form a consistent sequence with no duplicates.
+- Example: `test('OH-001 Отображается список заказов', async ({ page }) => { ... })` <!-- i18n-keep: E5 --> (Order list is displayed)
+
+## E2E: selector priority
+
+- Prefer role/label selectors for accessibility and forms; fall back to `data-testid` for stable elements. Use a **hierarchical naming convention** on page roots and key interactive elements (stack adapter defines the scheme — typically `{parent}__{element}`).
+
+## E2E: keep plans and selectors in sync with UI
+
+- When changing UI: update selectors in page objects and cross-check with the scenario plan. When adding/changing tests: read the matching plan and sync scenario titles first.
+
+## Stack notes
+
+- Runner: Vitest (default for SvelteKit).
+- Components: `render` from `@testing-library/svelte` (NOT `@vue/test-utils`, NOT React Testing Library as default).
+- `userEvent` from `@testing-library/user-event` when that is the repo convention.
+- HTTP-client behavior tests next to `src/lib/clients/**` (SvelteKit convention; no `app/`, no `src/app/`).
+- Mock `$lib/api` / stores per neighbor patterns.
+- DTO→domain mappers — unit tests for edge cases.
+- UI placement: sibling `*.spec.ts` in `src/lib/components` (no `__tests__/` inside the component folder).
+- `## Stack notes` content is stripped by `scripts/check-shared-core-drift.sh` before byte-comparing this file against `_shared/core/testing/testing-principles.md`; keep prose above (core content) verbatim against the core file.

package/presets/cursor/svelte/team/README.md

@@ -106,8 +106,6 @@ Prefer **`executing`** for pipeline mode. Legacy: `analysis`, `development`, `re
 /technical-retro <slug>
 ```
 
-Legacy: `/feature-start`, `/feature-continue`.
-
 ## Creating task dirs
 
 Bootstrap `<slug>/` by **writing** `pipeline.json` (Write tool). Runtime/hook owns `status.json` lifecycle; parent may only create a minimal bootstrap if missing. Do **not** use Shell `mkdir -p` — Cursor’s default sandbox returns `Operation not permitted` (especially for repos on macOS Desktop/Documents).
@@ -116,7 +114,6 @@ Bootstrap `<slug>/` by **writing** `pipeline.json` (Write tool). Runtime/hook ow
 
 Commit task artifacts if you want them to survive `ai-rules clean cursor`. Or copy finished tasks to `docs/agent-workflow/tasks/<slug>/`.
 
-
 ## specMode, applyReadiness, memlog
 
 - **`specMode`:** `consume` | `generate` | `none` — primary in `brief.md` `## Spec mode`; optional top-level `pipeline.json` `specMode`. `none` skips INDEX/author mode (spike/research).

package/scripts/_lib/embed-stems.json

@@ -0,0 +1,31 @@
+{
+  "$comment": "Single source of truth for embed-mode shared-core stems. Loaded by check-shared-core-drift.sh and sync-shared-core-embeds.sh to keep the two scripts in lockstep.",
+  "embed": [
+    "quality/code-quality-and-refactoring.md",
+    "quality/anti-sycophancy-discipline.md",
+    "quality/design-guidance.md",
+    "quality/mcp-usage.md",
+    "meta/preset-layering.md",
+    "meta/preset-twin-sync.md",
+    "meta/preset-token-budget.md",
+    "meta/preset-pr-checklist.md",
+    "meta/preset-no-cross-stack-leakage.md",
+    "review/code-review-mr.md",
+    "review/technical-retro.md",
+    "review/mockup-review.md",
+    "review/ux-design.md",
+    "agent-team/agent-team-intake.md",
+    "architecture/product-specs.md",
+    "architecture/product-specs-authoring.md",
+    "quality/debug-investigation.md",
+    "testing/testing-principles.md"
+  ],
+  "lineage": [
+    "architecture/feature-delivery-workflow.md",
+    "architecture/reference-features.template.md",
+    "agent-team/agent-team-orchestrator.md",
+    "quality/verification-before-completion.md",
+    "review/receiving-code-review.md",
+    "agent-team/task-classification.md"
+  ]
+}

package/scripts/aggregate-agent-task-metrics.mjs

@@ -1,9 +1,32 @@
 #!/usr/bin/env node
+/**
+ * Aggregate `metrics.json` ledgers across `.cursor/team/tasks/*` and emit a JSON report.
+ *
+ * Usage:
+ *   node scripts/aggregate-agent-task-metrics.mjs [--team-root <dir>] [--help]
+ *
+ * Defaults to `<cwd>/.cursor/team` when --team-root is omitted.
+ */
 
 import fs from 'node:fs';
 import path from 'node:path';
 
 const args = process.argv.slice(2);
+
+if (args.includes('-h') || args.includes('--help')) {
+  console.log(`Aggregate agent-task metrics ledgers.
+
+Usage:
+  node scripts/aggregate-agent-task-metrics.mjs [--team-root <dir>]
+
+Options:
+  --team-root <dir>  Directory containing a 'tasks/' subfolder with *.metrics.json ledgers
+                     (default: <cwd>/.cursor/team)
+
+Output: JSON report on stdout (machine-readable).`);
+  process.exit(0);
+}
+
 const teamRootIndex = args.indexOf('--team-root');
 const teamRoot =
   teamRootIndex >= 0

package/scripts/check-chain-hook-coverage.sh

@@ -0,0 +1,109 @@
+#!/usr/bin/env bash
+# FAIL when chain-team-phases.sh has an orphaned entry:
+#  - DEFAULT_ARTIFACT_OUTPUT_IDS entry without an AGENT_HANDOFF entry, or
+#  - AGENT_HANDOFF entry without a DEFAULT_ARTIFACT_OUTPUT_IDS entry.
+#
+# Also FAIL when a stack ships an agent file that the hook ignores entirely
+# (no entry in either map) AND the stack has a pipeline intent that can route
+# to it — for example, intent `openspec-change` requires `openspec-author` to
+# be wired through both maps or the pipeline silently halts in
+# `awaiting_artifact_receipt`. We check the documented intent-to-agent table in
+# each stack's task-router.md against the hook's actual coverage.
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/../../.." && pwd)"
+export AI_RULES_PRESETS_ROOT="$ROOT/packages/ai-rules/presets"
+
+python3 <<'PY'
+from __future__ import annotations
+
+import os
+import re
+import sys
+from pathlib import Path
+
+presets = Path(os.environ["AI_RULES_PRESETS_ROOT"])
+
+# Stacks that ship a /task pipeline. mcp-ts ships a Phase-1 chain but not the
+# standard openspec-change intent; do not require openspec-author there.
+STACKS_WITH_OPENSPEC = {
+    ("cursor", "android-kotlin"),
+    ("cursor", "go"),
+    ("cursor", "ios-swift"),
+    ("cursor", "java"),
+    ("cursor", "next"),
+    ("cursor", "nuxt"),
+    ("cursor", "php-hexagonal"),
+    ("cursor", "php-laravel"),
+    ("cursor", "svelte"),
+    ("claude", "android-kotlin"),
+    ("claude", "go"),
+    ("claude", "ios-swift"),
+    ("claude", "java"),
+    ("claude", "next"),
+    ("claude", "nuxt"),
+    ("claude", "php-hexagonal"),
+    ("claude", "php-laravel"),
+    ("claude", "svelte"),
+}
+
+# Agents used only outside the pipeline (no chain hook entry expected).
+PIPELINE_EXEMPT = {"task-router", "codebase-analyzer"}
+
+failures: list[str] = []
+checks = 0
+
+
+def parse_block(text: str, header_re: str, line_re: str) -> set[str]:
+    m = re.search(header_re, text, re.DOTALL)
+    if not m:
+        return set()
+    return {x.group(1) for x in line_re.finditer(m.group(1))}
+
+
+for hook in sorted(presets.glob("*/**/hooks/chain-team-phases.sh")):
+    rel = hook.relative_to(presets)
+    platform, preset = rel.parts[0], rel.parts[1]
+    text = hook.read_text(encoding="utf-8")
+
+    artifact_ids = parse_block(
+        text,
+        r"const DEFAULT_ARTIFACT_OUTPUT_IDS = \{(.*?)\};\n",
+        re.compile(r"^\s*['\"]([a-z][a-z0-9.\-]*)['\"]\s*:\s*['\"][a-z][a-z0-9.\-]*['\"]\s*,?", re.MULTILINE),
+    )
+    handoff_keys = parse_block(
+        text,
+        r"const AGENT_HANDOFF = \{(.*?)\n\};\n",
+        re.compile(r"^\s*['\"]([a-z][a-z0-9.\-]*)['\"]\s*:\s*\(s", re.MULTILINE),
+    )
+
+    # 1) Symmetric invariant: any entry in either map must appear in the other.
+    only_artifact = artifact_ids - handoff_keys
+    only_handoff = handoff_keys - artifact_ids
+    for agent in sorted(only_artifact - PIPELINE_EXEMPT):
+        checks += 1
+        failures.append(f"{rel}: DEFAULT_ARTIFACT_OUTPUT_IDS '{agent}' has no AGENT_HANDOFF entry")
+    for agent in sorted(only_handoff - PIPELINE_EXEMPT):
+        checks += 1
+        failures.append(f"{rel}: AGENT_HANDOFF '{agent}' has no DEFAULT_ARTIFACT_OUTPUT_IDS entry")
+
+    # 2) openspec-author must be in BOTH maps for any stack that ships the
+    # agent. The hook without this entry silently breaks the openspec-change
+    # intent (the original bug).
+    agents_dir = presets / platform / preset / "agents"
+    if (platform, preset) in STACKS_WITH_OPENSPEC and (agents_dir / "openspec-author.md").exists():
+        checks += 1
+        if "openspec-author" not in artifact_ids:
+            failures.append(f"{rel}: ships openspec-author.md but hook is missing DEFAULT_ARTIFACT_OUTPUT_IDS['openspec-author'] (openspec-change intent will silently stall in awaiting_artifact_receipt)")
+        if "openspec-author" not in handoff_keys:
+            failures.append(f"{rel}: ships openspec-author.md but hook is missing AGENT_HANDOFF['openspec-author']")
+
+if failures:
+    print(f"FAIL: chain-team-phases.sh coverage gap ({len(failures)} issue(s) / {checks} checks):")
+    for f in failures:
+        print(f"  - {f}")
+    sys.exit(1)
+
+print(f"OK: chain-team-phases.sh hook coverage is consistent ({checks} checks across all hooks)")
+sys.exit(0)
+PY

package/scripts/check-local-overlay.sh

@@ -0,0 +1,136 @@
+#!/usr/bin/env bash
+# Verify that every installable stack ships an `ai-local-overlay` rule on both
+# sides (Cursor `.mdc` and Claude `.md`) and that the body contains the
+# mandatory acknowledgement format.
+#
+# Exit 0 on OK; exit 1 on any FAIL.
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/../../.." && pwd)"
+export AI_RULES_PRESETS_ROOT="$ROOT/packages/ai-rules/presets"
+
+python3 <<'PY'
+from __future__ import annotations
+
+import os
+import re
+import sys
+from pathlib import Path
+
+presets = Path(os.environ["AI_RULES_PRESETS_ROOT"])
+STACKS = (
+    "next",
+    "nuxt",
+    "svelte",
+    "ios-swift",
+    "android-kotlin",
+    "go",
+    "java",
+    "mcp-ts",
+    "php-hexagonal",
+    "php-laravel",
+)
+
+CURSOR_NAME = "ai-local-overlay.mdc"
+CLAUDE_NAME = "ai-local-overlay.md"
+# The body line that the agent MUST emit when it applies the overlay.
+ACK_RE = re.compile(r"Using\s+\.ai\.local:\s+<rule-name>")
+# Sentinel strings that signal the rule is mandatory / explains authoring /
+# points at the consumer guide.
+FRONTMATTER_DESCRIPTION = "MANDATORY"
+POINTER_DOCS = "docs/LOCAL-OVERLAY.md"
+
+
+def strip_frontmatter(text: str) -> tuple[str, str]:
+    if not text.startswith("---\n"):
+        return "", text
+    end = text.find("\n---\n", 4)
+    if end < 0:
+        return "", text
+    return text[4:end], text[end + 5 :]
+
+
+failed = 0
+stack_failed: dict[str, int] = {}
+
+print("Local overlay coverage (every stack must ship ai-local-overlay)")
+print(f"Presets: {presets}")
+print()
+
+for stack in STACKS:
+    print(f"=== {stack} ===")
+    cursor_path = presets / "cursor" / stack / "rules" / CURSOR_NAME
+    claude_path = presets / "claude" / stack / "rules" / CLAUDE_NAME
+
+    # Per-stack failure counter — keeps the OK message for healthy stacks
+    # even when an earlier stack has failed.
+    sf = 0
+
+    # Cursor must exist + alwaysApply: true + ack format + pointer.
+    if not cursor_path.is_file():
+        print(f"FAIL: missing {cursor_path}")
+        sf += 1
+    else:
+        text = cursor_path.read_text(encoding="utf-8")
+        fm, body = strip_frontmatter(text)
+        if "alwaysApply: true" not in fm:
+            print(f"FAIL: {cursor_path.name} must have alwaysApply: true")
+            sf += 1
+        if FRONTMATTER_DESCRIPTION not in fm:
+            print(f"FAIL: {cursor_path.name} frontmatter description must include 'MANDATORY'")
+            sf += 1
+        if not ACK_RE.search(body):
+            print(f"FAIL: {cursor_path.name} body missing acknowledgement format `Using .ai.local: <rule-name>`")
+            sf += 1
+        if POINTER_DOCS not in body:
+            print(f"FAIL: {cursor_path.name} body must reference `docs/LOCAL-OVERLAY.md`")
+            sf += 1
+        if sf == 0:
+            print(f"  OK: {cursor_path.name} (alwaysApply + MANDATORY + ack + pointer)")
+
+    # Claude must exist (flat or topic folder) + paths: includes .ai.local + ack format + pointer.
+    if not claude_path.is_file():
+        # Try to find a topic-folder placement (e.g. tooling-and-review/ai-local-overlay.md).
+        candidates = list((presets / "claude" / stack / "rules").rglob(CLAUDE_NAME))
+        if candidates:
+            claude_path = candidates[0]
+        else:
+            print(f"FAIL: missing {claude_path}")
+            sf += 1
+    if claude_path.is_file():
+        text = claude_path.read_text(encoding="utf-8")
+        fm, body = strip_frontmatter(text)
+        if "**/.ai.local/**" not in fm:
+            print(f"FAIL: {claude_path.name} frontmatter must include `**/.ai.local/**` in paths")
+            sf += 1
+        if FRONTMATTER_DESCRIPTION not in fm:
+            print(f"FAIL: {claude_path.name} frontmatter description must include 'MANDATORY'")
+            sf += 1
+        if not ACK_RE.search(body):
+            print(f"FAIL: {claude_path.name} body missing acknowledgement format `Using .ai.local: <rule-name>`")
+            sf += 1
+        if POINTER_DOCS not in body:
+            print(f"FAIL: {claude_path.name} body must reference `docs/LOCAL-OVERLAY.md`")
+            sf += 1
+        if sf == 0:
+            print(f"  OK: {claude_path.name} (paths + MANDATORY + ack + pointer)")
+
+    # Twin-map coverage: the Claude twin must be listed in claude/<stack>/rules/README.md.
+    claude_readme = presets / "claude" / stack / "rules" / "README.md"
+    if claude_readme.is_file():
+        readme_text = claude_readme.read_text(encoding="utf-8")
+        if CURSOR_NAME not in readme_text:
+            print(f"FAIL: {claude_readme} mapping table must include `{CURSOR_NAME}`")
+            sf += 1
+
+    stack_failed[stack] = sf
+    failed += sf
+    print()
+
+if failed:
+    print(f"Result: FAIL ({failed} issue(s) across {sum(1 for v in stack_failed.values() if v > 0)} stack(s))")
+    sys.exit(1)
+
+print("Result: OK")
+sys.exit(0)
+PY

package/scripts/check-preset-i18n.sh

@@ -54,8 +54,8 @@ if len(violations) > 50:
     print(f"  ... and {len(violations) - 50} more")
 
 if violations and (fail or not soft):
-    if fail:
-        sys.exit(1)
+    print("Result: FAIL (unmarked Cyrillic)" if fail else "Result: WARN (soft)")
+    sys.exit(1)
 print("Result:", "WARN (soft)" if violations else "OK")
 sys.exit(0)
 PY

package/scripts/check-preset-leakage.sh

@@ -278,7 +278,10 @@ def line_is_negation(line: str) -> bool:
 
 
 def is_forbidden_agent(name: str, bad_stems: tuple[str, ...]) -> bool:
-    return name in bad_stems or any(name.startswith(s) for s in bad_stems)
+    # Exact match, or kebab-case prefix (so `playwright-test-planner` matches
+    # `playwright-test-planner-foo` too — kebab-case is the only naming style in
+    # use across all presets, so the naive `startswith` is intentional).
+    return name in bad_stems or any(name.startswith(s + "-") or name == s for s in bad_stems)
 
 
 def collect_step_agents(steps) -> list[str]:

package/scripts/check-preset-structure.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# Orchestrator: twin map + token budget + leakage + hook-only lifecycle + shared-core drift + i18n (hard).
+# Orchestrator: twin map + token budget + leakage + hook-only lifecycle + local-overlay + shared-core drift + i18n (hard).
 # All gates exit non-zero on FAIL.
 set -euo pipefail
 
@@ -33,7 +33,10 @@ run_gate "twin-map" "$SCRIPT_DIR/check-preset-twin-map.sh"
 run_gate "token-budget" "$SCRIPT_DIR/check-preset-token-budget.sh"
 run_gate "leakage" "$SCRIPT_DIR/check-preset-leakage.sh"
 run_gate "hook-only-lifecycle" "$SCRIPT_DIR/check-hook-only-lifecycle.sh"
+run_gate "local-overlay" "$SCRIPT_DIR/check-local-overlay.sh"
 run_gate "shared-core-drift" "$SCRIPT_DIR/check-shared-core-drift.sh" AI_RULES_DRIFT_FAIL=1
+run_gate "chain-hook-coverage" "$SCRIPT_DIR/check-chain-hook-coverage.sh"
+run_gate "task-router-intents" "$SCRIPT_DIR/check-task-router-intents.sh"
 run_gate "i18n" "$SCRIPT_DIR/check-preset-i18n.sh" AI_RULES_I18N_FAIL=1 AI_RULES_I18N_SOFT=0
 
 echo ">>> cli-mcp-merge"
@@ -45,6 +48,33 @@ else
 fi
 echo
 
+echo ">>> chain-team-phases coverage"
+if node "$SCRIPT_DIR/test-chain-team-phases-coverage.mjs"; then
+  echo "<<< chain-team-phases coverage: OK"
+else
+  echo "<<< chain-team-phases coverage: FAIL"
+  status=1
+fi
+echo
+
+echo ">>> agent-task-metrics hooks"
+if node "$SCRIPT_DIR/test-agent-task-metrics-hooks.mjs"; then
+  echo "<<< agent-task-metrics hooks: OK"
+else
+  echo "<<< agent-task-metrics hooks: FAIL"
+  status=1
+fi
+echo
+
+echo ">>> task-router-intents fixtures"
+if node "$SCRIPT_DIR/test-task-router-intents-fixtures.mjs"; then
+  echo "<<< task-router-intents fixtures: OK"
+else
+  echo "<<< task-router-intents fixtures: FAIL"
+  status=1
+fi
+echo
+
 # Soft WARN: dogfood product-specs (never fails the orchestrator).
 # Default check-product-specs exits 0 even when issues are found unless --strict.
 # Use --strict here only to surface problems as WARN in logs; do not flip status.