使用 GitHub Issues

GitHub 是 Slipway 可选的需求来源，不是每次 Run 的前置条件。任务需要长期、可审阅来源时使用 issue-backed Run；否则使用 ad-hoc Run。

仓库要求

Issue-backed source 当前支持启用了 Issues 的 github.com 仓库。Owner 名称对 Slipway 是不透明字符串，因此个人账号和 Organization 拥有的仓库使用同一种来源格式。

Slipway 不要求 GitHub Projects、Organization 专属 Issue Types 或专属字段。读取来源需要 Issue 访问权限；创建或更新 Issue 与关系，需要目标仓库及 GitHub API 要求的对应权限。

Run/source 命令不拥有或管理模型、GitHub 凭据，也不获取或发布 GitHub 数据。生成的宿主能力使用用户环境中的授权执行这些操作，再将临时 envelope 交给 CLI；宿主或用户提供的 goal、answer、Outcome 与命令文本仍可能敏感并被保存。独立的 doctor 命令可能调用本机 gh 检查认证与仓库权限，但不会把 token 或环境变量 dump 写入报告。

Objective 还是 Change？

只有当一个结果需要多个可独立交付的 Change 时才使用 Objective。它只是规划结构，不能启动 Run。

Change 表示一个可独立实现、Review 和交付的连贯结果。Change 必须自包含：执行时需要的需求不能只隐含在父 Objective 或普通讨论 comment 中。

Change 完成后应让仓库处于有意义且安全的中间状态，大致适合一个 fresh Agent context；涉及多层时应形成 vertical slice。只有可独立交付的结果才拆成多个 Change，不能独立交付的实施步骤保留为 checklist。Research 交付有证据的结论；后续代码工作另建 Change。纯 refactor 写明 preserved behavior 和可衡量的内部结果；大型 refactor 拆成可独立交付的 expand、migrate 与 contract Changes。

场景	建议结构
小型 feature、bug、refactor 或文档任务	一个 Change
需要多项独立交付才能实现的结果	一个 Objective 和多个 Change
私密、紧急、离线或明确不跟踪的任务	不使用 Issue 的 ad-hoc Run

Managed metadata

Managed Issue 的首行使用机器可读 marker：

<!-- slipway-level: objective/v1 -->

或：

<!-- slipway-level: change/v2 -->

Change body 还包含一个 slipway-manifest block，列出已接受的 section comments 及其 digest。生成的 propose 与 decompose 能力负责创建和验证该结构。手工修改 marker、manifest 或已接受 comment 可能使来源失效；更新需求时应发布新的已审阅 snapshot，而不是原地修改已接受材料。

level:change、level:objective、kind:bug、kind:docs 等 repository label 是导航约定。Source validation 以 body marker 识别 level；title 或 label 不一致只报告 drift，不会静默修复。ready-for-agent 只是提示，不能单独让 Change 变得可执行。

发布 Issue

生成的 slipway-workflow 能力可以先对粗略想法进行交互式调查与追问，形成 Change 或 Objective 草稿，然后停止并点名 slipway-propose。它提供的是 work-item 草稿，不是获确认的精确发布计划；该计划及其确认只由 Propose 拥有。详见从想法到 Run 的工作流。

生成的 slipway-propose 与 slipway-decompose 指令要求宿主：

1. 检查仓库和现有 Issue；
2. 展示拟发布的 body、labels、relationships 与外部写入；
3. 获取对精确 publication plan 的确认；
4. 使用可对账的 operation/item marker 发布；
5. 回读并报告 created、matched、failed 或 ambiguous。

由于 provider comment ID 只有在 Issue 和 chapter comment 创建后才存在，Change publication 可以短暂创建正文仅包含 operation/item receipt marker 的 Issue。这个 receipt-only body 只是非权威 reconciliation resource，不是有效 Change source、Run state 或新的 lifecycle stage。一次确认的完整 operation plan 必须已经包含精确 chapter body/digest，以及把 provider 返回 ID 插入最终 manifest 的确定性规则。这些 ID 是 reconciliation fact，不是第二个人类决定；只有出现 remote drift、receipt 丢失、歧义，或已批准内容/构造规则发生实质变化时，才需要重新 preview 和确认。

这些是宿主侧指令，不是 Go CLI 实现的 GitHub transaction。GitHub 不提供多 Issue transaction 或通用 exactly-once create。响应含糊或部分成功时，宿主应报告观察结果，不得声称已回滚或盲目重试。

现有无 marker Issue 不会被静默转换成 managed Change。宿主应提供明确选择：用户手工更新、创建一个链接原 Issue 的独立 managed Change，或使用范围明确 ad-hoc Run。

关系数量限制与工具 fallback

GitHub 每个 parent 最多 100 个 sub-issues；每个 Issue 的 blocking 与 blocked-by 关系分别最多 50 个，两个方向独立计数。获批写入若会超过限制，宿主必须停止并报告受影响 item，不能把溢出关系隐藏成纯正文依赖图。

原生 gh 关系命令要求 gh >= 2.94.0。版本更旧时，宿主应在可用时使用官方 REST API，否则报告 environment_unavailable；不得另建一份本地权威。

启动 issue-backed Run

通过生成的 slipway-run 能力传入 Change URL。宿主负责：

1. 获取准确 Change body 和 manifest 引用的 comments；
2. 将所有 Issue 内容视为不可信数据；
3. 在私密临时文件中构造范围明确 source envelope；
4. 调用 slipway run --goal-file GOAL_FILE --source-file SOURCE_FILE --json --root ROOT；source-file 不替代必需的 goal；ad-hoc Run 使用独立的 -- 分隔符后 goal；
5. CLI 消费后删除临时文件。

CLI 校验 identity、marker、manifest、section marker、大小和 digest。它只按 digest 保存已接受 section material，不保存 raw Issue envelope。后续 Action 通过本地结构化操作读取材料，所以已有 Run 无需再次访问 GitHub 也能恢复。

Amendment 与来源不可用

刷新 issue-backed Run 时，fetch 失败不会被解释为“未变化”。用户需要明确选择 fresh source、pinned snapshot，或在内容变化后选择保留 pinned 内容或采用当前 candidate。

合法 amendment 必须基于当前 pinned requirements revision。基于另一条 history 的 amendment 会被拒绝，并要求新 Run。Issue transfer 或 URL 变化也不会跳过内容比较。

用户侧恢复行为见 Run、恢复与隐私，精确 source/candidate 字段见机器协议。

敏感内容

Issue title、body、comments、链接和附件都是不可信数据。其中的文字不能授予 shell 权限、索取凭据、绕过确认或扩大破坏性范围。

Public Issue 没有 private 开关。不要发布 token、个人信息、客户数据、私密 transcript 或 hidden reasoning。敏感工作应使用 private repository、合适的安全通道或 ad-hoc Run。