# Forkctl Workflow Redesign — Decisions
- 2026-08-03 Treat the redesign as a new product contract: no compatibility readers, aliases, migrations, or fallback behavior for any prior manifest, CLI, local state, task, or JSON API shape.
- 2026-08-03 Preserve the proven protocol/view architecture and Git/StGit delegation, but reconsider every public command, argument, state object, and manifest field from first principles.
- 2026-08-03 Patch ownership is explicit. Forkctl never guesses intent or automatically chooses a patch from filenames.
- 2026-08-03 Forkctl provides smart, efficient commands and customization points; it does not monopolize Git, StGit, hook management, file globs, or operator choice.
- 2026-08-03 Hook behavior is manager-neutral. VSH uses mise plus Lefthook and receives a first-class preset, while another consumer may call the same forkctl checks from another manager.
- 2026-08-03 Staged capture is the proposed safe default because the index is an explicit snapshot and StGit natively supports `refresh --index`; all-worktree and path-scoped capture remain explicit alternatives.
- 2026-08-03 Design the complete workflow, CLI, JSON protocol, manifest, hook composition, recovery semantics, verification, release, and fleet cutover before implementation code begins.
- 2026-08-03 Use `ask_user` only for final design choices or real surviving ambiguity; do not use Plannotator for this initiative.
- 2026-08-03 PR #1 is evidence only. Reimplement its valid history, API error, report newline, and test-isolation findings in coherent layers; never merge it as the implementation base.
- 2026-08-03 Generic forkctl never mutates GitHub organization rulesets. VSH owns a narrow durable protected-branch policy for approved fork repositories.
- 2026-08-03 Give most long CLI options a deliberate short form. Reserve global shorts across the full tree, reuse local shorts only across disjoint subcommands, and leave a long option without a short only when the abbreviation would be misleading or collide.
- 2026-08-03 Model leaf-command parameters after justpath: small orthogonal concerns, repeatable values, sensible defaults, explicit format, and useful composed shortcuts rather than proliferating mode subcommands.
- 2026-08-03 Render clean colored width-aware help from the Clap command graph through forkctl's existing Anstyle/Comfy Table theme. Do not adopt `clap-help` because it cannot render subcommands, and do not maintain a second handwritten parameter model.
- 2026-08-03 One `check` command owns validation. Full repository checking is the default; `-s`/`--staged` selects the narrower index check. Remove `verify` rather than creating two strict-sounding commands or an optional `staged` subcommand for what is only a mode parameter.
- 2026-08-03 Mise receives the complete forkctl grammar through `usage-lib`'s direct Clap conversion and a mounted `fork` task. Do not duplicate command flags in task TOML or maintain one shallow task per forkctl command.
- 2026-08-03 Approved workflow: explicit metadata-only active intent, normal Git staging, smart staged-by-default refresh with explicit all/path alternatives, repeatable refresh, and finish as full-check-plus-clear.
- 2026-08-03 Approved CLI: top-level primary verbs, patch/operation/API families only for distinct actions, parameterized check scope, composable justpath-style flags, collision-audited shorts, data-driven colored help, and full dynamic completion.
- 2026-08-03 Approved API: one typed local request/response protocol, execute/plan modes, complete selectable JSON Schemas, stable typed results/notices/errors/details, and exact CLI parity.
- 2026-08-03 Approved integration: one mounted mise `fork` task generated from Clap with correct Usage and cwd macros; hook-manager-neutral checks with first-class optional Lefthook/mise composition.
- 2026-08-03 Approved recovery: one typed in-flight operation journal with status/continue/abort, plus operation-level history bound to exact annotated recovery objects; no generalized second VCS log.
- 2026-08-03 Mise source and documentation confirm that file-task CLI wrappers should self-mount their generated Usage spec through `mise run task -- --usage-spec`; the mount runs only for shell completion so task-local tools are available. Forkctl uses `raw_args = true` so validation/help/exit behavior pass directly to forkctl, and `--quiet` keeps completion free of mise banners.
- 2026-08-03 Root `mise.toml` is the sole source for the minimum mise, Rust, StGit, Lefthook, Usage, and GitHub CLI versions. `[workspace.package].version` is the sole forkctl release source. `mise run version:sync` regenerates the lockfile and operational copies; no operator updates copied pins manually.