Поддержать новый функционал hostScript в документации, AI-guidance и интеграции хоста

[flancer64]

Контекст

В библиотеке @teqfw/github-flows принята и реализуется модель двух startup-preparation steps:

• hostScript — host-side pre-launch step;
• setupScript — container-side startup step.

Для github-flows-app это означает, что хост-приложение должно быть приведено в соответствие с новой моделью не только в runtime/docs для людей, но и в AI-facing guidance, operational/security описаниях и, при необходимости, в product/integration logic.

Сейчас в репозитории основная operational story всё ещё в основном ориентирована на старую схему:

• профиль показывает только setupScript;
• токен обычно описан как статически смонтированный secret file;
• host-side pre-launch preparation как отдельный поддерживаемый шаг почти не отражён.

Задача

Привести github-flows-app в соответствие с новой моделью hostScript во всех релевантных слоях репозитория:

• documentation for humans;
• AI/agent guidance;
• operational and security guidance;
• integration model хоста;
• при необходимости code/config support или follow-up scope на него.

Что нужно сделать

1. Обновить документацию для людей

Проверить и обновить как минимум:

• README.md
• docs/overview.md
• docs/runtime-dependency.md
• docs/workspace.md
• docs/setup/README.md
• docs/setup/ubuntu/auth.md
• docs/setup/ubuntu/docker.md
• другие docs/setup/*, если они описывают startup, profiles, secrets или container launch

Нужно:

• различить hostScript и setupScript;
• показать их порядок и разные execution environments;
• обновить profile examples, где сейчас фигурирует только setupScript;
• описать, как host может подготавливать execution-scoped artifacts до container startup;
• не допустить противоречий с boundary-моделью, где runtime library владеет profile semantics.

2. Обновить AI-facing guidance

Проверить и обновить все agent-facing инструкции в репозитории, которые могут влиять на работу AI по этому проекту.

Как минимум проверить:

• AGENTS.md
• ctx/-связанные указатели, если они есть в репозитории продукта
• ai/, если каталог присутствует и содержит package guidance
• другие локальные инструкции для агентов/ассистентов

Нужно отразить:

• что модель runtime теперь включает hostScript;
• где проходит граница между host-side и container-side preparation;
• что long-lived secrets остаются host-local;
• что execution-scoped artifacts должны рассматриваться как временные и ограниченные по области действия.

3. Проверить security и secret-handling guidance

Нужно отдельно проверить, что документация не оставляет двусмысленности относительно:

• long-lived host secrets;
• GitHub App / PAT / token file сценариев;
• execution-scoped generated tokens/files;
• workspace visibility;
• cleanup temporary artifacts после run;
• недопустимости утечки секретов в публичные или долговременные operational surfaces.

Если нужно, дополнить docs отдельными operational rules.

4. Проверить host integration model

Нужно явно проверить и при необходимости обновить формулировки о том, как github-flows-app соотносится с runtime library:

• host supplies infrastructure and environment;
• runtime owns profile selection and execution semantics;
• host-side hostScript support не превращает приложение в workflow engine;
• host может обеспечивать pre-launch execution step, не забирая ownership у runtime model.

5. Оценить необходимость product/code changes

Нужно определить, ограничивается ли работа документацией или для поддержки новой модели нужны изменения в самом приложении.

Если нужны изменения, зафиксировать их явно:

• где должен появиться host-side pre-launch step;
• какие config/env inputs нужны;
• как должны materialize-иться execution-scoped artifacts;
• как должно происходить cleanup;
• какие части нужно реализовать в этом репозитории, а какие оставить как follow-up.

Если кодовые изменения не нужны, это тоже нужно явно подтвердить.

6. Проверить examples и consistency по всему репозиторию

Нужно пройтись по примерам и формулировкам во всём репозитории и убрать ситуацию, где setupScript подаётся как единственный preparation step.

Особенно важно, чтобы:

• примеры profile fragments были актуальны;
• docs для людей и AI не расходились между собой;
• security guidance не противоречил новым operational examples.

Ограничения

• Не менять библиотечный контекст github-flows в рамках этой задачи.
• Если нужны code changes, они должны относиться только к github-flows-app.
• Не переопределять модель hostScript, уже принятую в библиотеке и её контексте.

Критерии приёмки

Задача считается выполненной, если:

• human-facing docs в github-flows-app согласованы с моделью hostScript;
• AI-facing guidance также обновлён и не противоречит human-facing docs;
• security/secret-handling guidance покрывает сценарии host-side pre-launch preparation;
• examples больше не описывают setupScript как единственный preparation step;
• отдельно зафиксировано, нужны ли product/code changes для реальной поддержки новой модели.

Что нужно указать в итоговом отчёте

В комментарии или PR summary нужно указать:

• какие docs и guidance-файлы были обновлены;
• какие части репозитория были проверены на consistency;
• какие product/code changes потребовались или не потребовались;
• как теперь в github-flows-app описан сценарий host-side hostScript;
• какие follow-up задачи остались после этой работы.

[adsm-agentess]

Issue admitted for execution.

Reason:

• The request belongs to this repository and matches the documented host-application scope around @teqfw/github-flows.
• The requested work is clear enough to route without guessing.
• The requested outcome requires repository changes across documentation and agent guidance, with an explicit check for any needed host-side product/code support.

Next state: adsm:accepted

[adsm-agentess]

Finalized from merged PR #7 (bd742e5): the linked source work is verified in the base branch and is now marked adsm:completed.