[SoundBlaster]

Summary

Install SpecDraft notes and preview independently of the SpecGraph developer checkout, with one versioned CLI, packaged assets and self-contained skill. Proposal 0230 records the bounded delivery contract.

Motivation

Consumer projects currently depend on a changing source checkout. A fixed pipx installation lets them keep using SpecDraft while development and worktree cleanup continue separately.

Goals

• Deliver specgraph notes, specgraph preview, specgraph --version and explicit skill export.
• Preserve existing source CLI/data contracts. Full supervisor distribution, Docker, native Windows and package-index publication remain separate.

Changes

• Package the existing notes/preview modules, both CLI façades, all four HTTP assets and a matching skill/reference; retain consumer data outside installed files.
• Capture the actual request through notes and supervisor intake/proposal-lane helpers: user_intent::specdraft-portable-runtime-20261027 → proposal::0230 (under_review). Record five proposal obligations and draft criterion/test bindings. No model refinement or canonical adoption is claimed.
• Add installed-artifact CI for Python 3.10/3.14, retaining sdist/wheel and the installation receipt. Keep source-checkout instructions separate from the installed skill. Rehearse CN-CAPTURE from a pinned historical snapshot so evolving pyproject.toml does not rewrite or freeze previous reviews; changes within a selected review snapshot still fail.

Spec Evidence

Spec-ID: SG-SPEC-0007
Proposal-ID: 0230
Spec-Impact: tooling
Spec-Rationale: Preserve attributed intent and review boundaries while distributing the existing note/preview implementation independently. Governance specs remain unchanged; the draft target has no canonical Requirement binding.
Intent-Decision-Review: tools/intent_decision_reviews/0230_portable_specdraft.json

CLI dispatch, package-resource copying and destination byte checks are adapter/filesystem mechanics. Preview continues to reuse the existing immutable display-state Specifications; this packaging slice adds no domain policy classes merely to increase S.

Validation

• Tests added/updated for changed behavior
• Local checks passed

Commands run:

make test
make docc-sync proposal-tracking-gate materialization-packet-check spec-evidence-gate
.venv/bin/python -B tools/python_quality.py
# On TB5: build 1.3.0 sdist → wheel, pipx 1.8.0 install into an isolated tool prefix.
 .venv/bin/python -B tests/specdraft_distribution_smoke.py --command <pipx-bin>/specgraph --python <pipx-venv>/bin/python --wheel <built-wheel> --project <external-consumer> --forbidden-source-root <checkout> --source-revision df21c438b89df66e5bda22a0db48f8090ac342a3 --output <receipt>
make intent-decision-review SPEC_EVIDENCE_BASE_REF=a837ec632397310450b96ce21c7f4faf03b8233b INTENT_DECISION_REVIEW_ARGS='--pr-body-file <exact-description-file>'

Results:

• Installed wheel 0.2.0: all seven smoke scenarios passed on macOS/Python 3.12.11, module origins outside the developer checkout and exact pinned SpycificationCore commit verified. Source-bound observation.
• Focused compatibility tests: 60 passed, 1 skipped. Initial full suite: 3202 passed, 4 skipped, 7 failures (six historical CN-CAPTURE build-input bindings and one Node24 workflow setting). After the fixes, all 18 CN-CAPTURE tests and all 14 workflow tests passed. A second complete suite was not run; hosted CI rechecks the final snapshot.
• DocC sync, proposal tracking, materialization-packet integrity, spec evidence and Python quality passed. Intent decision review binds the final source snapshot and exact PR body.

Risks / Notes

• Backward compatibility impact: source notes/preview CLIs and notebook formats remain intact; python -m specgraph now exposes the real CLI instead of the scaffold greeting.
• Migration/config changes required: install the actual wheel with pipx, export the skill to an explicit directory and select a persistent consumer sketch. Existing differing skill files are refused; global agent configuration is not edited.
• Known limitations: this candidate is not published on PyPI; installing dependencies requires network/Git access. Local probes verify HTTP/resource behavior, not browser rendering, canonical acceptance or evidence admission. Hosted CI/review are pending when the PR is opened.

Checklist

• PR title clearly describes the change
• Scope is focused and minimal
• Documentation updated (or N/A)
• Workflow/artifact changes distinguish presence from readiness/status
• Consumers prefer authoritative repaired/promoted/latest artifacts where relevant
• Temporary or intermediate paths are scoped to the current run/task where relevant
• No secrets or sensitive data added

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-27T15:46:38.167613Z	f28c14d	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[github-actions]

Intent Atoms · v1

Scope: specification YAML in specs/nodes

Status: complete
Count: 302 → 302 (+0)
Diff: +0 added, −0 removed, 0 modified
Revisions: a837ec632397 → b63ff9b87de0
Profile: specgraph-intent-atoms-v1 (SHA-256 54caf075dafc)
Analyzer: 1.0.1 (SHA-256 aa7c646a25ea)

Proposal obligations · draft

Status: complete for declared fields
Count: 18 → 23 (+5)
Diff: +5 added, −0 removed, 0 modified
Coverage: explicit YAML declarations in docs/proposals; unannotated Markdown is not assessed.
Draft counts are separate from specification counts; they do not establish review, approval or canonical promotion.

Informational only; this report does not gate merge readiness.

[SoundBlaster]

HyperReview

Эскиз по исходникам · b63ff9b8

Состав · изменения в проекции

--- before.hc
+++ after.hc
@@ -0,0 +1,3 @@
+PortableSpecDraftRuntime
+  InstalledCommandFacade
+  SkillResourceInstaller

Выбранные связи · после

PortableSpecDraftRuntime:
  calls: "main → install_skill; main → notes_main; main → preview_main"
SkillResourceInstaller:
  calls: "install_skill → skill_contents"

Пояснения, источники и ограничения

Суть изменения

PR добавляет установленный Python-интерфейс SpecDraft: метаданные пакета задают команду `specgraph`, фасад маршрутизирует notes и preview к сохранённым интерфейсам и добавляет явную установку ресурсов skill. Также добавлены руководство, smoke-сценарий и workflow сборки/установки; фрагмент workflow неполный и не подтверждает запуск. Комментарии и документация утверждают сохранение прежних заметок и предпросмотра, а неизменённые исходные API/store и preview подтверждают, что их реализация в этом PR не менялась. Уточнены ограничения: выбранное workspace хранит данные отдельно от установки, preview остаётся loopback/read-only, кандидат не заявлен опубликованным в package index, а полный supervisor, Docker и native Windows находятся вне среза.

Интерпретация выбранных исходников; порядок узлов не означает порядок выполнения.

− и + показывают удаление и добавление в соответствующей ветке проекции; смена родителя тоже выделена, даже если строка узла не изменилась.

Связи и основания

Связи описаны отдельно от вложенности .hc; основания — в правой колонке.

Связь	Что видно в источниках	Основания
main → notes_main	После; интерпретация исходников; вызов операции. Фасад `main` в ветви `args.command == "notes"` импортирует `main as notes_main` из `conversation_notes_cli` и вызывает `notes_main(remaining)`. Это непосредственная передача notes-команды; реализация и дальнейшие вызовы notes_main здесь не представлены.	cli.py: main L12–38
main → preview_main	После; интерпретация исходников; вызов операции. В ветви `args.command == "preview"` `main` импортирует `main as preview_main` из `specdraft_preview_cli` и вызывает его с оставшимися аргументами. Это непосредственный вызов фасада; тело целевой функции не предоставлено.	cli.py: main L12–38
main → install_skill	После; интерпретация исходников; вызов операции. Для команды skill фасад вызывает `install_skill(args.destination)`, затем кодирует результат в JSON. Это прямой переход от CLI к установщику ресурсов.	cli.py: main L12–38
install_skill → skill_contents	После; интерпретация исходников; вызов операции. `install_skill` непосредственно вызывает `skill_contents()` перед проверкой назначения и записью файлов. Результат функции — словарь имён и байтов ресурсов; его реализация читает фиксированный набор ресурсов из `specgraph` через `importlib.resources`.	distribution.py: skill_contents L12–22, install_skill L25–55

Связи в Hypercode (.hcs)

Это неполные выборки связей из каждой версии. Отсутствие связи в одной из выборок не устанавливает её добавление или удаление. Пустой лист означает, что связи для этой версии не выбраны.

before.hcs

# Paired review context; no relationship recorded on this side.

after.hcs

PortableSpecDraftRuntime:
  # После; интерпретация исходников; вызов операции. Для команды skill фасад вызывает `install_skill(args.destination)`, затем кодирует результат в JSON. Это прямой переход от CLI к установщику ресурсов.
  # Sources: src_4f1d84caf47feadc9e2838e083c0de61f97c2e3ff8e90952faf027de329c2330
  # После; интерпретация исходников; вызов операции. Фасад `main` в ветви `args.command == "notes"` импортирует `main as notes_main` из `conversation_notes_cli` и вызывает `notes_main(remaining)`. Это непосредственная передача notes-команды; реализация и дальнейшие вызовы notes_main здесь не представлены.
  # Sources: src_4f1d84caf47feadc9e2838e083c0de61f97c2e3ff8e90952faf027de329c2330
  # После; интерпретация исходников; вызов операции. В ветви `args.command == "preview"` `main` импортирует `main as preview_main` из `specdraft_preview_cli` и вызывает его с оставшимися аргументами. Это непосредственный вызов фасада; тело целевой функции не предоставлено.
  # Sources: src_4f1d84caf47feadc9e2838e083c0de61f97c2e3ff8e90952faf027de329c2330
  calls: "main → install_skill; main → notes_main; main → preview_main"
SkillResourceInstaller:
  # После; интерпретация исходников; вызов операции. `install_skill` непосредственно вызывает `skill_contents()` перед проверкой назначения и записью файлов. Результат функции — словарь имён и байтов ресурсов; его реализация читает фиксированный набор ресурсов из `specgraph` через `importlib.resources`.
  # Sources: src_83ff47f4b38c7a4573bdc20e81dc6c6f33e461bb20812cf5ba345e8cf32d3b88
  calls: "install_skill → skill_contents"

Ответственности и источники

• PortableSpecDraftRuntime — В PR добавлен PortableSpecDraftRuntime: новый пакет связывает установленную команду с сохранёнными CLI заметок и предпросмотра и экспортом навыка. До изменения в `src/specgraph` был каркас без этой ответственности; исходные заметки и предпросмотр существовали отдельно. Это новая упаковочная граница, а не переименование этих функций. src/specgraph/cli.py — после; src/specgraph/distribution.py — после; pyproject.toml — после; docs/proposals/0230_portable_specdraft_runtime.md — после

• InstalledCommandFacade — Добавлен InstalledCommandFacade: `main` разбирает команды и передаёт оставшиеся аргументы существующим notes/preview CLI, а команду skill направляет установщику. Этот фасад нужен как новая граница установленного интерфейса; он не заменяет исходные CLI. Комментарий в модуле описывает намерение оставаться фасадом, тогда как исполняемое поведение подтверждают ветви диспетчеризации и вызовы. src/specgraph/cli.py — после

• SkillResourceInstaller — Добавлен SkillResourceInstaller: ресурсы читаются из пакета и копируются только в явно заданное место; совпадающее содержимое допускает повторную установку, несовпадающее отклоняется, создание использует эксклюзивный режим. Это новая область ответственности: существующие роли заметок и предпросмотра её не покрывают. Документация отдельно уточняет границу: глобальные настройки агента автоматически не меняются. src/specgraph/distribution.py — после; src/specgraph/resources/skills/specgraph-conversation-notes/references/usage.md — после

Границы анализа

PR #812: a837ec632397310450b96ce21c7f4faf03b8233b → b63ff9b87de01f80a6ca584d9c296ab2d19055a0.

Исходников в анализе: 41; пропущено: 14.

Компилятор проверил структуру Hypercode и ссылки. Соответствие интерпретации коду и поведение программы этим не доказаны. Анализ ограничен предоставленными исходниками и фрагментами контекста; выполнение программы не наблюдалось.

• Конфигурация: .github/workflows/specdraft-distribution.yml; after; охват partial; фрагментов 3. L1–10: configuration_context_omitted; L11–13: configuration_environment_redacted; L19–19: configuration_context_omitted; L20–21: configuration_environment_redacted; L25–25: configuration_secret_line; L34–37: configuration_environment_redacted; L40–43: configuration_environment_redacted; L44–48: configuration_context_omitted

• Конфигурация: pyproject.toml; after / before; охват complete; фрагментов 1.

• Конфигурация: tools/intent_decision_reviews/0230_portable_specdraft.json; after; охват complete; фрагментов 1.

Неизменённых файлов контекста по Git blob: 8. Их фрагменты до и после могут различаться охватом.

• Карты .hc/.hcs в предоставленных данных отсутствуют, поэтому срез ролей выведен из исходников и документов; авторские имена и пути карты сопоставить нельзя.

• Предоставленные тесты `tests/test_specdraft_distribution.py` и `tests/specdraft_distribution_smoke.py` описывают и содержат проверки, но наблюдаемого запуска и CI результата нет. Workflow дан фрагментами; его пропущенные строки и фактическое выполнение неизвестны.

• Не предоставлены реализации `conversation_notes_cli.py` и `specdraft_preview_cli.py`, которые вызываются фасадом; прямые вызовы в `cli.py` видны, но дальнейшая диспетчеризация, установка и поведение в окружении не наблюдались.

• `tools/conversation_notes/api.py`, `tools/conversation_notes/store.py` и preview-модули отмечены неизменёнными по полному blob. Их предоставленные фрагменты подтверждают существующий контекст, но не свидетельствуют об изменении этих реализаций в PR.

• Не предоставлены полные требования, изменения CONTRIBUTING.md и большинство путей из inventory, включая скрытые политикой; нельзя установить все изменения и обязательства за пределами доступных фрагментов.

• Пропущено: tools/conversation_notes/api.py — context_excerpted (до: 1).

• Пропущено: tools/conversation_notes/store.py — context_excerpted (до: 1).

• Пропущено: CONTRIBUTING.md — input_byte_limit (после: 1).

• Пропущено: путь скрыт политикой — operator_file (после: 1); unsupported_format (после: 10).

Точные диапазоны источников по узлам

PortableSpecDraftRuntime

• src/specgraph/cli.py — после: L1–42

• src/specgraph/distribution.py — после: L1–55

• pyproject.toml — после: L1–52

• docs/proposals/0230_portable_specdraft_runtime.md — после: L12–15, L41–44, L66–69

InstalledCommandFacade

• src/specgraph/cli.py — после: L12–38

SkillResourceInstaller

• src/specgraph/distribution.py — после: L1–55

• src/specgraph/resources/skills/specgraph-conversation-notes/references/usage.md — после: L1–72

Ок или не ок?

CI · результаты проверок

Снимок для b63ff9b8 · 2026-10-27T15:53:49Z (UTC).

Результат check-run не доказывает выполнение конкретного теста, полноту покрытия или соответствие архитектуре.

Проверка	Статус	Результат
Deploy landing page to static host	completed	skipped
Deploy bundle to static host	completed	skipped
Prepare case-sensitive redirect artifact	completed	skipped
deploy	completed	skipped
Build DocC technical surface	completed	success
test	completed	success
publication-diagnostic-compatibility (3.14)	completed	success
registered-rule-reuse	completed	success
publication-diagnostic-compatibility (3.10)	completed	success
specdraft-preview-ui	completed	success
python-quality	completed	success
spec-evidence	completed	success

Снимок неполный: показано не более 12 проверок.

Отсутствие, ожидание или сбой CI не блокируют архитектурный обзор.

Review gate: review thread.

[github-actions]

SpecificationMetrics · diagnostic PR measurement

Metric	Base	PR head (Δ)
Specifications (S)	125	125 (+0)
Remaining opportunities (U)	10296	10303 (+7)
S/U	0.0121406	0.0121324
Dead Specifications	0	0
Unknown Specifications	0	0

Collection: base complete, head complete.
Primary provisional: base False, head False.
Revisions: a837ec632397 → b63ff9b87de0; contract 943b09cbbe20.
Base diagnostics: none reported.
Head diagnostics: none reported.

• Python CC / Cog: cc_sum +20; cc_max +0; cog_sum +17; cog_max +0; sloc +81
• Clone pairs / duplicate lines / tokens: clone_pairs +1; duplicate_lines +8; duplicate_tokens +67

Scope: files assigned application by the manifest; tests/ is test, and the comment renderer is framework.
Informational only. Counts and metrics do not decide eligibility, correctness, or merge readiness.
Collection run
Detailed JSON reports and counting contract
Artifact presence does not imply a complete measurement; inspect report statuses and diagnostics. Downloads require GitHub access and expire with artifact retention.