用途
st 是持久化工作图的真实来源（durable work truth），原生计划仅是其投影。文档给出的核心心智模型是：将意图编译为持久图状态、审计、编译一个有界的安全孔径与 GCR、只投影该孔径、执行、记录义务级证明、重新编译。它适用于使用 .step/st-plan.jsonl 进行材料级（material）计划与依赖管理、恢复持久工作、以及携带证明的完成流程。
主要能力与工作模式
st 提供三种模式：
- 图模式（Graph Mode）：面向含意图原子、契约化可执行项、硬依赖边、证明义务、图谱系与可实施审计的材料计划。其必需的控制命令为
st compile aperture --file .step/st-plan.jsonl --limit 7。文档说明当前 st 在该命令上仍接受旧版--parallelism auto作为无操作的兼容别名，但不应在新指令中写入该标志。对于材料图工作，若没有当前的 GCR-v1（收据序号与指纹匹配所投影的持久计划状态），不得执行或投影原生计划。 - 降级图模式（Degraded Graph Mode）：当图状态存在但仍有阻塞性图债时，孔径预览可能有用，但除非存在精确的活跃豁免，否则禁止交付变更与完成声明；GCR 必须显示模式、债务、豁免与门控决策。
- 账本/简单模式（Ledger/Simple Mode）：仅用于小型有界工作或旧版 v3 状态，命令包括
st add ...、st set-status ...、st set-proof ...、st complete ...。文档要求不得静默地将材料计划路由到简单任务模式；若未编译图，应明确说明 “Graph not compiled; proceeding in ledger mode.”
使用方式
文档建议假定使用已文档化的当前 CLI，不要主动调用多个 --help 界面；仅在版本确实不确定或出现未知命令错误时使用一次探测 st capabilities --format json，并在会话中缓存结果。
材料接入（Material Intake）流程示例：
st intake scaffold --source docs/plan.md --out .step/st-intake.md
# Agent fills or edits the semantic intake artifact.
st intake check --input .step/st-intake.md --gate implementation-ready --format json
st intake normalize --input .step/st-intake.md --out .step/st-intake.normalized.md
st intake apply --file .step/st-plan.jsonl --input .step/st-intake.normalized.md --gate implementation-ready
st compile aperture --file .step/st-plan.jsonl --limit 7
文档指出 st intake plan 是 scaffold 的已弃用别名；在 agent 编写的 intake 通过 check 与 apply 之前，scaffold 不算语义编译。接入始终作用于权威的 .step/st-plan.jsonl，不得创建诸如 .step/*-st-plan.jsonl 的替代持久计划文件来绕过既有图债，应通过 st 命令修复权威图，或以审计/接入诊断失败。
对于现有健康图，从 st compile aperture --file .step/st-plan.jsonl --limit 7 开始，然后只把输出的 plan_sync.codex.plan 镜像到 update_plan，或把 plan_sync.opencode.todos 镜像到 OpenCode。
投影规则包括：持久来源为 .step/st-plan.jsonl；不得创建旁路持久计划文件；原生计划工具仅作投影；只能通过 st 命令变更持久状态；只投影 plan_sync.codex.plan 或 plan_sync.opencode.todos，绝不投影整个 plan_sync 对象；保留 [st-id] 作为每个 Codex 可见步骤的首个 token；将仅持久的字段排除在原生计划之外；除非当前 GCR 证明选定了安全并行波次，否则保持恰好一个 Codex in_progress 行；等待依赖的项不得被镜像为 in_progress。
执行与证明方面，只执行选定的孔径，工作后按义务级记录证明，示例：
st proof plan --file .step/st-plan.jsonl --scope aperture --format json
st proof record \
--file .step/st-plan.jsonl \
--id st-001 \
--obligation proof-001 \
--action proof-action-test-st \
--command "zig build test-st" \
--evidence-ref .step/proof/st-001-proof-001.log \
--artifact-ref "git:<sha-or-working-tree-fingerprint>"
st complete --file .step/st-plan.jsonl --id st-001
st compile aperture --file .step/st-plan.jsonl --limit 7
st assert-projection --file .step/st-plan.jsonl
文档说明 st set-proof 仍是兼容性便利命令，不得用一个含糊的遗留证明来满足多个不同的必需命令。若本地安装的 st 拒绝某组已文档化的证明标志组合，不要在发布循环中纠缠解析器细节；在它接受 obligation/action/command 标志时优先使用上述规范形式；若该构建只接受较小的完成面，则保持图状态与最小可接受的 st complete 命令一致，并将解析器不匹配记为后续工具修复，而非发明旁路证明状态。
图债命令（当 GCR 阻塞执行时使用）：
st graph debt list --file .step/st-plan.jsonl --format json
st graph debt waive --file .step/st-plan.jsonl --id debt-... --reason "..." --expires on-next-touch
st graph debt resolve --file .step/st-plan.jsonl --id debt-...
对材料工作而言，未豁免的阻塞性图债意味着 execution_allowed: no。
首次使用的存储策略：在仓库中首次执行 st init 或变更之前，需确定 .step/st-plan.jsonl 是共享还是本地。若已被跟踪则遵循共享模式；若已被忽略则遵循本地模式；若不清楚，应询问该文件应提交以供共享评审，还是通过 .git/info/exclude 保持本地。共享模式：跟踪 .step/st-plan.jsonl，忽略 .step/st-plan.jsonl.lock。本地模式：两者均忽略。
最终响应时，对材料级 $st 工作需报告：GCR id、模式（graph、degraded 或 ledger）、就绪前沿、阻塞前沿、选定波次、关键路径/深度、安全并行决策、证明依据与证明状态、图债、投影断言。若未编译图，需包含 “Graph not compiled; proceeding in ledger mode.”。
适用场景与限制
适用于需要持久化依赖图、可审计完成证明和受控并行执行的工程工作流，尤其是与 Codex、OpenCode 等原生计划工具配合的场景。限制包括：未提供 GCR-v1 时不得投影或执行材料计划；未豁免的阻塞性图债会禁止执行；不得创建旁路持久计划文件；简单模式仅限小型有界工作。关于安装命令、收费、价格、平台支持等信息，资料中暂未提供。