sdd-contradiction

name	sdd:contradiction
workflow_step	5
description	Проверяет текстовые артефакты (OpenSpec change-директории, отдельные файлы, произвольные каталоги) на внутренние противоречия, избыточность и broken cross-doc pointers. Активируй, когда пользователь просит проверить consistency директории/файла, после серии правок в change-артефактах, перед коммитом, после каждого перехода между соседними узлами графа proposal ↔ design ↔ spec ↔ tasks, или явно через `/sdd:contradiction PATH=<file|dir>`.

Contradiction checker (sdd:contradiction)

Determine Change (если $ARGUMENTS пуст)

Если $ARGUMENTS непуст — используй как PATH и переходи к следующему разделу.

Если $ARGUMENTS пуст:

Режим A — контекст очевиден. Если в текущем разговоре уже обсуждался конкретный чендж (например, только что выполнялся другой sdd-скилл или пользователь явно упоминал имя ченджа) — НЕ вызывай никаких инструментов. Через AskUserQuestion покажи список:

1. Продолжить с <name> (наиболее вероятный)
2. Выбрать другой чендж

Если пользователь выбрал вариант 2 — переходи к режиму B.

Режим B — контекст неоднозначен. Если чендж из разговора определить нельзя — выполни через Bash tool:

git branch --show-current
git status --short
ls openspec/changes/

Сканируй openspec/changes/, ранжируй кандидатов по трём сигналам (убыв. приоритет):

1. Имя ветки совпадает с именем директории ченджа.
2. В openspec/changes/<name>/ есть изменённые/untracked файлы по git status.
3. Директория существует и не архивирована (нет .sdd-state.yaml со stage: archived).

Через AskUserQuestion покажи нумерованный список до 7 кандидатов (отсортированных по убыванию релевантности, с пометкой «наиболее вероятный» у первого). Остальные скрыты с пометкой «ещё N».

Дождись выбора. Используй выбранный чендж как PATH = openspec/changes/<name>.

SCOPE CONSTRAINT

Все правки выполняются исключительно внутри openspec/changes/<name>/. MUST NOT изменять файлы вне этой директории, включая skills/, .claude/, openspec/specs/.

Identity check (если PATH — change-директория)

Если PATH является change-директорией (содержит proposal.md и .sdd.yaml), перед основным анализом:

1. Получи текущий email через Bash tool:

   python3 "${CLAUDE_SKILL_DIR}/../scripts/identity.py"
   

   Если скрипт вернул exit ≠ 0 — выведи stderr и остановись.

2. Прочитай owner: из .sdd.yaml через:

   python3 "${CLAUDE_SKILL_DIR}/../scripts/_sdd_yaml.py" read "<change-dir>"
   

3. Если owner пуст или совпадает с email → продолжай молча.

4. Если owner != email → выведи warning: ⚠ Это change owner=<owner>, ты <email>. Перезаписать на тебя? Через AskUserQuestion. При согласии:

   python3 "${CLAUDE_SKILL_DIR}/../scripts/_sdd_yaml.py" set-owner "<change-dir>" "<email>"
   

   При отказе — остановись с сообщением «работа над чужим change'ем отклонена».

Если PATH — не change-директория — пропусти этот шаг молча.

Cross-spec preamble (если PATH — change-директория)

Если PATH является change-директорией (содержит proposal.md), перед основным анализом:

1. Найди contradiction.py в scripts/ рядом со скиллом: ${CLAUDE_SKILL_DIR}/scripts/contradiction.py
2. Вызови через Bash tool:

   python "${CLAUDE_SKILL_DIR}/scripts/contradiction.py" "<change-dir-absolute-path>" 2>&1
   

3. Прочитай stdout. Он содержит:
   • Секции --- Capability: <name> (<path>) [<label>] --- для каждой загруженной спеки:
     • [PRIMARY/merges-into] — capability из .sdd.yaml.merges-into, найденная в index
     • [PRIMARY/creates] — capability из .sdd.yaml.creates, уже в index (live)
     • [PRIMARY/creates DRAFT] — capability из .sdd.yaml.creates, не в index (draft)
     • без метки — background capability (весь остальной index)
   • Секция --- ADJACENT Capabilities --- — capabilities из index, тематически смежные с change но незадекларированные; только listing, не включать в scope анализа
   • Summary: total_discovered, total_loaded, draft_specs_loaded, primary_capabilities, merges_into_missing, adjacent_capabilities, skipped
   • Warnings о missing files и missing merges-into capabilities
4. Включи загруженные PRIMARY и background спеки в scope анализа. PRIMARY-capabilities анализируй в первую очередь. ADJACENT — только информационный раздел, в анализ не включай.
5. В отчёте добавь строку после заголовка: Analyzed: <total_loaded> capabilities from index (или index.yaml not found если скрипт сообщил об этом).
6. Capabilities, пропущенные из-за missing files, перечисли в отдельной секции отчёта: --- Skipped capabilities ---

Если PATH — не change-директория (файл, произвольная директория) — пропусти этот шаг молча.

---

Никакого внешнего кода, Python-модуля, curated-словаря или fixture-тестов нет. Всё делаешь ты, модель, в одном прогоне.

Input handling

Пользователь передаёт PATH — один или несколько пробел-разделённых путей (файлов или директорий). Каждый путь раскрывается в список файлов; наборы объединяются в единый scope проверки.

Если путь не существует — выведи ERROR: path not found: <PATH> для каждого несуществующего пути и продолжи анализ по оставшимся (не останавливайся полностью). Если ни одного валидного пути нет — остановись.

После раскрытия всех путей определи режим по составу набора:

1. Файл (один файл, нет proposal.md) → читай только его, применяй in-file детекторы (numeric, reference, deontic, semantic, redundancy).
2. Change-директория (набор содержит proposal.md) → change-directory-режим: читай все четыре артефакта (proposal.md, design.md, tasks.md, specs/**/spec.md), ограничивая scope переданными файлами. Если в change-директории присутствует domain.md — включай его в scope наравне с opsx-артефактами; все тринадцать детекторов применяются к нему без исключений. Применяй все тринадцать детекторов.
3. Произвольная директория (без proposal.md в корне) → прочитай все текстовые файлы рекурсивно: *.md, *.sh, *.py, *.yaml, *.yml, *.json, *.txt, *.toml, *.ini, Makefile, Dockerfile.
4. Корень проекта (. или openspec/) → whole-project scan с поиском cross-change coupling; читай только файлы внутри PATH.

Детекторы, требующие конкретных артефактов (coverage, placement, spec-count, semantic-completeness, derivability, what-changes-coverage, decisions-coverage, completeness), запускаются только если соответствующие артефакты присутствуют в наборе; иначе — пропускаются с пометкой [detector: N/A — required artifacts not in scope] в Summary. Детектор completeness дополнительно вне change-directory-режима пропускается с пометкой [completeness: N/A — not a change-directory].

Граница анализа. Во всех режимах PATH — жёсткая граница. Ссылки на файлы вне PATH проверяй только на существование (reference-детектор); referenced файлы не читай и не включай в анализ.

Phase 1 — EXPAND (conditional)

Выполняй только если PATH — ранняя change-директория: proposal.md почти пустой (< ~500 символов в Why+What), иллюстративный-list классов/случаев отсутствует или содержит ≤ 3 пункта. В этом случае выведи в отчёт секцию:

--- EXPAND note ---
Scope may be under-specified. Consider listing illustrative classes/edge cases in proposal.md
before fixing v1 scope in design. This prevents narrow-scope commitment that misses dimensions.

Если change зрелый — фаза проходит молча, ничего в отчёт не добавляется.

Phase 2 — COMPRESS

До запуска детекторов пройдись по блокам (абзац, table-row, list-item длиной ≥ 120 символов или ≥ 15 слов, Requirement-секция) и выяви дубликаты в 2+ файлах. Для каждой группы дубликатов сформируй кандидат на SSOT-консолидацию по эвристике приоритета:

specs/**/spec.md > design.md > proposal.md > tasks.md

Эвристика рекомендательная. Override по делу: если дубликат — Why-статистика или motivational narrative, SSOT может остаться в proposal.md. Пометь предложение как heuristic.

Для каждой группы подготовь конкретный pointer-rewrite:

• какой текст оставить в SSOT-файле дословно;
• какой короткий pointer подставить в остальные места: «см. <ssot-file> → ».

Эти предложения будут представлены как [warning] redundancy в фазе VALIDATE, а сами предложенные новые pointer'ы пройдут через детектор reference там же — чтобы каскадные broken-pointers были видны сразу.

Исключения из redundancy-детекции:

• fenced-code-blocks с shebang-строкой (#!/bin/bash, #!/usr/bin/env python);
• YAML frontmatter (---\n...\n---);
• Markdown-разделители (---, ***, ___);
• чисто-пунктуационные строки;
• короткие cross-ref-подписи («см. D5», «Req X»).

Phase 3 — VALIDATE

Применяй тринадцать детекторов в фиксированном порядке: numeric → reference → deontic → semantic → redundancy → coverage → placement → spec-count → semantic-completeness → derivability → what-changes-coverage → decisions-coverage → completeness. Результаты пусть копятся отдельно по детекторам — формат отчёта ниже требует сгруппированного вывода.

3.1 — numeric (hard, severity=error)

Находи утверждения с числами и устойчивым subject'ом:

• счётчики (количество однотипных сущностей: «N records», «K fields», «M items per group»);
• пороги, лимиты, таймауты, TTL («30 дней», «5 retries», MAX_RETRIES=3);
• номера портов, версии, коэффициенты.

Группируй по subject'у (нормализация контекста: «N items of type A» и «N items of type B» — разные subject'ы даже при одном числе, не смешивай). Если для одного subject'а в разных местах встречаются разные числа — флаг.

Формат issue: <file>:<line>: [error] numeric: '<subject>' = <A> here vs <B> (at <other-file>:<line>).

3.2 — reference (hard, severity=error, 3 подстратегии)

Подстратегии — один класс reference с полем sub_kind:

1. file — упоминания файлов (scripts/*.sh, manifest/*.md, .claude/*, относительные пути). Проверяй существование на диске.
2. make-target — упоминания make <target>. Если в корне проекта есть Makefile, проверяй наличие цели. Если Makefile нет — пропусти с warning в stderr, не флагай.
3. pointer — cross-doc ссылки вида «см. <file> → <section-id|Requirement-name|§N|D>», «<file>.md:<anchor>». Резолви целевой файл и секцию. Проверяй, что секция / Requirement / параграф с таким именем есть в целевом файле.

Exception — plan-artefacts. Если файл явно упоминается в tasks.md текущего change как создаваемый этим change'ем (формулировки «создать», «добавить», «ввести файл X», «новый файл»), НЕ флагай его как missing, даже если физически отсутствует. Эвристика: присутствие пути в tasks.md + глагол-индикатор создания.

Формат issue: <file>:<line>: [error] reference: '<path-or-pointer>' — <reason> [sub_kind=<file|make-target|pointer>].

3.3 — deontic (hard, severity=error)

Для каждой сущности собирай все модальные утверждения:

• positive markers: SHALL, MUST, «обязан», «SHOULD», «MAY», «активно используется», «required», «SHALL вызывать», «SHALL содержать»;
• negative markers: SHALL NOT, MUST NOT, SHOULD NOT, «не вводится», «не регистрируется», «не должен», «запрещено», deprecated, «отклонено», «отказ», «not introduced», ~~Requirement~~ (strikethrough в заголовке Requirement).

Извлекай subject — имя сущности: quoted identifier (`scripts/foo.sh`, "foo"), Requirement-name, имя параметра/эндпоинта/таблицы/политики. Нормализуй: whitespace-collapse, lowercase ASCII, strip кавычек.

Группируй по canonical subject. Флаг, если в группе есть и positive, и negative.

Exceptions:

• Scope-restrictor в одном предложении («SHALL X только если Y», «SHALL NOT X без Y», «SHALL ... кроме Z») — это уточнение scope, не конфликт.
• Scenario-уровень модалок (#### Scenario: → WHEN ... THEN ...) парсится отдельно от Requirement-уровня. У Scenario свой WHEN-scope, модалки внутри не смешивай с Requirement-модалками.
• Разные subject'ы — scripts/foo.sh SHALL ... и scripts/bar.sh SHALL NOT ... — не конфликт.

Формат: <file>:<line>: [error] deontic: '<subject>' <positive-polarity> here vs <negative-polarity> (at <other-file>:<line>).

3.4 — semantic (hard, severity=error)

Сам выцепляй темы из текста (не из внешнего словаря):

• пути файлов и директорий;
• политики (например, «triger — manual-only», «все репы — субмодули»);
• правила (формат записи, schema);
• идентификаторы (имена репозиториев, ветки, commit-ref);
• конфигурационные значения.

Для каждой темы собери все claim'ы из разных мест и сравни по смыслу (не по буквам). Нормализация:

• whitespace / case / trailing / / singular-plural — не флагай;
• форматирование (backticks, quotes) — не флагай;
• разные буквальные значения («manifest/repos.md» vs «manifest/submodules.yaml») — флагай.

Polarity определяй по контексту самой темы (вместе с деонтикой, но в semantic — про factual claim). Если одно место утверждает о теме, а другое отрицает или переопределяет — это semantic расхождение.

В отчёте обязательно перечисли выделенные темы в секции Subjects covered by semantic detector — для прозрачности покрытия, чтобы пользователь видел что ты проверял.

User-provided ignore. Если в том же обращении пользователь говорит «subject X — известный false positive» или «игнорируй <тему>» — повторно выдай отчёт без этого subject'а, не требуя перезапуска.

Формат: <file>:<line>: [error] semantic: '<subject>' = '<claim-A>' here vs '<claim-B>' (at <other-file>:<line>).

3.5 — redundancy (soft, severity=warning)

Используй результаты фазы COMPRESS. Каждая группа дубликатов:

• выведи все локации (N записей для N мест),
• укажи suggested SSOT с пометкой (heuristic, override as needed),
• добавь pointer-rewrite suggestion: «оставить полный текст в <ssot>, в остальных — см. <ssot> → <anchor>»,
• прогони предложенные новые pointer'ы через reference подстратегию pointer. Если какой-то из них после consolidation стал бы broken — добавь warning «after fixing this redundancy, pointer X might break at :».

User override SSOT. Если пользователь в том же обращении укажет другой SSOT («SSOT для этого блока — proposal.md, не design.md») — пересчитай pointer-rewrite относительно указанного SSOT и повторно валидируй новые pointer'ы. Без перезапуска.

Redundancy не растит exit-код. Это только warning.

Формат: <file>:<line>: [warning] redundancy: '<snippet-60-chars>' duplicated in <other-file>:<line> (suggested SSOT: <file>, heuristic).

3.6 — coverage (soft, severity=warning)

Только в режиме change-директории. В остальных режимах пропускай с пометкой [coverage: N/A — required artifacts not in scope] в Summary.

Алгоритм:

1. Прочитай proposal.md — секцию ### New Capabilities. Собери список capabilities.
2. Прочитай все specs/**/spec.md — собери все ### Requirement: блоки.
3. Для каждого Requirement и каждого capability проверь: есть ли в tasks.md хотя бы одна задача, в тексте которой упоминается имя Requirement / capability или ключевые слова его тела (совпадение по смыслу, не по байтам).
4. Непокрытые элементы → [warning] coverage: в Soft warnings.

Severity warning — несопоставленный Requirement не обязательно ошибка (может быть намеренно отложен). Coverage не растит exit-код.

Формат: specs/<path>/spec.md:<line>: [warning] coverage: 'Requirement: <name>' has no corresponding task in tasks.md. Capability: proposal.md:<line>: [warning] coverage: 'Capability: <name>' has no corresponding task in tasks.md.

3.7 — placement (soft, severity=warning)

Только в режиме change-директории. В других режимах пропускай с пометкой [placement: N/A — required artifacts not in scope] в Summary.

Детектор проверяет, что каждый тип информации находится в артефакте, соответствующем его роли в OpenSpec-графе:

• proposal.md — «почему»: бизнес-контекст, мотивация, capabilities-list, impact.
• design.md — «как»: архитектурные решения, rationale, trade-offs, alternatives.
• spec.md — «что»: тестируемые контракты, Requirement-блоки, Scenario-блоки.
• tasks.md — «реализация»: конкретные шаги, чекбоксы, файлы-к-созданию.

Флагируй следующие паттерны с severity warning:

1. Requirement-блок вне spec.md — строка ### Requirement: или #### Requirement: найдена в proposal.md, design.md или tasks.md.
2. Implementation-step внутри spec.md — чекбокс - [ ] / - [x] или нумерованный список в секции с заголовком, содержащим «task», «step», «implement», «шаг», «задача», найден в spec.md.
3. Rationale-блок в spec.md без WHY-заголовка — абзац с маркерами («потому что», «because», «rationale», «trade-off», «we chose», «решили», «альтернатива», «alternative») найден в spec.md и не вложен в явный ### Why, **Why:** или **Why (<qualifier>):** заголовок.

Если блок невозможно однозначно классифицировать — выдавай warning с пометкой ambiguous.

Формат: <file>:<line>: [warning] placement: <description>.

3.8 — spec-count (soft, severity=warning)

Только в режиме change-директории. В других режимах пропускай с пометкой [spec-count: N/A — required artifacts not in scope] в Summary.

Детектор проверяет три условия:

1. Capability без спеки — считать пункты в ### New Capabilities в proposal.md и сравнивать с числом specs/**/spec.md файлов. Если capabilities > spec-файлов — флаг. Если ### New Capabilities отсутствует или пуста — вывести [spec-count: N/A — no structured capabilities list in proposal.md] и пропустить п.1; п.2 и п.3 выполнять всегда.

2. Задача без спеки — для каждой задачи в tasks.md (строка с чекбоксом или нумерованным пунктом): проверить, содержит ли текст задачи имя, путь или ключевые слова хотя бы одного из specs/**/spec.md. Если нет — флаг.

3. Спека-заглушка — specs/**/spec.md содержит 0 ### Requirement: блоков, либо ровно 1 Requirement и 0 #### Scenario: блоков. Спека с 1 Requirement и хотя бы 1 Scenario — содержательна, не флагается.

Severity warning для всех трёх. Spec-count не растит exit-код.

Формат: <file>:<line>: [warning] spec-count: <description>.

3.9 — semantic-completeness (soft, severity=warning)

Только в режиме change-директории. В других режимах пропускай с пометкой [semantic-completeness: N/A — required artifacts not in scope] в Summary.

Детектор проверяет два вида полноты:

Проверка 1 — нераскрытый термин. Собери термины/capability-имена из секций ### New Capabilities и ### Glossary (если есть) в proposal.md. Для каждого термина проверь наличие (или близкого семантического соответствия) в теле хотя бы одного Requirement-блока в specs/**/spec.md. Если нет — флаг.

Проверка 2 — orphan Requirement. Собери все ### Requirement: имена из specs/**/spec.md. Для каждого проверь: упоминается ли его имя (или ключевые слова первых двух предложений тела) хотя бы в одном из: design.md (в Discussion или Decisions-секции), tasks.md (как задача). Если ни в одном — флаг.

Severity warning для обеих проверок. Semantic-completeness не растит exit-код.

Формат:

• proposal.md:<line>: [warning] semantic-completeness: term '<name>' introduced in proposal but not covered in any spec
• specs/<path>/spec.md:<line>: [warning] semantic-completeness: Requirement '<name>' is orphaned — not referenced in design.md or tasks.md

3.10 — derivability (soft, severity=warning)

Только в режиме change-директории. В других режимах пропускай с пометкой [derivability: N/A — required artifacts not in scope] в Summary.

Детектор проверяет три паттерна производного контента — утверждений, которые логически следуют из другого артефакта и явно переформулированы без добавления нового знания.

Паттерн 1 — Rationale-drift. Проверяй: содержит ли specs/**/spec.md WHY-блок (абзац с маркерами «потому что», «because», «since», «так как», «поскольку»), чьё содержание семантически совпадает (≥60% ключевых слов) с WHY-блоком в design.md или proposal.md. Такой блок выводим из design/proposal — spec не должна его переформулировать.

Исключение из Паттерна 1: явный ### Why заголовок или **Why:** блок в spec.md — намеренное документирование WHY в спеке, не флагать.

Паттерн 2 — Constraint-restatement. Проверяй: содержит ли tasks.md причинно-следственный оборот («должна X, так как», «убедиться что X (Requirement: Y)», «потому что спека требует») со ссылкой на Requirement по имени или смыслу. Такое ограничение выводимо из самого Requirement — tasks достаточно checkbox без переформулировки constraint.

Паттерн 3 — Decision-echo. Проверяй: содержит ли proposal.md блок с маркерами принятых решений («мы выбрали», «решено использовать», «принято решение», «we chose», «decided to»), семантически совпадающий (≥60% ключевых слов) с Decisions-секцией design.md. Proposal должен содержать WHY-мотивацию; HOW-решения принадлежат design.md.

Общие исключения (все паттерны):

• Короткие cross-ref подписи («см. D5», «Req X», ≤ 15 слов) — намеренные указатели.
• #### Scenario: блоки — описывают тестируемое поведение, не дублируют rationale.
• fenced-code-blocks — код не является производным от prose.

Для каждого флага детектор SHALL предлагать конкретный pointer-rewrite: что оставить, что заменить ссылкой вида «см. <ssot-file> → ».

Severity warning. Derivability не растит exit-код.

Формат: <file>:<line>: [warning] derivability: <description> (pattern: <rationale-drift|constraint-restatement|decision-echo>).

3.11 — what-changes-coverage (soft, severity=warning)

Только в режиме change-директории. В других режимах пропускай с пометкой [what-changes-coverage: N/A — required artifacts not in scope] в Summary.

Детектор проверяет, что каждый пункт секции ## What Changes в proposal.md адресован хотя бы одним Decision (### D<N>) в design.md.

Алгоритм. Для каждого пункта ## What Changes:

1. Извлечь предметные термины: существительные, технические идентификаторы, имена детекторов/файлов/параметров (не служебные слова).
2. Проверить, встречаются ли ≥2 таких термина в теле любого ### D<N> блока в design.md.
3. Если ни один Decision не покрывает пункт — выдать [warning] what-changes-coverage.

Исключения:

• Пункты без предметных терминов (только глагол + служебное слово, например «Обновить строку Summary», «Добавить счётчик») — пропускать.
• Если design.md не содержит ## Decisions секции → [what-changes-coverage: N/A — no Decisions section in design.md] в Summary; детектор пропускается.

Severity warning. What-changes-coverage не растит exit-код.

Формат: proposal.md:<line>: [warning] what-changes-coverage: What Changes item has no corresponding Decision in design.md.

3.12 — decisions-coverage (soft, severity=warning)

Только в режиме change-директории. В других режимах пропускай с пометкой [decisions-coverage: N/A — required artifacts not in scope] в Summary.

Детектор проверяет, что каждое prescriptive Decision в design.md отражено хотя бы в одном Requirement в specs/**/spec.md.

Алгоритм. Для каждого ### D<N> блока в design.md:

1. Проверить наличие prescriptive маркеров: SHALL, MUST, «должен», «обязан», «требует», «необходимо».
2. Если маркеры есть — извлечь предметные термины из заголовка и первого предложения Decision.
3. Проверить, встречаются ли ≥2 таких термина в имени или теле хотя бы одного ### Requirement: в specs/**/spec.md.
4. Если ни один Requirement не покрывает Decision — выдать [warning] decisions-coverage.

Исключения:

• Decisions в секции ## Risks / Trade-offs — не флагать.
• Decisions без prescriptive language → пропускать.
• Decisions с явной пометкой Non-Goal или «не входит в scope» → пропускать.

Severity warning. Decisions-coverage не растит exit-код.

Формат: design.md:<line>: [warning] decisions-coverage: Decision '<D-name>' has no corresponding Requirement in spec.

3.13 — completeness (hard, severity=error)

Только в режиме change-директории. В режимах file, arbitrary-dir и whole-project детектор пропускается с пометкой [completeness: N/A — not a change-directory] в Summary.

Детектор проверяет наличие обязательных структурных файлов change'а. Запуск sdd:contradiction означает, что change готовится к apply, поэтому всё должно быть на месте — проверка не зависит от стадии из .sdd-state.yaml.

Алгоритм. Для каждого пути из списка обязательных артефактов проверь существование на диске:

• proposal.md
• .sdd.yaml
• .sdd-state.yaml
• tasks.md
• specs/ с минимум одним spec.md

Если файл отсутствует — выдай [error] completeness. Если директория specs/ отсутствует или не содержит ни одного spec.md — это тоже [error] completeness.

Severity error (hard issue): отсутствие структурного файла блокирует apply. Детектор растит exit-код наравне с остальными hard-детекторами.

Формат:

• <missing-file>: [error] completeness: required file missing — '<missing-file>'
• specs/: [error] completeness: required specs directory missing or empty

Phase 4 — CONVERGE

Выполняй после Phase 3 (VALIDATE) и до Phase 5 (CROSS-CUT).

Алгоритм — максимум 3 итерации

Шаг 1 — SSOT-иерархия: каноническое значение

Для каждого hard issue (numeric или semantic) определи SSOT-источник по приоритету:

specs/**/spec.md > design.md > proposal.md > tasks.md

Значение из файла с наивысшим приоритетом является каноническим. Все остальные вхождения subject'а приводятся к нему (BFS по exhaustive touch-list).

• Если два файла одного приоритетного уровня содержат конфликтующие значения → немедленно перейти к шагу 4 (decision gate).
• Если однозначный SSOT найден → продолжить шаг 2.

Шаг 2 — Exhaustive touch-list

Для каждого subject'а найди все вхождения по scope — не только конфликтующую пару. Расширяй секцию Cascade predictions формулировкой:

To fully resolve '<subject>': <file1>:<line> (value: X), <file2>:<line> (value: Y), ...

Шаг 3 — Симуляция фиксов; прогон numeric + semantic

Мысленно применяй канонические значения ко всем вхождениям touch-list. Прогони numeric и semantic детекторы на гипотетическом состоянии:

• Нет новых issues → конвергенция достигнута; в pass log: Re-run numeric+semantic... found: none → stable; перейти к финальному отчёту.
• Есть новые issues → это second-order issues; записать; повторить шаг 1 (следующая итерация).
• 3 итерации исчерпаны → вывести convergence not reached after 3 passes — re-run after applying fixes; завершить Phase 4 с последним известным состоянием.

Шаг 4 — Decision gate

Срабатывает только при конфликте на одном SSOT-уровне. Скилл SHALL:

1. Немедленно прервать итерацию.
2. Вывести --- Decision gate --- с описанием развилки и вариантами + их каскадными следствиями.
3. Завершить Phase 4 — дальнейшие итерации не выполняются.

SHALL NOT угадывать направление развилки молча.

Pass log — формат

Каждая итерация Phase 4 фиксируется блоком в отчёте (размещается после Cascade predictions, до Post-fix second-order issues):

--- CONVERGE pass <N> ---
<file>:<line> '<subject>' <old_value>→<new_value> (src: <ssot-file>:<line>)
...
Re-run numeric+semantic... found: <N issues | none → stable>

---

Phase 5 — CROSS-CUT (conditional, whole-project scan)

Выполняй только если PATH = корень проекта / openspec/ / openspec/changes/, т.е. видно больше одного change'а.

Для каждого subject'а (выделенного в semantic-детекторе) и для каждого pointer-а (из reference), затрагивающих больше одного change'а:

• сравни claim'ы между change'ами;
• флагай cross-change расхождения с той же severity, как в in-change детекторах;
• явно указывай, между какими changes найдено расхождение.

Если контекст переполнен и сканировать все changes за один проход нельзя — явно сообщи:

--- Context overflow ---
Context budget exceeded. Prioritized files: <A/B/C...>.
Re-run with PATH=<subdir> for coverage of: <remaining change-names>.

Multi-pass convergence

Ты видишь все файлы сразу. Не запускай себя рекурсивно через внешний tool call — итерации выполняются внутри одного прогона в Phase 4. Вместо этого:

1. просканируй контекст;
2. выдели подозрительные узлы (файлы с частыми cross-refs, высокой связностью, пересечениями subjects) — объясни выбор в отчёте;
3. прогоняй детекторы (Phase 3);
4. для каждого hard issue выполняй Phase 4 (CONVERGE) — до 3 внутренних итераций, пока не стабилизируется или не сработает decision gate;
5. для каждого предложенного фикса предскажи каскад: «если пофиксить X, возникнет потенциальный broken-pointer Y», «если консолидировать в SSOT Z, три pointer'а в W нужно обновить».

Выдавай consolidated отчёт — один раз, с приоритизацией фиксов. Пользователь может внести правки и вызвать тебя снова для верификации.

Residual risk

После завершения анализа оцени residual_risk — качественную оценку вероятности необнаруженных issues. Выводи последней строкой Summary. Значение: low, medium или high, за которым следует однострочное обоснование. Процентные значения не используются — они создают ложную точность.

• low: все файлы в PATH прочитаны полностью, context не переполнен, ambiguous-случаев не осталось, cross-ref граф линейный (≤ 1 узла с высокой связностью).
• medium: остались нерешённые ambiguous-случаи, или ≥ 2 узла с высокой связностью, или часть файлов пропущена из-за приоритизации без явного overflow.
• high: был явный context overflow (файлы не читались), или PATH содержит > 10 файлов и охват заведомо неполный.

Report format

Выводи отчёт строго в этой структуре:

=== Contradiction report: <PATH> ===

--- Suspicious nodes (heuristic) ---
<file-1>: <reason-picked>
<file-2>: <reason-picked>
...

--- Hard issues (error) ---
<file>:<line>: [error] <class>: '<subject>' ... (at <other-file>:<line>)
...

--- Cascade predictions (if any) ---
- Fixing <issue-A> may break <pointer-B> at <file>:<line>.
- To fully resolve '<subject>': <file1>:<line> (value: X), <file2>:<line> (value: Y), ...
...

--- CONVERGE pass 1 ---                    ← опускается если Phase 4 не нашла hard issues
<file>:<line> '<subject>' <old>→<new> (src: <ssot-file>:<line>)
...
Re-run numeric+semantic... found: <N issues | none → stable>

--- CONVERGE pass 2 ---                    ← если понадобилась следующая итерация
...

--- Post-fix second-order issues ---       ← опускается при decision gate или отсутствии Phase-4 фиксов
<file>:<line>: [2nd-order] <class>: '<subject>' ...
...
(none)                                     ← если Phase 4 завершилась стабильно и новых issues нет

--- Soft warnings ---
<file>:<line>: [warning] redundancy: '<snippet>' duplicated in <other-file>:<line> (suggested SSOT: <file>, heuristic)
  → pointer-rewrite: replace with "см. <ssot-file> → <anchor>"
  → post-consolidation pointer check: <ok | broken at X>
...

--- Subjects covered by semantic detector ---
- <subject-1>
- <subject-2>
...

--- Summary ---
- hard: <N> (numeric=<a>, reference=<b>, deontic=<c>, semantic=<d>, completeness=<e>)
- warnings: <M> (redundancy=<r>, coverage=<cv>, placement=<pl>, spec-count=<sc>, semantic-completeness=<smc>, derivability=<dv>, what-changes-coverage=<wc>, decisions-coverage=<dc>)
- convergence: <stable | decision-gate | max-iterations-reached | n/a — no hard issues>
- exit semantics: <clean | has-hard-issues>
- residual_risk: <low | medium | high> — <reason>

Правила:

• секции hard и soft — раздельны, hard всегда первой;
• sorting внутри секции: (severity desc, file asc, line asc);
• severity-prefix обязателен ([error] / [warning]);
• для redundancy обязательно показывать suggested SSOT и pointer-rewrite;
• N/A-детекторы фиксируются в Summary как [<detector>: N/A — required artifacts not in scope];
• секции --- CONVERGE pass N --- и --- Post-fix second-order issues --- опускаются полностью если Phase 4 не запускалась (нет hard issues в Phase 3);
• --- Post-fix second-order issues --- также опускается при decision gate (нечего показывать — итерация прервана); при стабильной конвергенции без second-order issues выводить (none);
• convergence: n/a — no hard issues когда Phase 4 не запускалась; иначе одно из stable | decision-gate | max-iterations-reached;
• residual_risk — последняя строка Summary; качественная оценка, не число.

Fallback — когда что-то пошло не так

• PATH не существует → ERROR: path not found: <PATH>, остановись (при одном пути) или продолжи по остальным (при нескольких).
• Файлы не удалось прочитать → сообщи явно, не угадывай содержимое.
• Контекст переполнен → см. «Context overflow» в фазе CROSS-CUT.
• Двусмысленная формулировка (не можешь решить, один subject или разные) → выведи в отчёте с пометкой ambiguous, не делай выбор молча.

Что скилл НЕ делает

• НЕ предлагает автоматический fix; только диагностика и предложения SSOT / pointer-rewrite.
• НЕ исполняет Python / bash / другой внешний код.
• НЕ изменяет файлы по своей инициативе.
• НЕ регистрирует автоматический PostToolUse-триггер — только ручной вызов.
• НЕ отождествляет redundancy с derivability: redundancy — буквальный или почти-буквальный дубликат блока текста в 2+ артефактах; derivability — явная переформулировка утверждения, логически следующего из другого артефакта, без добавления нового знания.

When to run (рекомендации пользователю)

Если пользователь спрашивает «когда вызывать» — напомни:

• перед коммитом change-артефактов;
• после каждого перехода в графе proposal ↔ design ↔ spec ↔ tasks;
• после SSOT-консолидации (убрали повтор → проверить, не осталось ли упоминаний в других местах);
• при подозрении на расхождение (формулировка разъехалась между документами).

---

Log write (финальный шаг — перед User-facing wrapper)

Если PATH — change-директория, запиши полный технический отчёт в лог-файл через Bash tool:

TS=$(date +%Y%m%dT%H%M%S)
mkdir -p ".logs/<name>"
cat > ".logs/<name>/contradiction-${TS}.md" << 'LOGEOF'
---
change: <name>
skill: sdd:contradiction
timestamp: <TS>
exit_semantics: <clean|has-hard-issues>
hard_issues: <hard_counts.total>
warnings: <warning_counts.total>
---

## Detector Report

<verbatim полный отчёт Phase 3/4: все секции --- Hard issues ---, --- Cascade predictions ---,
--- CONVERGE pass N ---, --- Post-fix second-order issues ---, --- Soft warnings ---,
--- Subjects covered by semantic detector ---, --- Summary --->

## Errors

<заполнить если ошибка произошла до завершения анализа; иначе — _нет_>
<формат: - **step:** <шаг>  **what:** <ошибка>  **why:** <ожидалось/получено>  **reproduce:** <команда>>
LOGEOF
echo "log: .logs/<name>/contradiction-${TS}.md"

Сохрани TS для ссылки в диалоговом выводе. Если PATH — не change-директория — пропусти молча.

При ошибке до завершения анализа (identity exit ≠ 0, script fail, PATH not found): запиши лог с заполненной ## Errors секцией и полем exit_semantics: has-hard-issues, затем остановись. Поле reproduce — точная Bash-команда или входные аргументы, которые привели к ошибке.

---

User-facing wrapper (финальный шаг — после Log write)

Вызови через Bash tool:

echo "<детализированный отчёт выше>" | python3 "${CLAUDE_SKILL_DIR}/../scripts/contradiction_summary.py" -

Скрипт возвращает JSON {hard_counts, warning_counts, residual_risk, convergence, exit_semantics}.

Рендери диалоговый отчёт в строгом порядке блоков:

## Описание
<2–5 предложений прозы: что произошло, какие проблемы найдены — на простом языке, без жаргона детекторов>

## Найденные противоречия
<если hard_counts.total == 0: тело `нет`, заголовок остаётся>
<если hard_counts.total > 0: компактный список — hard: N, warnings: M>

## Что делать
<для каждого warning и hard issue — одна строка `- [ ] <действие>`:
  — описывать ЧТО изменить в тексте change'а на уровне смысла, не технических имён
  — не упоминать имена файлов, имена детекторов, технические идентификаторы
  — формулировать как команду Клоду: «Убери...», «Добавь...», «Сократи...»
  — каждая строка должна быть понятна без открытия других файлов
  — каждая строка заканчивается подсказкой: `(непонятно — скажи «поясни», слишком очевидно — скажи «детали»)`
если нет замечаний: тело `_нет замечаний_`, заголовок остаётся>
→ Подробный технический отчёт: .logs/<name>/contradiction-<TS>.md

## Решено самостоятельно
<опционально; decision-gate развилки, закрытые автономно; формат: «вопрос → решение»; опускается если пусто>

## Прочее
<опционально; риторические замечания, follow-up идеи; опускается если пусто>

## Вопросы к пользователю
<только вопросы про желаемое поведение, на которые можно ответить не зная кода; технические выборы Claude закрывает самостоятельно и фиксирует в `## Решено самостоятельно`>
<каждый вопрос заканчивается подсказкой: `(непонятно — скажи «поясни», слишком очевидно — скажи «детали»)`>
<если вопросов нет — ровно одна строка: `Продолжаю.`>
<синтетический CTA «Продолжаем по флоу?» ЗАПРЕЩЁН>
<этот блок — последний; после него нет заголовков и прозы>
<блок `## Как проверить` НЕ рендерится — он только в sdd:apply>

Правила коммуникационного стиля:

1. По умолчанию — действие, не вопрос. Любую развилку, закрываемую разумным предположением, закрывай автономно и фиксируй в ## Решено самостоятельно. В ## Вопросы к пользователю — только decision-gate вопросы или реальные user-only вопросы.
2. Форма ответа = форма запроса. Шестиблочный формат — только в этом финальном выводе. В промежуточной переписке — проза, 2–3 предложения, без markdown-секций.
3. Действие первое, отчёт после. Никаких pre-action narration для диагностических шагов.
4. Ноль внутреннего жаргона в user-facing полях. В ## Описание, ## Что делать и ## Вопросы к пользователю SHALL NOT появляться: имена файлов, имена детекторов, hard issue, drift_score, residual_risk, SSOT, pointer-rewrite, convergence. Весь технический дамп — только в лог-файле.
5. «Поясни» — максимум одно предложение. Если пользователь отвечает «поясни», «не понял», «сложно» или аналогично — следующий ответ строго одно предложение на русском языке без технических терминов, имён файлов и вариантов реализации. При повторном «поясни» — переформулировать иначе, но снова одним предложением, объём не увеличивать.

Write-then-replay (если PATH — change-директория)

После рендера диалогового отчёта (User-facing wrapper) запиши весь форматированный вывод в файл и воспроизведи его — это гарантирует сохранность вывода при запуске через Agent tool.

1. Запиши блоки ## Описание, ## Найденные противоречия, ## Что делать, ## Решено самостоятельно (если присутствует), ## Прочее (если присутствует), ## Вопросы к пользователю и строку → Подробный технический отчёт: ... в файл .logs/<name>/contradiction-${TS}-output.md через Write tool. Используй тот же TS, что был получен на шаге Log write.

2. Выведи содержимое файла через Bash tool:

   cat ".logs/<name>/contradiction-${TS}-output.md"
   

Если PATH — не change-директория — пропусти молча.

State-update (если PATH — change-директория)

После рендера отчёта запиши pending_transitions для hook'а:

# при hard_counts.total == 0:
python3 "${CLAUDE_SKILL_DIR}/../scripts/state_manager.py" --ns sdd --skill contradiction --step ok --state-file "<change-dir>/.sdd-state.yaml"

# при hard_counts.total > 0:
python3 "${CLAUDE_SKILL_DIR}/../scripts/state_manager.py" --ns sdd --skill contradiction --step failed --state-file "<change-dir>/.sdd-state.yaml"

PostToolUse hook применит переход автоматически. Если hook не настроен — state не обновится, скилл продолжает работать.

Если PATH — не change-директория — пропусти этот шаг молча.