@brainervirus/workit-cli 0.10.0 → 1.0.0

package/README.md

@@ -1,10 +1,14 @@
 # @brainervirus/workit-cli
 
+[![CI](https://github.com/BrainerVirus/workit/actions/workflows/ci.yml/badge.svg)](https://github.com/BrainerVirus/workit/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/@brainervirus/workit-cli.svg)](https://www.npmjs.com/package/@brainervirus/workit-cli)
+[![license: MIT](https://img.shields.io/badge/license-MIT-green.svg)](../../LICENSE)
+
 The workit CLI — an interactive Ink wizard that configures workit for OpenCode and/or Cursor, plus an offline installation doctor.
 
 ## Requirements
 
-- **Node.js ≥ 22** — the published CLI is a self-contained Node bundle (no Bun runtime). Node 21 and below fail (`ERR_MODULE_NOT_FOUND`/ESM syntax or the `>=22` engine gate).
+- **Node.js ≥ 24** — the published CLI is a self-contained Node bundle (no Bun runtime). Node 23 and below fail (`ERR_MODULE_NOT_FOUND`/ESM syntax or the `>=24` engine gate).
 
 ## Install
 
@@ -20,28 +24,34 @@ npx @brainervirus/workit-cli init
 workit init              # interactive setup wizard
 workit doctor            # offline installation health report
 workit doctor --json     # machine-readable report
-workit flow status --plan docs/<slug>/plan.md        # read the effective flow state
-workit flow pause --plan docs/<slug>/plan.md [--confirm]     # active -> paused
-workit flow resume --plan docs/<slug>/plan.md [--confirm]    # paused -> active
-workit flow complete --plan docs/<slug>/plan.md [--confirm]  # complete (ledger + verification gated)
-workit flow review-package --plan docs/<slug>/plan.md --base <sha> --head <sha> [--confirm]  # write a review diff
-workit flow append-advisory --plan docs/<slug>/plan.md --task <id> --text <text> [--confirm]  # record an advisory review finding
-workit handoff --message "docs/<slug>/plan.md"      # print the destination handoff prompt
-workit                   # help
+workit <family> <action> [--payload <json|@file|->] [--task <id>] [--revision <uuid>] [--workspace-revision <uuid|null>] [--view full] [--actor <id>] [--confirm] [--json]
+workit action <operation> --payload <JSON> [--preview] [--confirm] [--task <id>] [--json]   # preview or run one approved external action
+workit handoff --task <id> [--json]                   # export task state and compact destination context
+workit cutover preview [--hosts ..] [--json] | apply [--hosts ..] [--resolution k=v] [--confirm] | rollback preview|apply <backupId> [--json] [--confirm]
+workit uninstall                           # remove host registrations (keeps ~/.config/workit)
+workit                                     # help
 ```
 
 `workit init` guides you through: platform selection (OpenCode/Cursor), global config (locale, timezone, branch policy), YouTrack, VCS, workspaces (path globs → provider), and project hygiene files. The wizard is a TTY application — `workit init` requires an interactive terminal and prints guidance (exiting nonzero) when stdin is not a TTY.
 
 `workit doctor` checks the offline installation health and exits nonzero when problems are found; `--json` prints the full report as JSON instead of the human-readable table.
 
-`workit flow` maps the shared-core execution lifecycle (`pending`/`active`/`paused`/`completed`) to the CLI: `status` reads the effective flow state (approval digests, drift, execution, handoff-destination flag); `pause`/`resume`/`complete` mutate it with `--confirm` (or a TTY prompt when stdin is a TTY, exit 2 when neither applies); `review-package` writes the review diff for a `--base..--head` range through the shared core guard, which rejects empty ranges. `workit handoff` prints the core destination handoff prompt (four-choice menu, never the originating Handoff option) and marks the flow as a handoff destination; a second handoff on an already-marked destination is rejected. Domain/verification failures exit 1 with structured JSON on stderr; usage errors exit 2.
+The task surface exposes the eight shared operation families (`task`, `policy`,
+`evidence`, `finding`, `decision`, `worker`, `writer`, and `state`) and their 24
+closed actions. Payloads can be inline JSON, a UTF-8 `@file`, or UTF-8 stdin
+with `-`; `--json` preserves the structured Result shape and exits nonzero for
+failures. Headless mutations that require consent use `--confirm` (agent-reported)
+or an observed TTY prompt; the action route additionally requires an
+interactive TTY — headless action calls return `needs_input` even with
+`--confirm`. `workit handoff --task` is read-only and refuses to
+emit a handoff when export and inspection revisions differ.
 
 ## Behavior
 
 - **Safe apply semantics** — a malformed `config.json` is detected before the wizard renders and reported as a friendly blocked output instead of crashing; the same guard runs after the Apply preview.
 - **Stable interaction** — unchanged wizard inputs are no-ops; they settle without React render warnings and never discard draft state.
 - **Clean terminal** — only `warn`/`error` diagnostics print to stderr; routine structured `info` records stay in the JSONL journal. Nonzero failures and human-readable errors remain visible.
-- **Node support** — the packed CLI runs on Node 22+; installation on Node 22.19 emits no engine warning from workit's dependency tree.
+- **Node support** — the packed CLI runs on Node 24+; installation on Node 24 emits no engine warning from workit's dependency tree.
 
 ## Package scripts
 

package/assets/templates/execution-contract.md

@@ -1,73 +1,40 @@
-Load `using-superpowers`, `subagent-driven-development`, `test-driven-development`, and `verification-before-completion` through OpenCode's `skill` tool. Implement the existing plan; do not re-plan.
+Load resolved method skills through the host skill loader when policy selects them. Implement the existing plan; do not re-plan.
 
 **Spec:** <SPEC_PATH>
 **Plan:** <PLAN_PATH>
 **Branch:** <BRANCH>
-**SDD:** `<SDD_DIR>`
-
-## Handoff destination
-
-This session is a handoff destination for a continued plan. The originating session already recorded the post-plan menu choice; present exactly these four choices plus model deferral and never re-offer the originating handoff option:
-
-- Subagent-driven
-- Inline
-- Review spec first
-- Review plan first
-- Change model first
-
-<workflow-handoff-destination>true</workflow-handoff-destination>
 
 ## Hard gates
 
-- The parent is coordinator-only: it does not edit product code or perform delegated exploration.
-- Never use a worktree. Branch changes are in-place through `workit_branch_setup` on `feature/*` or `bugfix/*`; never commit on protected branches.
-- Working state, briefs, ledgers, and review diffs live only under gitignored `<SDD_DIR>` in `docs/<slug>/sdd/` and use `workit_sdd_*` tools.
-- Use native `todowrite` for visible task state as well as the gitignored ledger.
-- Use native `question` for branch/stash choices and guarded external mutations; call mutation tools only after approval with `confirmed: true` (grounded in the recorded NativeChoiceEvidence).
-- Flow-tool confirmations are never agent-typed booleans and never caller-supplied evidence objects: on OpenCode the plugin records the user's native-`question` answer as a host-observed one-use receipt (`attested: true`, `callID`, `selectedLabel`, `recordedAt`) consumed by `workit_spec_approve` / `workit_plan_approve` / `workit_plan_menu` — no evidence argument exists, and delegated worker status comes from host session parentage (`parentID`), never a caller `role` field. On Cursor, confirmations are policy-only (`attested: false`) and subagent-driven execution is rejected as unsupported.
-- Delegated authority is direct-child-only: a worker is the session whose host `parentID` exactly equals the activating coordinator's recorded `coordinator_session_id`; missing, mismatched, or multi-owner lineage fails closed with `delegation_lineage_denied`, and nested `opencode` launches are denied during active delegated work. An authorized child receives only the compact worker contract (execute the supplied brief, follow TDD, land one contiguous non-empty commit range, report results) — never coordinator guidance, `wk-implement`, or ledger management; coordinator bookkeeping via `workit_sdd_*` stays with the coordinator session.
-- On Cursor, for every repository-scoped `workit_*` call, pass the active Cursor workspace as `workspace_root`; never rely on the MCP process default.
-- Use native `task` with only the built-in `explore` and `general` agents.
-
-## Flow gates (HARD)
-
-- `wk-implement` refuses to run unless the plan is `approved` (flow.json) and the post-plan menu was presented.
-- `wk-handoff` refuses to run unless both spec and plan are `approved`.
-- Sequence is enforced by tools: `workit_spec_approve`, `workit_plan_approve`, `workit_plan_menu` — never skip a step (the spec/plan self-review runs automatically inside the transition; only the final approval asks for your confirmation).
+- Inspect task state before acting. On OpenCode, Cursor, Codex, and Pi use the eight shared `workit_*` families (`workit_task`, `workit_policy`, `workit_evidence`, `workit_finding`, `workit_decision`, `workit_worker`, `workit_writer`, `workit_state`). On the CLI host use `workit <family> <action>` with the same actions (hyphenated on the CLI).
+- Never use a worktree. Branch changes are in-place through the approved `git.branch_setup` external action (CLI: `workit action git.branch_setup --payload …`).
+- Task metadata lives under `.workit/`; never edit it directly. Record progress, evidence, findings, decisions, and worker state only through the shared operations.
+- Helpers cannot widen scope, record binding decisions, close or pause the task, assign further helpers, or resolve blockers for the lead.
+- On Cursor, pass the active workspace as `workspace_root` on every repository-scoped call.
 
 ## Setup
 
-0. Call `workit_docs_validate` with the linked spec/plan paths. Hard-fail on any error before todos or branch setup.
-1. Call `workit_sdd_context` with `<PLAN_PATH>` and initialize `todowrite` from returned tasks.
-2. Call `workit_plan_tasks`; cache each top-level task's `section_text`.
-3. Mark IDs in `completed_task_ids` completed and never redispatch them.
-4. Call `workit_resolve_branch`, then show the current branch, target branch, and stash behavior before any in-place checkout/setup mutation.
-5. Always use `question`: for a clean tree ask whether to proceed or cancel; for a dirty tree add the stash choice and describe what will be stashed.
-6. Call `workit_branch_setup` with `confirmed: true` only after approval.
+1. If there is no active or paused task, call `workit_task` with `action: "start"` then `workit_policy` with `action: "assess"` (CLI: `workit task start …` then `workit policy assess …`).
+2. Load `workit-plan`, list tasks with `workit_task` `action: "list"`, and mirror visible todo state to the host UI.
+3. When policy requires a feature branch, resolve it with read-only `context.read` and apply `git.branch_setup` only after native approval.
 
 ## Remaining-task loop
 
-For each top-level task absent from `completed_task_ids`:
+For each bounded plan task:
 
-1. Mark it `in_progress` with `todowrite`.
-2. Create a working-state brief with `workit_sdd_task_brief` and `confirmed: true`.
-3. Delegate read-only discovery, when needed, to an `explore` agent. Delegate implementation to a fresh `general` agent. Product changes follow TDD.
-4. Create a working-state diff with `workit_sdd_review_package` and `confirmed: true`.
-5. Delegate spec-compliance review and code-quality review to separate `general` agents.
-6. **Blocking** findings (Critical, Important, or spec-compliance) may trigger at most **two** fix+re-review rounds per task. **Advisory** findings (Minor, style, YAGNI, taste) never pause the loop — append them with `workit_sdd_append_advisory` (`--task <id> --text <text>`, `confirmed: true`) instead of an unrestricted file edit.
-7. Append the validated ledger entry with `workit_sdd_append_progress` and `confirmed: true`; mark the todo completed.
+1. Mark the item in progress in the host todo UI and record boundary progress with `workit_task` `action: "progress"`.
+2. Route by policy: assign bounded workers with `workit_worker` `action: "assign"` when delegation is available; otherwise implement inline. Acquire product-write ownership with `workit_writer` `action: "acquire"` before repository mutations; release it when done.
+3. Record checks and artifacts with `workit_evidence` `action: "record"`. Record review concerns with `workit_finding` `action: "record"`; resolve or defer them with `finding.resolve`. Blocking findings may trigger at most **two** fix+re-review rounds per task; advisory taste/YAGNI items still use `finding.record` and never pause the loop by direct file edit.
+4. Never advance while a foreign writer is active or blocking findings remain open for the current candidate.
 
 ## Final gate
 
-Run a separate full-branch code review, then `workit_verify`. Present the full `<SDD_DIR>/advisories.md` roll-up once, then use native `question` so the user can choose which advisory items to fix, discuss, or discard. Report exact check results and never infer success. Use `workit_git_context` for a commit preview and load `wk-commit` through `skill` for an approved commit. If working state contains a stash reference, preview reapplication through `question`, then call `workit_branch_setup` with `confirmed: true` after approval.
-
-**Mandatory:** end the run by calling `workit_plan_complete` (OpenCode/Cursor) or the CLI `workit flow complete` (CLI host) after the final task once the SDD ledger is complete (all task IDs appended) and `workit_verify` passes — a complete ledger and green verification are the tool's gates. Never finish the run while the plan is still `active`.
+Run repository verification (CLI: `workit doctor`; hosts: approved project verify when policy requires it). **Mandatory:** close the lead task with `workit_task` `action: "close"` (CLI: `workit task close --payload … [--confirm]`) once requirements are satisfied and verification passes — never finish while the task is still `active` or `paused`.
 
 ## Task order
 
 <TASK_LIST>
 
-## Quality gate (HARD)
+## Quality gate
 
-- Specs/plans are written from `templates/spec-template.md` / `templates/plan-template.md`.
-- After `workit_docs_validate`, surface `quality` findings (spec scan). Hard findings (missing required section, missing CA-XX) block task start unless the user explicitly waives them. Warnings are advisory.
+- Specs/plans follow `templates/spec-template.md` / `templates/plan-template.md`.

package/assets/templates/plan-template.md

@@ -1,6 +1,6 @@
 # <Feature> Implementation Plan
 
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+> **For agentic workers:** Load `workit-implement` when policy selects implementation. Use bounded `workit_worker` delegation when the host supports it; otherwise execute inline within writer scope. Steps use checkbox (`- [ ]`) syntax for tracking.
 
 **Spec:** `docs/<slug>/spec.md`
 **Branch:** `feature/<slug>`
@@ -9,8 +9,8 @@
 
 ## Global Constraints
 
-- Each task lands exactly one contiguous non-empty commit range (`base..head`): fix rounds append commits to that range and never rewrite/amend an active review range; each progress line records the task's real base..head shas.
-- The final task ends execution with `workit_plan_complete` (or the CLI `workit flow complete`) once the SDD ledger is complete and repository verification passes — a run never finishes while the plan is still `active`.
+- Each task lands exactly one contiguous non-empty commit range (`base..head`): fix rounds append commits to that range and never rewrite/amend an active review range; record the real base..head shas in task progress.
+- The final task closes the lead Workit task with `workit_task` `action: "close"` (CLI: `workit task close --payload … [--confirm]`) once requirements are satisfied and repository verification passes — never finish while the task is still `active` or `paused`.
 - <project-wide requirements, one line each>
 
 ---

package/assets/templates/spec-template.md

@@ -2,6 +2,9 @@
 
 **Branch:** `feature/<slug>`
 
+**Change:** ADDED|MODIFIED|REMOVED — <one-sentence intent>. (Small work with
+no durable agreement: `Spec: none (<reason>)`, no file.)
+
 ## Context
 
 <!-- Why does this exist? What problem does it solve? 1-3 sentences. -->
@@ -16,13 +19,14 @@
 
 ## Architecture
 
-<!-- REQUIRED if this spec has flows or architecture: render a mermaid diagram (workit_present_flow). -->
+<!-- May be `N/A (<reason>)` when the change has no flows or architecture. -->
+<!-- Otherwise REQUIRED: render a mermaid diagram (workit-diagram skill). -->
 ```mermaid
 flowchart TD
   A[Start] --> B[Step]
 ```
 
-<!-- REQUIRED if this spec touches UI: render an ASCII wireframe (workit_present_ascii). -->
+<!-- REQUIRED if this spec touches UI: render an ASCII wireframe (workit-mockup skill). -->
 ```text
 ┌──────────────┐
 │ Header       │
@@ -39,8 +43,16 @@ flowchart TD
 ## Acceptance criteria
 
 <!-- REQUIRED: enumerable, each verifiable. Numbered CA-01, CA-02, ... -->
+<!-- Requirements use SHALL/MUST (one per bullet, observable, no HOW); each
+     carries at least one GIVEN/WHEN/THEN, including the most-regretted edge. -->
 - CA-01 …
-- CA-02 …
+
+## Review checklist
+
+<!-- Before implementation: intent matches; nothing extra; each requirement
+     testable with an exercising scenario; most-cared case covered;
+     tasks trace to requirements; you would sign if built exactly as written. -->
+- [ ] …
 
 ## Decisions
 

package/assets/templates/workit-contract.md

@@ -0,0 +1,12 @@
+# Workit contract
+
+Workit keeps one accountable lead and one shared task state. Inspect current
+task state before acting; use only the shared operations for task, policy,
+evidence, finding, decision, worker, writer, and state changes. Authority is
+bounded by the requested scope, current revision, caller/session provenance, and
+observed capabilities. Never claim host enforcement or evidence that the host
+cannot provide. Preserve unresolved requirements, gaps, and uncertain workers.
+
+Focused methods are loaded only when the resolved policy requires them. A method
+must call the shared operations and must not create a second lifecycle, approval
+chain, or task-state representation.