@7n/rules 1.0.0

package/rules/npm-module/rule_meta/concern.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://unpkg.com/@7n/rules/schemas/concern.json",
+  "fixability": "config",
+  "lint": {
+    "scope": "full",
+    "glob": ["npm/rules/**/main.json", "npm/rules/**/main.mjs", "npm/rules/**/main.mdc", "npm/rules/**/auto.md"]
+  }
+}

package/rules/npm-module/rule_meta/docs/main.md

@@ -0,0 +1,35 @@
+---
+type: JS Module
+title: main.mjs
+resource: npm/rules/npm-module/rule_meta/main.mjs
+docgen:
+  crc: 3c4c2ca7
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 95
+  issues: anchor-miss:(scripts.mdc),judge:inaccurate:0.98
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Lint-детектор concern-а `npm-module/rule_meta`: валідує метадані кожного правила у `npm/rules/<id>/` — файл `main.json` та супутні конвенції каталогу правила.
+
+## Поведінка
+
+1. Якщо `npm/rules/` відсутній — pass (немає правил для валідації).
+2. Для кожної теки правила:
+   - `auto.md` є пережитком — якщо файл лишився, порушення (метадані тепер у `main.json`).
+   - `main.mdc` обовʼязковий (канон scripts.mdc) — відсутність = порушення.
+   - `main.json` має існувати і бути валідним JSON-обʼєктом.
+   - Поле `auto` (опційне) має відповідати одній з форм: `"завжди"` / масив / `{ glob }` / `{ predicate }`; предикат має бути зареєстрований у `RULE_PREDICATES`.
+   - Поле `lint` заборонене: rule-level lint-scope скасовано (spec 2026-06-28-concern-lint-scope-design) — lint-поверхня декларується у `<rule>/<concern>/concern.json#lint`.
+   - Поле `llmFix` заборонене: opt-in-прапорця немає — fix-можливість концерну визначається наявністю `fix-*.mjs`/`fix-worker.mjs`.
+3. Повертає `LintResult` зі списком порушень; валідні правила репортяться як pass.
+
+## Публічний API
+
+lint — перевіряє `main.json` усіх правил у `npm/rules/` і повертає `{ violations }`.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

package/rules/npm-module/rule_meta/main.mjs

@@ -0,0 +1,119 @@
+/** @see ./docs/main.md */
+import { existsSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { createViolationReporter } from '../../../scripts/lib/lint-surface/violation-reporter.mjs'
+import { parseRuleAutoSpec, readRuleMetaRaw } from '../../../scripts/lib/rule-meta.mjs'
+import { RULE_PREDICATES } from '../../../scripts/lib/rule-predicates.mjs'
+
+/**
+ * Перевіряє поле `auto` у meta.json одного правила.
+ * @param {string} id ідентифікатор правила
+ * @param {Record<string, unknown>} raw сирий meta.json
+ * @param {ReturnType<typeof createViolationReporter>} reporter репортер
+ * @returns {boolean} true, якщо поле валідне (або відсутнє)
+ */
+function checkAutoField(id, raw, reporter) {
+  if (raw.auto === undefined) return true
+  const spec = parseRuleAutoSpec(raw.auto)
+  if (spec === null) {
+    const autoHint = 'нерозпізнане (очікується "завжди" / масив / {glob} / {predicate})'
+    reporter.fail(`rules/${id}: main.json.auto ${autoHint}`)
+    return false
+  }
+  if ('predicate' in spec && !Object.hasOwn(RULE_PREDICATES, spec.predicate)) {
+    reporter.fail(`rules/${id}: main.json — невідомий predicate "${spec.predicate}" (немає в RULE_PREDICATES)`)
+    return false
+  }
+  return true
+}
+
+/**
+ * Забороняє залишкове поле `lint` у meta.json правила.
+ * Канон (spec 2026-06-28-concern-lint-scope-design): lint-scope живе у
+ * `<rule>/<concern>/concern.json#lint`, rule-level `main.json.lint` скасовано.
+ * @param {string} id ідентифікатор правила
+ * @param {Record<string, unknown>} raw сирий meta.json
+ * @param {ReturnType<typeof createViolationReporter>} reporter репортер
+ * @returns {boolean} true, якщо поле відсутнє
+ */
+function checkLintField(id, raw, reporter) {
+  if (raw.lint === undefined) return true
+  reporter.fail(`rules/${id}: main.json.lint скасовано — lint-scope декларується у <concern>/concern.json#lint`)
+  return false
+}
+
+/**
+ * Забороняє залишкове поле `llmFix` у meta.json правила.
+ * Канон (scripts.mdc, spec 2026-06-28-concern-lint-scope-design): opt-in-прапорця
+ * llmFix немає — fix-можливість концерну визначається наявністю `fix-*.mjs`/`fix-worker.mjs`.
+ * @param {string} id ідентифікатор правила
+ * @param {Record<string, unknown>} raw сирий meta.json
+ * @param {ReturnType<typeof createViolationReporter>} reporter репортер
+ * @returns {boolean} true, якщо поле відсутнє
+ */
+function checkLlmFixField(id, raw, reporter) {
+  if (raw.llmFix === undefined) return true
+  reporter.fail(
+    `rules/${id}: main.json.llmFix скасовано — fix-можливість = наявність fix-*.mjs/fix-worker.mjs у концерні`
+  )
+  return false
+}
+
+/**
+ * Валідує meta.json одного правила.
+ * @param {string} id ідентифікатор правила
+ * @param {string} ruleDir каталог правила
+ * @param {ReturnType<typeof createViolationReporter>} reporter репортер
+ * @returns {void}
+ */
+function checkRule(id, ruleDir, reporter) {
+  let ruleOk = true
+
+  if (existsSync(join(ruleDir, 'auto.md'))) {
+    reporter.fail(`rules/${id}: залишковий auto.md — видали (метадані тепер у main.json)`)
+    ruleOk = false
+  }
+
+  // Канон (scripts.mdc): main.mdc — ОБОВ'ЯЗКОВИЙ у кожному npm/rules/<id>/.
+  if (!existsSync(join(ruleDir, 'main.mdc'))) {
+    reporter.fail(`rules/${id}: відсутній main.mdc — обов'язковий (scripts.mdc)`)
+    ruleOk = false
+  }
+
+  const raw = readRuleMetaRaw(ruleDir)
+  if (!raw) {
+    reporter.fail(`rules/${id}: відсутній або невалідний main.json`)
+    return
+  }
+
+  if (!checkAutoField(id, raw, reporter)) ruleOk = false
+  if (!checkLintField(id, raw, reporter)) ruleOk = false
+  if (!checkLlmFixField(id, raw, reporter)) ruleOk = false
+
+  if (ruleOk) {
+    reporter.pass(`rules/${id}: main.json валідний`)
+  }
+}
+
+/**
+ * Валідує всі `npm/rules/<id>/meta.json`.
+ * @param {import('../../../scripts/lib/lint-surface/types.mjs').LintContext} ctx Контекст лінту (`cwd` тощо).
+ * @returns {Promise<import('../../../scripts/lib/lint-surface/types.mjs').LintResult>} Результат лінту зі списком violations.
+ */
+export function lint(ctx) {
+  const cwd = ctx.cwd
+  const reporter = createViolationReporter(ctx)
+  const rulesDir = join(cwd, 'npm', 'rules')
+  if (!existsSync(rulesDir)) {
+    reporter.pass('npm/rules/ відсутній — немає правил для валідації')
+    return Promise.resolve(reporter.result())
+  }
+
+  for (const entry of readdirSync(rulesDir, { withFileTypes: true })) {
+    if (!entry.isDirectory() || entry.name.startsWith('.')) continue
+    checkRule(entry.name, join(rulesDir, entry.name), reporter)
+  }
+
+  return Promise.resolve(reporter.result())
+}

package/rules/npm-module/rule_meta/rule_meta.mdc

@@ -0,0 +1,11 @@
+## Валідація `main.json` правил
+
+Кожне правило у `npm/rules/<id>/` повинно мати коректний `main.json` (метадані правила).
+
+Перевірки (`rule_meta.mjs`):
+
+- **`main.mdc` обовʼязковий** у кожному `npm/rules/<id>/` — без нього `check` падає.
+- **`auto.md` є пережитком** — якщо такий файл залишився, `check` вимагає його видалити (метадані тепер у `main.json`).
+- **`main.json` має бути валідним JSON** із коректними полями:
+  - **`auto`** (опційне): `"завжди"` / масив glob-рядків / `{ glob }` / `{ predicate }`. Якщо `predicate` вказано — він має бути зареєстрований у `RULE_PREDICATES`.
+  - **`lint` заборонене**: rule-level scope скасовано — lint-поверхня декларується per-concern у `<rule>/<concern>/concern.json#lint` (spec 2026-06-28-concern-lint-scope-design).

package/rules/npm-module/skill_meta/concern.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "https://unpkg.com/@7n/rules/schemas/concern.json",
+  "fixability": "config",
+  "lint": { "scope": "full", "glob": ["npm/skills/**/main.json", "npm/skills/**/auto.md"] }
+}

package/rules/npm-module/skill_meta/docs/main.md

@@ -0,0 +1,149 @@
+---
+type: JS Module
+title: main.mjs
+resource: npm/rules/npm-module/skill_meta/main.mjs
+docgen:
+  crc: cefe56b0
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+  issues: judge:inaccurate:0.99
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+system_message:
+You are an expert coding assistant operating inside pi, a coding agent harness. You help users by reading files, executing commands, editing code, and writing new files.
+
+Available tools:
+(none)
+
+In addition to the tools above, you may have access to other custom tools depending on the project.
+
+Guidelines:
+
+- Be concise in your responses
+- Show file paths clearly when working with files
+
+Pi documentation (read only when the user asks about pi itself, its SDK, extensions, themes, skills, or TUI):
+
+- Main documentation: /Users/vitalii/www/nitra/cursor/node_modules/@earendil-works/pi-coding-agent/README.md
+- Additional docs: /Users/vitalii/www/nitra/cursor/node_modules/@earendil-works/pi-coding-agent/docs
+- Examples: /Users/vitalii/www/nitra/cursor/node_modules/@earendil-works/pi-coding-agent/examples (extensions, custom tools, SDK)
+- When reading pi docs or examples, resolve docs/... under Additional docs and examples/... under Examples, not the current working directory
+- When asked about: extensions (docs/extensions.md, examples/extensions/), themes (docs/themes.md), skills (docs/skills.md), prompt templates (docs/prompt-templates.md), TUI components (docs/tui.md), keybindings (docs/keybindings.md), SDK integrations (docs/sdk.md), custom providers (docs/custom-provider.md), adding models (docs/models.md), pi packages (docs/packages.md)
+- When working on pi topics, read the pi .md files completely and follow .md cross-references before implementing
+- Always read pi .md files completely and follow links to related docs (e.g., tui.md for TUI API details)
+
+<project_context>
+Project-specific instructions and guidelines:
+
+<project_instructions path="/Users/vitalii/www/nitra/cursor/AGENTS.md">
+
+# AGENTS.md version: '1.0'
+
+## Purpose
+
+This file is the entry point for all AI agents working with this repository.
+
+## Rule source
+
+The primary development rules are stored in the Cursor rules directory:
+
+- .cursor/rules/conftest.mdc
+- .cursor/rules/dev-dep.mdc
+- .cursor/rules/n-adr.mdc
+- .cursor/rules/n-bun.mdc
+- .cursor/rules/n-changelog.mdc
+- .cursor/rules/n-ci4.mdc
+- .cursor/rules/n-doc-files.mdc
+- .cursor/rules/n-feedback.mdc
+- .cursor/rules/n-ga.mdc
+- .cursor/rules/n-js-run.mdc
+- .cursor/rules/n-js.mdc
+- .cursor/rules/n-npm-module.mdc
+- .cursor/rules/n-python.mdc
+- .cursor/rules/n-rego.mdc
+- .cursor/rules/n-security.mdc
+- .cursor/rules/n-style.mdc
+- .cursor/rules/n-test.mdc
+- .cursor/rules/n-text.mdc
+- .cursor/rules/n-tool-surface.mdc
+- .cursor/rules/n-vue.mdc
+- .cursor/rules/n-worktree.mdc
+- .cursor/rules/scripts.mdc
+
+## Skills
+
+- `.cursor/skills/mdc-check/SKILL.md` — Проаналізувати правило в npm/mdc: максимум перевірюваної логіки й деталей — у check-{id}.mjs з зрозумілими коментарями/JSDoc; у .mdc залишати людинозрозумілий зміст без дублювання алгоритму перевірки
+- `.cursor/skills/n-adr-normalize/SKILL.md` — Ручний запуск ADR-нормалізації — обхід порогу й min-interval, прогон одного батчу чернеток через LLM, перегляд результату через git diff
+- `.cursor/skills/n-doc-files/SKILL.md` — Обовʼязковий крок задачі (як lint): для кожного зміненого/нового кодового файлу (js/mjs/ts/vue/py) JS-оркестрована генерація лаконічної поведінкової української md-документації у теку docs/ поряд із кодом, зі звіркою застарілості за CRC у frontmatter
+- `.cursor/skills/n-lint/SKILL.md` — Запустити дельта-лінт (npx @7n/rules lint) по змінених файлах vs origin, виправити порушення й підтвердити чистий вихід
+- `.cursor/skills/n-llm-patch/SKILL.md` — Підготовка самодостатнього текстового промпта для іншого Claude/Cursor-агента — read-only аналіз CWD без жодних змін у поточному репо
+- `.cursor/skills/n-publish-telegram/SKILL.md` — Підготовка матеріалу з поточного контексту для публікації в Telegram-каналі команди
+- `.cursor/skills/n-taze/SKILL.md` — Оновлення версій модулів проекту з аналізом major-змін і автоматичним рефакторингом несумісного коду
+
+## Commands
+
+Generated from the root `package.json` on each `npx @7n/rules` sync. Prefer `bun run <script>` for project scripts.
+
+- **Залежності**: `bun i`
+- **test**: `bun run test`
+- **start**: `bun run start`
+- **Оновити правила та AGENTS.md** (після змін у правилах/шаблоні CLI): `npx @7n/rules`
+- **Перевірки правил (programmatic)**: `npx @7n/rules fix`
+- **knip (невикористані залежності та експорти)**: `bunx knip`
+
+## Instructions for all agents
+
+Before making changes, read the relevant rule files for the area you are working on.
+
+## Інваріант після змін
+
+`n-changelog.mdc` (alwaysApply) релевантне після **будь-якої** зміни файлів, не лише для релізу. Перед фінальною відповіддю виконай `npx @7n/rules fix changelog` (exit `0`) і познач результат рядком `Changelog: …` у відповіді.
+
+## Priority
+
+If rules conflict:
+
+1. AGENTS.md
+2. task-specific rule file
+3. core rule file
+
+## Language
+
+Respond in Ukrainian.
+Keep technical terms in English.
+
+## Behavior
+
+Do not ignore referenced rule files.
+Explicitly follow repository conventions before proposing or applying changes.
+
+</project_instructions>
+</project_context>
+
+## Поведінка
+
+Поведінка:
+
+1. Перевіряє наявність каталогу `npm/skills` у корені репозиторію. Якщо відсутній, операція завершується успіхом.
+2. Ітерується по всім підкаталогах у `npm/skills`. Для кожного каталогу виконується перевірка відповідності метаданих скіла.
+3. Для кожного скіла перевіряється, чи відсутній файл `auto.md`. Якщо знайдено, фіксується порушення, оскільки метадані мають знаходитися у `main.json`.
+4. Зчитується вміст `main.json` скіла. Якщо файл відсутній або недійсний, фіксується порушення.
+5. Виконується перевірка полів у `main.json` скіла:
+   - Перевіряється тип поля `worktree` — має бути булевим значенням.
+   - Якщо поле `auto` визначене, аналізується його значення на відповідність очікуваним форматам.
+   - Перевіряється тип поля `requireRoot` — має бути булевим значенням.
+   - Перевіряється узгодженість: якщо `worktree` дорівнює `true`, поле `requireRoot` не може бути `false`.
+   - Якщо поле `tier` визначене, воно має відповідати одному з визначених рівнів.
+6. Якщо всі перевірки для скіла успішно пройдені, фіксується успішний статус для цього скіла.
+7. Завершення виконання `main` та повернення коду виходу, що відображає кількість виявлених порушень.
+
+## Публічний API
+
+main — перевіряє, що всі файли `npm/skills/<id>/meta.json` відповідають встановленим вимогам.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

package/rules/npm-module/skill_meta/main.mjs

@@ -0,0 +1,91 @@
+/** @see ./docs/skill_meta.md */
+import { existsSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { createViolationReporter } from '../../../scripts/lib/lint-surface/violation-reporter.mjs'
+import { SKILL_TIERS, parseSkillAutoSpec, readSkillMetaRaw } from '../../../scripts/lib/skill-meta.mjs'
+
+/**
+ * Перевіряє поля сирого meta.json одного скіла (без auto.md / відсутності файлу).
+ * @param {string} id ідентифікатор скіла
+ * @param {Record<string, unknown>} raw сирий meta.json
+ * @param {ReturnType<typeof createViolationReporter>} reporter репортер
+ * @returns {boolean} true, якщо всі поля валідні
+ */
+function checkSkillFields(id, raw, reporter) {
+  let ok = true
+  if (typeof raw.worktree !== 'boolean') {
+    reporter.fail(`skills/${id}: main.json.worktree має бути boolean`)
+    ok = false
+  }
+  if (raw.auto !== undefined && parseSkillAutoSpec(raw.auto) === null) {
+    reporter.fail(`skills/${id}: main.json.auto нерозпізнане — очікується "завжди" або непорожній масив правил`)
+    ok = false
+  }
+  if (raw.requireRoot !== undefined && typeof raw.requireRoot !== 'boolean') {
+    reporter.fail(`skills/${id}: main.json.requireRoot має бути boolean`)
+    ok = false
+  }
+  if (raw.worktree === true && raw.requireRoot === false) {
+    reporter.fail(
+      `skills/${id}: requireRoot:false суперечить worktree:true (worktree вже вимагає кореня — прибери поле)`
+    )
+    ok = false
+  }
+  if (raw.tier !== undefined && !(typeof raw.tier === 'string' && SKILL_TIERS.includes(raw.tier))) {
+    const tierList = SKILL_TIERS.map(t => `"${t}"`).join(' | ')
+    reporter.fail(`skills/${id}: main.json.tier має бути ${tierList}`)
+    ok = false
+  }
+  return ok
+}
+
+/**
+ * Валідує meta.json одного скіла.
+ * @param {string} id ідентифікатор скіла
+ * @param {string} skillDir каталог скіла
+ * @param {ReturnType<typeof createViolationReporter>} reporter репортер
+ * @returns {void}
+ */
+function checkSkill(id, skillDir, reporter) {
+  let skillOk = true
+
+  if (existsSync(join(skillDir, 'auto.md'))) {
+    reporter.fail(`skills/${id}: залишковий auto.md — видали (метадані тепер у main.json)`)
+    skillOk = false
+  }
+
+  const raw = readSkillMetaRaw(skillDir)
+  if (!raw) {
+    reporter.fail(`skills/${id}: відсутній або невалідний main.json (очікується {"auto"?, "worktree": bool})`)
+    return
+  }
+
+  if (!checkSkillFields(id, raw, reporter)) skillOk = false
+
+  if (skillOk) {
+    reporter.pass(`skills/${id}: main.json валідний`)
+  }
+}
+
+/**
+ * Валідує всі `npm/skills/<id>/meta.json`.
+ * @param {import('../../../scripts/lib/lint-surface/types.mjs').LintContext} ctx контекст лінту.
+ * @returns {Promise<import('../../../scripts/lib/lint-surface/types.mjs').LintResult>} результат перевірки з порушеннями.
+ */
+export function lint(ctx) {
+  const cwd = ctx.cwd
+  const reporter = createViolationReporter(ctx)
+  const skillsDir = join(cwd, 'npm', 'skills')
+  if (!existsSync(skillsDir)) {
+    reporter.pass('npm/skills/ відсутній — немає скілів для валідації')
+    return Promise.resolve(reporter.result())
+  }
+
+  for (const entry of readdirSync(skillsDir, { withFileTypes: true })) {
+    if (!entry.isDirectory() || entry.name.startsWith('.')) continue
+    checkSkill(entry.name, join(skillsDir, entry.name), reporter)
+  }
+
+  return Promise.resolve(reporter.result())
+}

package/rules/npm-module/skill_meta/skill_meta.mdc

@@ -0,0 +1,11 @@
+## Валідація `main.json` скілів
+
+Кожен скіл у `npm/skills/<id>/` повинен мати коректний `main.json` (метадані скіла).
+
+Перевірки (`skill_meta.mjs`):
+
+- **`auto.md` є пережитком** — якщо такий файл залишився, `check` вимагає його видалити (метадані тепер у `main.json`).
+- **`main.json` має бути валідним JSON** із коректними полями:
+  - **`worktree`** (обовʼязкове): `boolean`. Якщо `true` — скіл запускається виключно в окремому git-worktree.
+  - **`auto`** (опційне): `"завжди"` або непорожній масив ідентифікаторів правил-тригерів.
+  - **`requireRoot`** (опційне): `boolean`. Значення `false` несумісне з `worktree: true` — таку комбінацію `check` відхиляє.

package/rules/php/cs_fixer/concern.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "https://unpkg.com/@7n/rules/schemas/concern.json",
+  "lint": {
+    "scope": "per-file",
+    "glob": ["**/*.php"]
+  }
+}

package/rules/php/cs_fixer/docs/main.md

@@ -0,0 +1,34 @@
+---
+type: JS Module
+title: main.mjs
+resource: npm/rules/php/cs_fixer/main.mjs
+docgen:
+  crc: d2eae379
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  tier: local-min
+  score: 100
+  issues: judge:inaccurate:0.98
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Використовує `php-cs-fixer` для валідації стилю PHP-коду. Визначає файли для перевірки на основі наданого списку або для всіх файлів у робочому каталозі. Процес є read-only: він не вносить жодних змін до файлової системи чи бази даних. Для коректної роботи опирається на конфігурації, визначені у `composer.json`. Перевірка виконується за допомогою `php-cs-fixer fix --dry-run --diff`, вимагаючи наявності відповідних конфігурацій та виконуваного файлу `php-cs-fixer` у `vendor/bin`.
+
+## Поведінка
+
+Поведінка
+1. Перевіряє наявності `composer.json` у корені робочого каталогу. Якщо відсутній, перевірка пропускається.
+2. Визначає цілі для перевірки: або всі файли, що закінчуються на `.php`, якщо не вказані конкретні файли, або наданий список файлів.
+3. Шукає виконуваний файл `php-cs-fixer` у `vendor/bin` кореневого каталогу. Якщо не знайдено, перевірка пропускається.
+4. Запускає `php-cs-fixer` у режимі сухого запуску з відмінностями для всіх визначених цілей.
+5. Якщо команда завершується з кодом, відмінним від нуля, фіксується порушення, що включає вивід команди.
+6. В іншому випадку, результати перевірки повертаються як успішні.
+
+## Публічний API
+
+* lint — виявляє проблеми форматування коду за стандартами php/cs_fixer (read-only).
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

package/rules/php/cs_fixer/main.mjs

@@ -0,0 +1,52 @@
+/**
+ * lint-поверхня php/cs_fixer: read-only detector (`php-cs-fixer fix --dry-run --diff`, з
+ * `vendor/bin`). Per-file: приймає `ctx.files`, інакше `.` (весь проєкт). Виділено з колишнього
+ * bundled `php/check` (spec docs/specs/2026-07-02-text-check-per-file-split-design.md "Рішення
+ * python/php/rego") — php-cs-fixer приймає список конкретних файлів аргументом.
+ */
+import { spawnSync } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+
+import { createViolationReporter } from '../../../scripts/lib/lint-surface/violation-reporter.mjs'
+
+/** Розширення `.php` — фільтр delta-списку файлів у `lint(ctx)`. */
+const PHP_EXT_RE = /\.php$/u
+
+/**
+ * @param {string} root корінь
+ * @returns {string | null} абсолютний шлях до `vendor/bin/php-cs-fixer` або null, якщо відсутній
+ */
+function vendorBin(root) {
+  const p = resolve(root, 'vendor', 'bin', 'php-cs-fixer')
+  return existsSync(p) ? p : null
+}
+
+/**
+ * Detector php/cs_fixer (read-only).
+ * @param {import('../../../scripts/lib/lint-surface/types.mjs').LintContext} ctx контекст лінту.
+ * @returns {import('../../../scripts/lib/lint-surface/types.mjs').LintResult} результат із порушеннями
+ */
+export function lint(ctx) {
+  const reporter = createViolationReporter(ctx)
+  const { fail } = reporter
+  const root = ctx.cwd
+
+  if (!existsSync(join(root, 'composer.json'))) return reporter.result()
+
+  const targets = ctx.files === undefined ? ['.'] : ctx.files.filter(f => PHP_EXT_RE.test(f))
+  if (targets.length === 0) return reporter.result()
+
+  const abs = vendorBin(root)
+  if (!abs) return reporter.result() // php-cs-fixer відсутній у vendor/bin → пропущено
+
+  const r = spawnSync(abs, ['fix', '--dry-run', '--diff', ...targets], { cwd: root, encoding: 'utf8', shell: false })
+  if (r.status !== 0) {
+    const code = typeof r.status === 'number' ? r.status : 1
+    const out = `${r.stdout ?? ''}${r.stderr ?? ''}`.trim().slice(0, 2000)
+    const outSuffix = out ? `\n${out}` : ''
+    fail(`lint-php: PHP-CS-Fixer (dry-run) — помилка (код ${code}, php.mdc)${outSuffix}`, 'php-cs-fixer-violation')
+  }
+
+  return reporter.result()
+}

package/rules/php/docs/index.md

@@ -0,0 +1,11 @@
+---
+type: Directory Index
+title: npm/rules/php
+resource: npm/rules/php/
+---
+
+# npm/rules/php
+
+| Файл                | Тип       |
+| ------------------- | --------- |
+| [main.mjs](main.md) | JS Module |

package/rules/php/lint_php_yml/concern.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://unpkg.com/@7n/rules/schemas/concern.json",
+  "fixability": "config",
+  "policy": {
+    "files": {
+      "single": ".github/workflows/lint-php.yml"
+    }
+  }
+}

package/rules/php/lint_php_yml/lint_php_yml.mdc

@@ -0,0 +1,23 @@
+## Структура `.github/workflows/lint-php.yml`
+
+Rego-пакет: `php.lint_php_yml`
+
+Цільовий файл: `.github/workflows/lint-php.yml` (парситься як YAML).
+
+Перевіряє, що у workflow присутні всі канонічні `run:`-кроки з template-сніпету — крок `n-rules lint php --no-fix` має бути в одному зі steps jobs.
+
+Канонічний template-сніпет: [lint-php.yml.snippet.yml](./template/lint-php.yml.snippet.yml)
+
+**✓ Правильно** — job `php` містить крок:
+
+```yaml
+- name: Lint PHP
+  run: n-rules lint php --no-fix
+```
+
+**✗ Неправильно** — крок відсутній або містить інший run-рядок:
+
+```yaml
+- name: Lint PHP
+  run: echo something
+```

package/rules/php/lint_php_yml/lint_php_yml.rego

@@ -0,0 +1,34 @@
+# Перевірка `lint-php.yml` (php.mdc).
+#
+# Канон надходить через --data: { "template": { "snippet": ... } }
+# Структура --data сформована з template/lint-php.yml.snippet.yml.
+# Маркер `run:` збирається з template's php-job steps.
+# Універсальні workflow-перевірки — у `ga.workflow_common`.
+package php.lint_php_yml
+
+import rego.v1
+
+# Очікуваний `run:` маркер — конкатенація всіх run-блоків з template.
+expected_run_blob := concat("\n", [r |
+	some step in data.template.snippet.jobs.php.steps
+	r := object.get(step, "run", "")
+	r != ""
+])
+
+all_run_text := concat("\n", [run_text |
+	some job in object.get(input, "jobs", {})
+	some step in object.get(job, "steps", [])
+	run_text := step_run_to_text(step)
+])
+
+deny contains msg if {
+	expected_run_blob != ""
+	not contains(all_run_text, expected_run_blob)
+	msg := sprintf("lint-php.yml: жоден крок run не містить %q (php.mdc)", [expected_run_blob])
+}
+
+step_run_to_text(step) := step.run if is_string(step.run)
+
+else := concat("\n", [s | some s in step.run]) if is_array(step.run)
+
+else := ""