kunolu/640-skills/sbtd-workflow-onboard

SBTD Workflow Onboard Skills

Use this Skill to onboard a local machine and initialize one or more projects with the SBTD workflow templates bundled under templates/.

The repository root installers are install.sh and install.ps1. scripts/onboard.py implements checks, plans, template writes, global Skill installation, read-only per-project SBTD state/bootstrap checks, and the explicitly authorized migration plan/apply/verify/reconcile phases.

The directory remains self-contained: catalog.json is the machine-readable source catalog, catalog.schema.json is its Draft 2020-12 contract, scripts/ is the Onboard implementation, templates/ is the install payload, and assets/ contains managed third-party fallback snapshots and migration support assets. Keep this separation when adding catalog entries; do not move install payloads beside runtime code merely to flatten paths.

v2 Delivery and Release Boundaries

The v2 catalog carries 14 bundled / 19 external Skills and on-demand SBTD setup. Explicit Codex/OMP project graph/MCP wiring, root-installer forwarding, migration and cleanup/recovery have separate implementation and acceptance records. A source checkout or successful installation is not release, Windows-native or actual-host proof. Check the repository's published tag and release evidence for those claims. Graft installation, real-project deployment and legacy retirement each require their independent authorization.

P1-01 supplies the internal argument and exchange-contract modules (scripts/onboard_arguments.py, scripts/onboard_contracts.py, onboard-contracts.schema.json). P1-12 registers migration --phase plan|apply|verify; P1-04/P1-05 add the Codex/OMP deployment producers through existing init entry points, and cleanup/recovery are implemented by their owning tasks. Do not substitute contract fixtures, valid hashes, or a copied directory for executed migration or recovery evidence.

P1-17 adds the task-state Python library inside scripts/ (sbtd_task_document.py, sbtd_task_state.py). TaskStore exposes create / inspect / select / transition / set_mode / resume / reopen / protect_local_state / promote / archive for host-native callers; it is not a new global CLI, daemon, journal, or onboard.py subcommand. The task document owns state and the active JSON is only a bookmark. Markdown structure recognition uses the declared dependency markdown-it-py>=4,<5 (CommonMark tokens, parse-only, no rendering, no network; Python >=3.10) — a missing dependency stops writes explicitly instead of falling back to hand-rolled scanning. Promotion and archive are two-phase: prepare and verify the target candidate and references first, then a separate confirmation retires the original directory atomically into .sbtd/task-originals/ without recursive deletion. Candidate copies use a protected temporary area owned by the current operation; sibling logical task records require explicit include_tasks authorization, and path nesting is not ownership. Non-Git projects record a null branch; first-time narrow protection only appends /.sbtd/. When the installed helper copy or its declared dependencies are unavailable, callers must report that persistence did not run instead of claiming it. Windows, host routing, identity creation and legacy migration remain later stages.

任务节点同步由 scripts/sbtd_task_sync.py 的 TaskSync(TaskStore(root)) 提供：check 按跟踪状态选择 A／B／C，record 成对记录开始／完成及文件证据，record_check 经确认只追加差异，不自动 reopen；check_finish_commit 本地检查 B 方案的限定收尾 diff。每个节点第一步先核对并更新 task.md；进展、状态、事件与代码同 commit，push／开 PR 前再核对 tip。完整入口、旧格式不追溯／惰性基线及收尾边界见 templates/skills/sbtd-task/references/state.md。检查只用 Git／本地文件，不调用平台工具，不接入 CI；不回填上一 PR 合并 SHA／时间。

Task cancellation is an explicit terminal state, cancelled, not a successful completion. Keep completed_at null; do not cancel children implicitly, count cancelled bootstrap as done, or emit unfinished-work reminders for it. Archive/reopen preserve cancellation history. Imported cancelled/blocked facts retain unproven mode/time rather than inventing them, and an unknown blocked ingress still needs an explicit recovery-phase choice. Update the task runtime, schema and references together before using the new records; older readers may reject them. Exact historical event and reason rules are in Canonical legacy task candidates.

P1-18 adds deterministic routing and protected handoff helpers in the same scripts/ directory (sbtd_task_routing.py, sbtd_handoff.py), again without a new global CLI, daemon, journal, or onboard.py subcommand. TaskRouter only maps facts the host has already made explicit (a RouteRequest intent of new / continue / question, an explicit mode, a recommendation response of accept / keep, and read-only / confirmation flags) to a deterministic RouteDecision (ready, needs-task-choice, needs-mode-choice, needs-mode-decision, needs-branch-choice, needs-persistence-confirmation, persistence-failed, blocked); it is not a natural-language intent classifier. Continuation resolves exactly one task before any mode decision, refusals persist in a structured mode_note deduplicated by risk identity, and a failed save keeps the in-session choice while reporting it as not persisted. TaskStore additionally exposes current_binding, recovery_candidates and rebind: a branch mismatch requires the correct worktree, an explicit rebind (with expected_branch, reason, evidence and confirmation; it updates only the binding and its event — no checkout, no stash, no reset of blocked recovery history), or a read-only choice. HandoffStore saves snapshots only on a real pause / context-switch / branch-switch / context-pressure / manual trigger — status counts or entering checking never trigger; task and session opt-outs latch independently (session wins) and a manual request does not clear them. save returns one of saved, suppressed, conversation-only, branch-conflict, unprotected, unchanged, pending-confirmation, needs-redaction: writes first verify the narrow docs/handoffs/ protection and tracked state and require an explicit redaction_confirmed; file names carry the lowercase hex of the UTF-8 full logical task ID (collision-free even on case-insensitive filesystems, reversible), and an unchanged same-task snapshot — compared on every field except created_at — is not rewritten across a day boundary. Proactive reminders only cover the latest per-task snapshots within seven days whose root/branch match an unfinished task; older snapshots remain manually resumable but never rewrite the task, a branch mismatch rejects the write, and a handoff is never the source of mode or status. Whether the Agent truly recommends first, pauses, and executes the full method per mode remains owned by the Skill rules and real-host proof; this slice does not claim Windows, host wiring, automatic session-start restoration, legacy migration, full validation, or release.

P1-19 adds on-demand developer identity in scripts/sbtd_identity.py, again without a new global CLI, daemon, initializer, or identity database. DeveloperStore(root, read_only=False) exposes read-only resolve() / plan(name) and the confirmation-gated ensure(name, confirmed=False, protect=False), all returning a frozen IdentityResult (status, name, source, path, first_write_eligible, topology, reason, needs_protection, completed_steps). A valid local .sbtd/developer wins immediately without any Git call; only a genuinely absent local file triggers verification of the real Git toplevel, absolute git-dir/common-dir and the NUL-separated worktree registry, and a verified linked worktree reads the same-repo main checkout's current identity in place without copying it. Present-but-abnormal local or main files (duplicate name= declarations, invalid value, wrong type, symlink, unreadable, unsafe parents) are conflicts, not absence; unknown or unavailable Git metadata is blocked, not proof of a non-Git project. Names pass only the single validate_developer_name (^[a-z0-9]+$, verbatim); nothing is inferred from Git, OS, environment or history, and ordinary resolution never reads legacy .trellis/.developer. onboard.py consumes identity only through an explicit --developer <name>: check / plan stay read-only and add a developerPlan object to the single JSON document, while init / reset / init-projects require --developer together with --yes and preflight every listed project's identity plan before any global or project write; without --developer nothing changes and reset never rewrites an existing identity. Narrow /.sbtd/ ignore protection and the name are confirmed separately. The root installers gain no developer-specific flag and forward the implemented public flags; legacy identity migration remains the separately gated P1-12 task.

P1-12 migration uses an existing external private vault and explicit approved candidates; plan creates nothing. apply --yes preserves originals, installs only approved projections, pauses proven owned legacy Codex/OMP routing, and atomically saves a new cumulative receipt beside the manifest. Retries require the explicit prior receipt and preserve successful results and original backups. verify reads actual artifacts/resources and bound deployment reports without deploying or cleaning up. If a completed apply left its deployment evidence unsaved, migration --phase reconcile with explicit --yes freshly observes current state and writes one new typed evidence document at a new private path — the historical receipt, its exit code and its timestamps are never fabricated, and the following standard verify reports acceptance_basis: current-state; reconcile authorizes no install, retry or cleanup. Direct share copies preserve source bytes; rewritten content needs redact. Mixed or unknown configuration is preserved for reconciliation, not broadly overwritten. Read Migration Runtime before these commands; this staged consumer implementation is not permission to migrate real projects or claim real host/Windows acceptance.

The migration planner supports characterized 0.6.15 / 0.6.17 legacy data layouts, with the original stamps and metadata preserved. 0.6.15 hash claims for lessons/runtime/junk do not confer generated ownership or bypass user-data approval. Genuinely absent project host roots permit platforms: []; unknown/new host roots and incomplete marker-operation closures still reject. This data compatibility does not expand vendor-uninstall CLI support or authorize source repair, publication, deployment, cleanup or recovery. See Migration Runtime for the exact boundaries.