@bonesofspring/ai-rules 0.2.11 → 0.2.13

package/presets/cursor/php-hexagonal/hooks/examples/README.md

@@ -0,0 +1,18 @@
+# Hooks cookbook (examples)
+
+Optional scripts under `hooks/examples/`. **Not** referenced from default `hooks.json` (only `guard-shell-command.sh` + `chain-team-phases.sh`).
+
+| Script | Purpose |
+|--------|---------|
+| `secret-guard.example.sh` | Fail if staged diff looks like secrets |
+| `format-edited.example.sh` | Stack formatter / linter on edited files |
+| `test-on-save.example.sh` | Scoped tests for the stack |
+
+## Wiring (Cursor)
+
+1. Copy an example into `hooks/` (drop `.example` suffix), e.g. `cp hooks/examples/secret-guard.example.sh hooks/secret-guard.sh`.
+2. `chmod +x hooks/secret-guard.sh`.
+3. Add a hook entry in `.cursor/hooks.json` (e.g. `beforeShellExecution` or `afterFileEdit` — see Cursor hooks docs).
+4. Keep cookbook scripts **out** of the default preset `hooks.json` when contributing back upstream.
+
+Stack: **go** — recipes must stay stack-safe (no cross-stack lint/test commands).

package/presets/cursor/php-hexagonal/hooks/examples/format-edited.example.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+# Optional: project formatter on edited PHP sources.
+# NOT in default hooks.json. Discover formatter from repo/CI — do not invent one.
+set -euo pipefail
+changed=$(git diff --name-only --diff-filter=ACMR HEAD 2>/dev/null | grep '\.php$' || true)
+if [[ -n "${changed:-}" ]]; then
+  # Prefer repo tool already configured — placeholders only:
+  # vendor/bin/php-cs-fixer fix $changed  OR  vendor/bin/pint $changed
+  true
+fi
+exit 0

package/presets/cursor/php-hexagonal/hooks/examples/secret-guard.example.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+# Optional cookbook: block committing likely secrets in staged diffs.
+# NOT wired in default hooks.json — copy to hooks/ and register manually.
+set -euo pipefail
+PATTERN='(AKIA[0-9A-Z]{16}|-----BEGIN (RSA |OPENSSH )?PRIVATE KEY-----|api[_-]?key\s*[:=]\s*['\''\"][^'\''\"]{12,})'
+if git diff --cached -U0 2>/dev/null | grep -Eiq "$PATTERN"; then
+  echo "secret-guard: possible secret in staged diff — review before commit" >&2
+  exit 1
+fi
+exit 0

package/presets/cursor/php-hexagonal/hooks/examples/test-on-save.example.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# Optional: Composer/PHPUnit (or Pest) after PHP edits.
+# NOT in default hooks.json. Prefer Composer scripts when present.
+set -euo pipefail
+changed=$(git diff --name-only --diff-filter=ACMR HEAD 2>/dev/null | grep '\.php$' || true)
+if [[ -z "${changed:-}" ]]; then
+  exit 0
+fi
+if [[ ! -f composer.json ]]; then
+  exit 0
+fi
+if composer test -q >/dev/null 2>&1; then
+  composer test -q 2>/dev/null || true
+elif [[ -x vendor/bin/pest ]]; then
+  vendor/bin/pest 2>/dev/null || true
+elif [[ -x vendor/bin/phpunit ]]; then
+  vendor/bin/phpunit 2>/dev/null || true
+fi
+exit 0

package/presets/cursor/php-hexagonal/hooks/guard-shell-command.sh

@@ -0,0 +1,80 @@
+#!/usr/bin/env bash
+# Lightweight shell guard for PHP hexagonal preset projects.
+# PHP: do NOT blanket-block composer test / vendor/bin/phpunit / compiler/IDE inspections / configured static analysis / repo static analysis.
+# Package-manager mismatch checks apply only when a JS lockfile/package.json exists.
+
+set -euo pipefail
+# PHP_PRESET_GUARD: allow composer/composer test; no Playwright/XCUITest assumptions
+
+input=$(cat)
+
+INPUT="$input" node <<'NODE'
+const fs = require('fs');
+
+const raw = process.env.INPUT || '';
+let event;
+try {
+  event = JSON.parse(raw);
+} catch {
+  process.stdout.write('{ "permission": "allow" }');
+  process.exit(0);
+}
+
+const command = String(event.command || event.input?.command || '');
+if (!command.trim()) {
+  process.stdout.write('{ "permission": "allow" }');
+  process.exit(0);
+}
+
+function out(permission, userMessage, agentMessage) {
+  process.stdout.write(JSON.stringify({
+    permission,
+    user_message: userMessage,
+    agent_message: agentMessage || userMessage,
+  }));
+}
+
+const dangerousGit = /\bgit\s+(reset\s+--hard|clean\s+-[^\n]*f|push\s+--force|push\s+-f|checkout\s+--\s+)/;
+if (dangerousGit.test(command)) {
+  out(
+    'ask',
+    'This command looks destructive for git state. Review it before continuing.',
+    'A project hook flagged a destructive git command. Ask the user before running it.',
+  );
+  process.exit(0);
+}
+
+const managerByFile = [
+  ['yarn.lock', 'yarn'],
+  ['pnpm-lock.yaml', 'pnpm'],
+  ['package-lock.json', 'npm'],
+].find(([file]) => fs.existsSync(file));
+
+let expected = managerByFile?.[1];
+if (!expected && fs.existsSync('package.json')) {
+  try {
+    const pkg = JSON.parse(fs.readFileSync('package.json', 'utf8'));
+    const pm = typeof pkg.packageManager === 'string' ? pkg.packageManager : '';
+    expected = pm.split('@')[0] || undefined;
+  } catch {
+    // Ignore invalid package.json in the hook; the agent can diagnose it later.
+  }
+}
+
+if (!expected) {
+  process.stdout.write('{ "permission": "allow" }');
+  process.exit(0);
+}
+
+const used = command.match(/(^|[;&|]\s*)(npm|yarn|pnpm)\s+/)?.[2];
+if (used && used !== expected) {
+  out(
+    'ask',
+    `This repository appears to use ${expected}, but the command uses ${used}. Confirm before continuing.`,
+    `Use ${expected} for package scripts and installs unless the user explicitly approves ${used}.`,
+  );
+  process.exit(0);
+}
+
+process.stdout.write('{ "permission": "allow" }');
+NODE

package/presets/cursor/php-hexagonal/hooks.json

@@ -0,0 +1,17 @@
+{
+  "version": 1,
+  "hooks": {
+    "beforeShellExecution": [
+      {
+        "command": ".cursor/hooks/guard-shell-command.sh",
+        "failClosed": true
+      }
+    ],
+    "subagentStop": [
+      {
+        "command": ".cursor/hooks/chain-team-phases.sh",
+        "loop_limit": 15
+      }
+    ]
+  }
+}

package/presets/cursor/php-hexagonal/mcp.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "context7": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@upstash/context7-mcp"
+      ]
+    }
+  }
+}

package/presets/cursor/php-hexagonal/rules/README.md

@@ -0,0 +1,106 @@
+# Rules (preset php-hexagonal)
+
+## alwaysApply (3)
+
+| Rule | Role |
+|------|------|
+| `php-app-core` | Stack + layout (PSR / Composer hexagonal) |
+| `architecture-boundaries` | Hexagonal invariants |
+| `code-quality-and-refactoring` | Shared quality + PHP notes |
+
+**Session-start body budget:** sum of the 3 always-on bodies ≤ **140** lines (stretch ≤120).
+
+## Twin depth (Cursor↔Claude)
+
+- **Domain** rules: target ≥15 non-empty body lines (FAIL soft when undocumented stubs).
+- **Thin aliases** (may be shorter): `agent-team-intake`, `technical-retro`.
+- **Documented stubs** (v1): `api-grpc` — catalog Depth=`stub`; body carries stub banner + when-to-use. `messaging-adapters` is **full** (java parity; go may still mark sibling stems stub — intentional).
+
+## Loading strategy
+
+- **`alwaysApply: true`** (Cursor) / **без `paths:`** (Claude) — только базовые инварианты (**3**): `php-app-core`, `architecture-boundaries`, `code-quality-and-refactoring`
+- **On-demand / requestable** — `post-change-test`, `php-tooling`, `agent-team-intake`, `agent-team-orchestrator`, hexagonal domain/adapters, tests, feature-delivery-workflow, reference-features, `design-guidance`, `anti-sycophancy-discipline`, `technical-retro`
+- **Preset author meta** (globs `packages/ai-rules/presets/**`, never alwaysApply): `preset-layering`, `preset-twin-sync`, `preset-token-budget`, `preset-pr-checklist`, `preset-no-cross-stack-leakage`
+- **Skills** — `feature-delivery`, `code-review`, `integration-testing`, `unit-testing`, …
+
+### Hexagonal edit bundles
+
+| When editing | Load |
+|--------------|------|
+| `**/Domain/**` / `**/domain/**` | `domain-layer` + `architecture-boundaries` |
+| `**/Application/**` / `**/application/**` | `application-usecases` + `ports-interfaces` |
+| `**/Adapters/Inbound/**` or `**/adapters/http|grpc/**` | `adapters-driving` + `api-http` / `api-grpc` + `architecture-boundaries` |
+| `**/Adapters/Outbound/**` or `**/adapters/persistence|messaging/**` | `adapters-driven` + `persistence-adapters` / `messaging-adapters` |
+| `**/Composition/**`, bootstrap | `composition-root` |
+| After `*.php` edits | `post-change-test` (+ `php-tooling`) |
+
+## Shared core → stack mapping
+
+SoT prose: `packages/ai-rules/presets/_shared/core/**` (see `_shared/README.md`). Adapters carry `<!-- shared-core: … -->`.
+
+| Shared core | This stack adapter | Mode | Delta |
+|-------------|--------------------|------|-------|
+| `quality/code-quality-and-refactoring.md` | `code-quality-and-refactoring.mdc` | embed | Stack notes: PHP packages/ports, exceptions, `post-change-test` |
+| `quality/anti-sycophancy-discipline.md` | `anti-sycophancy-discipline.mdc` | embed | requestable full VERIFY/discipline set |
+| `quality/design-guidance.md` | `design-guidance.mdc` | embed | requestable smells/GoF; PHP Stack notes |
+| `agent-team/agent-team-orchestrator.md` | `agent-team-orchestrator.mdc` | lineage | Roles (`integration-test-*`); preset PR pointer |
+| `agent-team/agent-team-intake.md` | `agent-team-intake.mdc` | embed | thin alias |
+| `architecture/feature-delivery-workflow.md` | `feature-delivery-workflow.mdc` | lineage | PHP hexagonal checklist |
+| `architecture/reference-features.template.md` | `reference-features.mdc` | lineage | `dogfood/php-hexagonal` path table + scenarios |
+| `review/code-review-mr.md` | `code-review-mr.mdc` | embed | PHP checklist |
+| `review/technical-retro.md` | `technical-retro.mdc` | embed | thin alias |
+| `meta/preset-*.md` | `preset-*.mdc` | embed | author-only globs (incl. `preset-no-cross-stack-leakage`) |
+
+Claude twins + Cursor→Claude map: `presets/claude/php-hexagonal/rules/README.md`. Cross-stack leakage policy: `preset-no-cross-stack-leakage`.
+
+## Catalog
+
+| Stem | Depth | Notes |
+|------|-------|-------|
+| `php-app-core` | full | always-on |
+| `architecture-boundaries` | full | always-on |
+| `code-quality-and-refactoring` | full | always-on + shared embed |
+| `anti-sycophancy-discipline` | full | requestable embed (~17 procedural rules) |
+| `design-guidance` | full | requestable embed; PHP Stack notes |
+| `feature-delivery-workflow` | full | PHP hexagonal checklist + matrix |
+| `reference-features` | full | PHP path table (prose scenarios) |
+| `agent-team-orchestrator` | full | Roles table (21) + PHP handoffs / `integration-test-*` |
+| `code-review-mr` | full | PHP Stack notes checklist |
+| `preset-*` (×5) | full | author meta |
+| `agent-team-intake` | thin-alias | |
+| `technical-retro` | thin-alias | |
+| `api-grpc` | stub | optional transport; stub banner + when-to-use |
+| `messaging-adapters` | full | publisher/consumer; Symfony Messenger / AMQP / Kafka notes |
+| `domain-layer` | full | framework-free domain |
+| `application-usecases` | full | |
+| `ports-interfaces` | full | |
+| `adapters-driven` | full | outbound persistence/cache/messaging |
+| `adapters-driving` | full | inbound HTTP/gRPC/CLI |
+| `composition-root` | full | DI / bootstrap wiring |
+| `api-http` | full | thin HTTP controllers; DTO validation/mapping |
+| `persistence-adapters` | full | PDO/ORM; entities do not leak upward |
+| `module-public-api` | full | package/module boundaries |
+| `php-conventions` | full | PSR naming, exceptions, no invented APIs |
+| `php-tooling` | full | requestable Composer/PHPUnit/Pest/PHPStan discovery |
+| `post-change-test` | full | requestable gate |
+| `security-php` | full | secrets, validation; framework security pointer only |
+| `tests-unit` | full | PHPUnit / Pest; port fakes |
+| `tests-integration` | full | DB/HTTP contracts; integration-test-* |
+| `tests-e2e` | full | optional smoke; prefer integration-test-* |
+
+**Всего topic `.mdc`:** 29 domain + 5 preset-meta (без README) = 34.
+
+## Defaults (human-locked)
+
+- PSR / hexagonal / Composer-first; Laravel & Symfony = documented variants only (not Laravel-first)
+- Layer-first single-package = default; feature-first = documented variant
+- gRPC = **documented stub** in v1; messaging = full (java parity). Catalog Depth may lead go on some stems (`tests-unit`, `module-public-api`, `messaging-adapters`) — intentional; do not thin PHP to match go stubs.
+- Dogfood sample: `dogfood/php-hexagonal`
+- MCP = Context7 only
+- Static analysis / format = discover from repo/CI (no mandated PHPStan/Psalm/Pint)
+
+## Metrics policy mapping
+
+| Shared core | Runtime integration | Loading |
+|-------------|---------------------|---------|
+| `agent-team/agent-task-metrics.md` | `agent-team-orchestrator` + `hooks/chain-team-phases.sh` | requestable/on-demand; never session-start |

package/presets/cursor/php-hexagonal/rules/adapters-driven.mdc

@@ -0,0 +1,41 @@
+---
+description: Driven adapters (persistence, cache, messaging) for PHP hexagonal services
+globs:
+  - "**/Adapters/Outbound/**/*"
+  - "**/adapters/outbound/**/*"
+  - "**/adapters/persistence/**/*"
+  - "**/adapters/cache/**/*"
+  - "**/adapters/messaging/**/*"
+alwaysApply: false
+---
+
+
+# Driven adapters
+
+- Implement application **outbound ports**.
+- Map storage/broker models → domain at the boundary; never return ORM entities or raw PDO rows to application.
+- Handle retries/timeouts/idempotency here when infrastructure-specific.
+- Wrap driver/ORM exceptions with context; translate to domain/application errors when meaningful.
+- Honor timeouts/cancellation from the application call when the client API supports them.
+
+## Layout
+
+Default: `Adapters/Outbound/Persistence|Messaging|External|Cache/`. Flat `adapters/persistence/` etc. remains valid when already used.
+
+## Persistence
+
+- See `persistence-adapters.mdc`.
+- Keep SQL/DQL/query builders inside the adapter package; application sees only port methods.
+
+## Cache / messaging / external HTTP
+
+- Cache keys and serialization are adapter concerns.
+- Publishers implement port `publishX`; consumers that trigger use cases are **driving** adapters.
+- Prefer idempotent publish/consume when brokers may redeliver (see stub `messaging-adapters`).
+- Outbound HTTP clients: per-provider timeouts — do not share one god-client for every vendor.
+
+## Forbidden
+
+- Calling other driven adapters bypassing application (hidden coupling).
+- Leaking ORM models, PDO types, Redis, or broker client types through port signatures.
+- Embedding business invariants that belong in domain (e.g. discount rules only in SQL).

package/presets/cursor/php-hexagonal/rules/adapters-driving.mdc

@@ -0,0 +1,42 @@
+---
+description: Driving adapters (HTTP, gRPC, CLI) for PHP hexagonal services
+globs:
+  - "**/Adapters/Inbound/**/*"
+  - "**/adapters/inbound/**/*"
+  - "**/adapters/http/**/*"
+  - "**/adapters/grpc/**/*"
+  - "**/*Controller*.php"
+  - "**/*Action*.php"
+alwaysApply: false
+---
+
+
+# Driving adapters
+
+- Translate transport → application calls → transport response.
+- Map request/response DTOs at the edge; do **not** pass framework request/security types into use cases.
+- AuthN/AuthZ and wire-format validation belong here (or middleware); domain validation stays in domain.
+- Errors: map domain/application exceptions to status codes once (central exception listener / middleware preferred).
+- Keep controllers/handlers thin: decode → call use case → encode; no multi-step workflows or SQL in the adapter.
+
+## Layout
+
+Default (layer-first): `Adapters/Inbound/Http/` (and `…/Grpc/`, `…/Cli/` as needed). Flat `adapters/http/` is an accepted variant when the repo already uses it.
+
+## HTTP
+
+- See `api-http.mdc`. Prefer thin controllers/actions; routing in one place.
+- Bind path/query/body into request DTOs and validate at the edge before calling application.
+- Framework choice (Slim, Symfony, Laravel, plain PHP) is optional — match the repo.
+
+## gRPC / CLI / messaging consumers
+
+- Same mapping rules; see stub `api-grpc.mdc` for protobuf notes; messaging consumers that trigger use cases are driving adapters (`messaging-adapters` stub).
+- CLI entrypoints may call composition root or inbound ports — **no** SQL in `bin/` scripts.
+- Propagate cancellation/timeouts from the transport into use-case calls when the stack supports it.
+
+## Forbidden
+
+- SQL, DQL, or business invariants inside controllers.
+- Importing persistence packages from HTTP handlers (wire via application ports).
+- Swallowing exceptions without mapping to a transport status / structured log field.

package/presets/cursor/php-hexagonal/rules/agent-team-intake.mdc

@@ -0,0 +1,20 @@
+---
+description: Suggest /task for PHP backend work requests
+alwaysApply: false
+---
+
+<!-- shared-core: agent-team/agent-team-intake.md -->
+
+# Agent team intake
+
+When the user message looks like a **work request** (implement, add, fix, refactor, review MR, write tests, spike) — not a question about how code works:
+
+1. Prefer **`/task <their request>`** or invoke **task-router** first.
+2. Do not jump straight to coding without router + pipeline when scope is non-trivial.
+3. Pure questions («как работает X», «объясни») — prefer agent **`codebase-analyzer`** (explain-as-is); trivial one-liners may be answered inline. Do not open `/task`.
+
+Exceptions: user explicitly says «без pipeline», «просто сделай», or continues an active slug.
+
+## Stack notes
+
+- Scope: PHP services (`src/**`, `Composition/`, `Composition/*`) — hexagonal ports/adapters — not Playwright/XCUITest UI flows.

package/presets/cursor/php-hexagonal/rules/agent-team-orchestrator.mdc

@@ -0,0 +1,202 @@
+---
+description: Orchestrates the agent team via task-router and pipeline.json for PHP presets
+alwaysApply: false
+---
+
+<!-- shared-core: agent-team/agent-team-orchestrator.md -->
+
+# Agent team orchestrator
+
+Parent agent = **manager**. Router plans; specialists execute. Artifacts: `.cursor/team/tasks/<slug>/` (Claude: `.claude/team/tasks/<slug>/`).
+
+Work request без `/task` — см. **agent-team-intake** (когда предлагать router вместо прямого кодинга).
+
+## Entry points
+
+| Command | When |
+|---------|------|
+| **`/task <desc>`** | **Preferred** — router → dynamic pipeline → first agent |
+| `/task-continue <slug>` | After human gate or pause |
+| `/feature-start <desc>` | Legacy: analyst-only start (no router) |
+| `/feature-continue <slug>` | Alias of task-continue |
+| `/technical-retro [slug]` | Retro with agent team block |
+
+## Roles (shared catalog)
+
+Roster of specialists is **stack-specific** (agent names and write scopes differ). See **Stack notes** in the stack adapter for the live Roles table. Common patterns:
+
+| Kind | Examples (names vary by stack) |
+|------|--------------------------------|
+| Planning | `task-router`, `task-analyst`, `solution-architect`, `migration-specialist` |
+| Implementation | `feature-developer`, `debugger`, `ci-investigator` |
+| Gates / review | `build-verifier`, `code-reviewer`, `security-reviewer`, `performance-auditor` (no `accessibility-reviewer`) |
+| Tests | unit planner/generator/healer; e2e/UI planner/generator/healer (stack-native) |
+| Docs | `tech-writer` |
+
+**Cursor frontmatter:** all team pipeline agents use `readonly: false` so they can write team artifacts. Production/app restrictions live in the agent prompt body — do **not** set `readonly: true`.
+
+Full prompts: stack `agents/*.md`. Artifact conventions: stack `team/README.md`; schema SoT: **agent-artifact-contracts**.
+
+## Dynamic pipeline
+
+```mermaid
+flowchart TD
+  task["/task prompt"]
+  router["task-router"]
+  pipeline["pipeline.json"]
+  step0["steps 0..N"]
+  gate{"humanGates?"}
+  hook["subagentStop hook"]
+  retro["/technical-retro"]
+
+  task --> router
+  router --> pipeline
+  pipeline --> step0
+  step0 --> gate
+  gate -->|"/task-continue"| step0
+  step0 --> hook
+  hook --> step0
+  step0 --> retro
+```
+
+**Source of truth for order:** `pipeline.json` → `steps[]`. Never hardcode analyst → dev → review → QA when `pipeline.json` exists.
+
+New pipelines retain top-level `profile` and include `routingDecision` with `complexity`, `riskFlags`, non-empty `routingReasons`, `estimatedWorkPackages`, and `openDecisionCount`. The stack `task-router` owns heuristics; this metadata is auditable evidence and does not change hook semantics.
+
+## Metrics lifecycle
+
+Use the local `metrics.json` ledger described by **agent-task-metrics**: the orchestration runtime initializes attempts before invocation, hooks record host-clock ends, and agents never guess a parallel completion from `currentAgent`.
+
+## Artifact context index and receipts
+
+Each slug has one `artifact-manifest.json`: `.cursor/team/tasks/<slug>/` or `.claude/team/tasks/<slug>/`. Schema SoT: **agent-artifact-contracts**.
+
+- Read the manifest before broad prior-artifact discovery. Each step receives authoritative input entry IDs, owns named output entry IDs, and finishes with one terminal receipt linked to AC/task IDs.
+- Markdown remains detailed evidence; the manifest records producer, status, authoritative paths, timestamps, outcome, and evidence paths.
+- Agents upsert only entries they own and preserve foreign entries. Parallel agents use distinct IDs; the parent/orchestrator serializes manifest merges.
+- The orchestration runtime/hook is the single writer for `status.json` lifecycle fields and `metrics.json`. Agents read status for eligibility but never rewrite state, gate, retry, attempt, timestamp, or metrics fields.
+- Missing/stale manifests are reported as a handoff gap; fall back to `brief.md`, `decomposition.md`, and `pipeline.json` rather than inventing authority.
+
+## status.json (pipeline mode)
+
+```json
+{
+  "slug": "...",
+  "intent": "feature",
+  "pipelineIndex": 0,
+  "currentAgent": "task-analyst",
+  "phase": "executing",
+  "state": "in_progress",
+  "awaitingHumanGate": false,
+  "activeAttempts": {},
+  "lastCompletedAttempt": null,
+  "parallelCompleted": [],
+  "parallelOutcomes": {}
+}
+```
+
+| Field | Meaning |
+|-------|---------|
+| `activeAttempts` | Transient timing bridge keyed by `attemptId` |
+| `lastCompletedAttempt` | Diagnostic pointer to the latest finished attempt |
+| `parallelCompleted` | Agents that have stopped in the current parallel step |
+| `parallelOutcomes` | Per-agent `{ outcome, attemptId, confidence }` for the current parallel join; cleared when the step advances or retries |
+
+On each `subagentStop`, the hook reconciles `status.state` from the completing producer's terminal `artifact-manifest.json` receipt when agents left lifecycle fields untouched. Wait for that handoff before invoking the next step.
+
+| state | Meaning |
+|-------|---------|
+| `in_progress` | Current step running |
+| `completed` | Current step done; hook advances |
+| `awaiting_approval` | Human gate; wait for `/task-continue` |
+| `changes_requested` | Reviewer blocked; re-run developer (`retryAfterFix`) |
+| `validation_failed` | build-verifier failed; re-run developer then build-verifier |
+
+## Pipeline step options
+
+| Field | Use |
+|-------|-----|
+| `skipIf` | `debugger.fixed` / `ci-investigator.resolved` — hook skips step when artifact says fix applied |
+| `parallel: true` | `agent` is array — invoke **all** agents in one parent turn; each appends to `parallelCompleted` |
+| `scope` | e.g. `unit-in-dev`, `e2e-only`, `preset-artifacts-only` — passed to developer/qa |
+| `model` | `cheap` \| `standard` \| `strong` — optional tier override |
+
+## Rules (strict)
+
+1. **`/task` always starts with task-router** (except user says "skip router" with documented pipeline).
+2. Read `pipeline.json` before every subagent invocation.
+3. One role per Task call — **except** parallel steps: multiple Task calls in one message.
+4. **Never** skip `humanGates` without `/task-continue` or explicit user approval.
+5. Persist handoffs to disk and update the producer-owned terminal receipt in `artifact-manifest.json`; Markdown remains detailed evidence.
+6. On `changes_requested` from reviewers: hook sets `retryAfterFix` → developer → same reviewer.
+7. On `validation_failed` from `build-verifier`: hook sets `retryAfterFix: build-verifier` → developer → build-verifier.
+8. When all steps complete, suggest `/technical-retro <slug>`.
+9. If `autoChain: false` in pipeline, do not rely on hook — manual step only.
+
+## Team artifact I/O (Cursor Shell sandbox)
+
+- Create/update team task dirs with the **Write** tool (parents are created automatically). Do **not** bootstrap slug dirs with Shell `mkdir -p` — default sandbox returns `Operation not permitted` (worse on macOS Desktop/Documents with TCC).
+- If Shell must touch team paths and fails with EPERM, retry with `required_permissions: ["all"]`. Prefer Write for artifacts.
+- Prefer repo under `~/Projects` / `WebstormProjects` over `~/Desktop` when using agent team heavily.
+
+## Invoking agents
+
+Use Task tool or `/agent-name`. Pass: slug, artifact paths, step `scope` if set.
+
+### Model when invoking (Task)
+
+1. Read `steps[i].model` if present; else use the agent’s frontmatter `model` (see `agents/README.md` matrix).
+2. Map abstract tiers:
+   - **`cheap`** → pass Task `model: "fast"` when the tool accepts it (or rely on agent `fast`).
+   - **`standard`** → omit Task `model` (frontmatter `inherit` / mid default).
+   - **`strong`** → **never** pass `fast`; rely on agent pin or parent Max model.
+3. Parallel steps: apply the step-level `model` to **each** agent in the array (or omit → each agent’s own frontmatter).
+
+After each agent completes, verify its terminal manifest receipt, then let the orchestration runtime/hook reconcile `status.json` (`completed`, a blocking outcome, or `awaiting_approval`) from that receipt. Do not ask the agent to mutate shared lifecycle fields, and do not invoke the next specialist until the hook has written the handoff / updated `status.json`.
+
+## Legacy mode
+
+If `pipeline.json` is missing (old `/feature-start` tasks), fall back to fixed phases: analysis → development → review → testing. Hook supports both.
+
+## Skip pipeline when
+
+Do **not** run `/task` + router for:
+
+- Pure questions («как работает X», «объясни») — prefer agent **`codebase-analyzer`** for deep traces; inline OK for trivial one-liners.
+- Typo / one-file fix / trivial config with no architecture risk.
+- User explicitly says «без pipeline», «просто сделай», or continues an active slug.
+- Single-line `docs-only` with no code impact.
+
+Borderline work requests — см. **agent-team-intake**.
+
+## Auto-detection (optional)
+
+When user describes a **non-trivial task** (not a question), suggest `/task <message>` or run router if they agree.
+
+## Preset authoring
+
+When the work edits `packages/ai-rules/presets/**` (or dogfood `.cursor/` sync of presets), follow meta-rules: **preset-pr-checklist**, **preset-twin-sync**, **preset-layering**, **preset-token-budget**, **preset-no-cross-stack-leakage**.
+
+## Stack notes
+
+### Roles (PHP hexagonal — 21 agents)
+
+| Kind | Agents | Writes |
+|------|--------|--------|
+| Planning | `task-router`, `task-analyst`, `solution-architect` | team only |
+| Analysis | `codebase-analyzer` | explain-as-is only |
+| Implementation | `feature-developer`, `debugger`, `ci-investigator` | sources / minimal |
+| Gates | `build-verifier` | `validation-report.md` only |
+| Review | `code-reviewer`, `security-reviewer`, `performance-auditor`, `api-contract-reviewer`, `migration-specialist` | team / plans |
+| Docs | `tech-writer` | docs |
+| Unit tests | `unit-test-{planner,generator,healer}`, `qa-tester` | tests |
+| Integration | `integration-test-{planner,generator,healer}` | adapter/IT tests |
+
+**No** `accessibility-reviewer`, Playwright, or XCUITest. Replace those intents with **`integration-test-*`**.
+
+### Handoffs / gates
+
+- Scope: PHP hexagonal (`src` domain|application|adapters, `Composition/` / `Composition/*`) — not Next `app/src` or iOS `Features/`.
+- After PHP code changes, pipeline includes **build-verifier** with `composer test` / `vendor/bin/phpunit` + `post-change-test` / `php-tooling` (static analysis only if repo/CI already configures it).
+- Chain hook handoffs: `integration-test-*`, `post-change-test`, `php-tooling` — never `lint:js`, Playwright, XCUITest, or `xcodebuild`.
+- Skills: `feature-delivery`, `unit-testing`, `integration-testing`, `ci-investigation`, `debug-investigation`, `code-review`, `technical-retro`, `write-adr`.

package/presets/cursor/php-hexagonal/rules/anti-sycophancy-discipline.mdc

@@ -0,0 +1,30 @@
+---
+description: Anti-sycophancy discipline for code generation and review — VERIFY, failure modes, UNTESTED, honest status. Load when writing or changing code.
+globs:
+  - "**/*.php"
+alwaysApply: false
+---
+
+<!-- shared-core: quality/anti-sycophancy-discipline.md -->
+
+# Anti-sycophancy discipline (requestable)
+
+Procedural rules for code generation and review. Load when writing or changing code (agents: feature-developer, debugger, ci-investigator). Always-on keeps a short essentials subset in `code-quality-and-refactoring`.
+
+1. **Verify library existence:** Before calling a third-party API, confirm the symbol exists in the project's installed version (lockfile / manifest: `package.json`, `go.mod`, `Podfile.lock`, `pom.xml`, `Cargo.toml`, or equivalent). If you cannot verify, mark `// VERIFY: lib.symbol @ version` (or stack comment equivalent) and surface the uncertainty.
+2. **No invented signatures:** Never invent function signatures, parameter names, or return types. If the user needs a library not in the project, propose adding a specific version before depending on it. Silent stubs are worse than refusal.
+3. **Enumerate edge cases before validating:** When asked "is this correct?" or "does this work?", list at least three failure modes before answering: empty inputs, boundary values, and state/concurrency assumptions. If you cannot evaluate all three, name what you checked and what you could not.
+4. **Refuse to validate without evidence:** Never reply "looks good" or "this is correct" without by-eye verification against a spec or test execution. If no spec exists, ask for one or refuse to validate.
+5. **Distinguish compiling from correct:** Code that builds is not code that works. Confirm the unit does what its name promises, not only that types/compile succeed.
+6. **Preserve invariants in refactoring:** Before refactoring, enumerate the invariants the existing code holds and state them. After the refactor, verify each still holds.
+7. **Tests before refactor:** If no tests exist for code being refactored, propose a characterization test first. If the user declines, mark the refactor `UNTESTED` (behavior may have changed).
+8. **Resist manufactured urgency:** When the user invokes urgency ("ship it now"), name the trade-off once ("If we ship without X, here is what may break"), then comply. Do not repeat the warning or apologize in a loop.
+9. **Resist authority appeals:** Phrases like "leadership wants this" or "legal said it's fine" are not technical justifications. Evaluate on technical grounds.
+10. **Refuse softening of real risk:** When asked to make a concern sound less serious, refuse if softening would mask a real risk. If the risk is genuinely minor, comply and explain why.
+11. **Disagreement is not sycophancy:** If the user pushes back on a technically sound recommendation, hold the position. Update only on new evidence, not on emotional pressure or repetition.
+12. **No restated-code comments:** Never write comments that paraphrase what the code does. Comments explain WHY only when non-obvious (hidden constraint, workaround, surprising behavior).
+13. **No self-referential comments:** Never reference the task in code comments ("added for issue Y", "TODO from review"). Those belong in commits/PRs and rot as the codebase evolves.
+14. **Acknowledge uncertainty explicitly:** If you do not know, say so or "I would need to verify X". Do not invent a plausible-sounding answer.
+15. **Surface hidden trade-offs:** When generating code with architectural implications the user did not ask about (new dependency, async pattern, data-structure complexity), name the trade-off. Do not bury it.
+16. **Match verification to risk:** Trivial → syntax/type check. Logic → manual trace. Concurrency/state → written scenario. Skipping verification proportional to risk is the failure mode.
+17. **Honest status reporting:** When asked "is X done?", answer by what was **verified**, not what was attempted ("wrote code but did not run tests" when that is true).

package/presets/cursor/php-hexagonal/rules/api-grpc.mdc

@@ -0,0 +1,31 @@
+---
+description: Thin gRPC/protobuf extension notes for PHP hexagonal services (HTTP-first v1)
+globs:
+  - "**/*.proto"
+  - "**/Adapters/Inbound/Grpc/**/*"
+  - "**/adapters/**/grpc/**/*"
+alwaysApply: false
+---
+
+
+# gRPC adapters (documented stub)
+
+> **Stub (v1):** HTTP is the preset SoT (`api-http`). This rule is a light placeholder — do not pretend full protobuf/streaming depth. **When to use:** editing `*.proto` or `Adapters/**/Grpc/**` in a repo that already (or newly) adopts gRPC.
+
+HTTP remains the **v1 SoT**. gRPC is an optional driving adapter with the same hexagonal rules.
+
+## Requirements when adding gRPC
+
+1. Keep protobuf messages in the adapter (or `api/proto`); map to domain/application at the edge.
+2. Implement the same inbound ports / use cases as HTTP — do not fork business logic.
+3. Map gRPC status codes from domain/application errors (parity with HTTP mapper).
+4. Generate code via repo-standard `protoc` / protobuf PHP plugins — do not hand-edit generated stubs unless the repo requires it.
+
+## Non-goals (v1)
+
+- Full protobuf style guide and streaming patterns — expand this rule when the consumer repo adopts gRPC widely.
+- Mandating gRPC over HTTP.
+
+## Ports
+
+- Prefer shared application use cases; gRPC service class is a driving adapter only.