ai-spector 0.8.97 → 0.9.2

package/README.md

@@ -1,6 +1,8 @@
 # AI Spector
 
-Documentation workflow in **Cursor** or **Claude Code**: traceability graph, SRS, basic design, and UI prototypes (static HTML or SPA). **Describe what you need in chat** — the agent matches a **skill**, reads its runbook, and runs `ai-spector` MCP tools. You rarely touch the terminal.
+Documentation workflow in **Cursor** or **Claude Code**: traceability graph, SRS, basic design, and UI prototypes (static HTML or SPA). **Describe what you need in chat** — the agent matches one of **4 skills**, reads its runbook, and runs `ai-spector` MCP tools. You rarely touch the terminal.
+
+**Kari Writer** owns the `.docops/` contract only (no agent skills). ai-spector is an optional local tool that implements that contract via git files.
 
 **Needs:** Node 20+, Git, [Cursor](https://cursor.com) and/or [Claude Code](https://docs.anthropic.com/en/docs/claude-code), Python 3.11+ *(optional — CocoIndex semantic search)*.
 
@@ -43,16 +45,27 @@ The init wizard prompts for editor (Cursor, Claude Code, or both), languages, gi
 
 Creates:
 
-- `.ai-spector/` — config, graph, templates
 - `.docops/` — Writer contract (`docops.config.json`, comments, review-queue, prototype metadata)
+- `.ai-spector/` — engine store (`engine.json`, graph, registry, work sessions)
 - `docs/data-source/`, `docs/srs/`, `docs/basic-design/`
-- **Cursor:** `.cursor/` — skills, rules, `mcp.json`
-- **Claude Code:** `CLAUDE.md` + `.claude/skills/` + `.mcp.json`
+- **Cursor:** `.cursor/` — **4 skills**, rules, `mcp.json`
+- **Claude Code:** `CLAUDE.md` + `.claude/skills/` (4 skills) + `.mcp.json`
 - Pre-commit hook (when git is available)
 
-**Writer contract:** Kari Writer reads `.docops/docops.config.json` for capabilities and paths (see `kari-writer/contracts/CONTRACT.md` in the docs-ops meta-repo). ai-spector `init` scaffolds `.docops/` alongside legacy `.ai-spector/` during transition (`DOCOPS_DUAL_WRITE=1` by default).
+No `docflow.config.json` — fresh `init` writes the two-config model below.
+
+### Configuration (2 files)
+
+| File | Owner | Purpose |
+|------|-------|---------|
+| `.docops/docops.config.json` | **Writer contract** (shared) | Languages, doc layers, paths, **capabilities** |
+| `.ai-spector/engine.json` | ai-spector engine (local only) | Graph/task artifact paths, readiness, CocoIndex, `scaffoldVersion` |
 
-**Docops CLI** (Writer contract only — no full ai-spector scaffold):
+**Writer** defines the contract schema (`kari-writer/contracts/CONTRACT.md` in the docs-ops meta-repo). It ships **no agent skills**. **Capabilities** in `docops.config.json` gate Writer web UI, ai-spector CLI/MCP, skill install, and `check` rules.
+
+**`.docops/guide/`** is for human tool authors only — agents and skills must **not** load or link to it at runtime.
+
+**Docops CLI** (Writer contract bootstrap — no full ai-spector scaffold):
 
 ```bash
 npx ai-spector docops status              # human-readable layout + readiness
@@ -64,13 +77,18 @@ npx ai-spector docops init --force        # fill gaps when config already exists
 
 npx ai-spector docops migrate --dry-run   # preview legacy → .docops/ migration
 npx ai-spector docops migrate             # migrate layout + copy templates
+npx ai-spector docops migrate --from-docflow   # split docflow.config.json → contract + engine
 npx ai-spector docops migrate --templates-only   # copy templates only
 npx ai-spector docops migrate --repair    # fill gaps without overwriting existing files
 ```
 
-Migrate an existing legacy project with `docops migrate`; use `--templates-only` or `--repair` if templates or contract files are still missing. Full steps, verification checklist, and `DOCOPS_LEGACY_PATHS` transition notes: [`kari-writer/contracts/MIGRATION.md`](../../kari-writer/contracts/MIGRATION.md) in the docs-ops meta-repo.
+Upgrade from a legacy project that still has `docflow.config.json`:
+
+```bash
+npx ai-spector docops migrate --from-docflow
+```
 
-Plugin registry (`docflow.config.json` → `plugins.resolved`) still gates **CLI/MCP** only; Writer web uses `capabilities` from the `.docops/` contract as authoritative.
+Then run `npx ai-spector upgrade apply` to sync the 4-skill scaffold. Full migration steps: [`kari-writer/contracts/MIGRATION.md`](../../kari-writer/contracts/MIGRATION.md) in the docs-ops meta-repo.
 
 ### Upgrade (guided workflow)
 
@@ -86,7 +104,7 @@ npx ai-spector upgrade apply --auto
 npx ai-spector upgrade validate
 ```
 
-The upgrade workflow scans a package checklist, syncs scaffold, backfills config, and stamps `scaffoldVersion` in `docflow.config.json` when complete.
+The upgrade workflow scans a package checklist, syncs the **4-skill** scaffold, backfills config, and stamps `scaffoldVersion` in `engine.json` when complete.
 
 Legacy skills-only refresh:
 
@@ -115,7 +133,16 @@ The agent installs the npm dependency (if needed), verifies the checklist, and r
 
 ### Step 3 — Enable the agent *(manual, one-time)*
 
-**Cursor:** Settings → Rules → **Agent Skills** — enable **all** folders under `.cursor/skills/`. Reload MCP (`.cursor/mcp.json`).
+Enable the **4 skills** (not the retired 23-skill bundle):
+
+| Skill | Role |
+|-------|------|
+| `ai-spector` | Setup, upgrade, adopt, check, work sessions |
+| `ai-spector-generate` | SRS, basic/detail design, prototype, template import |
+| `ai-spector-graph` | Analyze, index, validate, impact, search, sync audit |
+| `ai-spector-contract` | Review sign-off, comments, prototype comments, translation |
+
+**Cursor:** Settings → Rules → **Agent Skills** — enable all four folders under `.cursor/skills/`. Reload MCP (`.cursor/mcp.json`).
 
 **Claude Code:** Skills load from `.claude/skills/`. Reload MCP (`.mcp.json`).
 
@@ -135,14 +162,14 @@ Continue in chat — see [Workflow](#workflow) below.
 
 ## Workflow
 
-After `init`, see `.cursor/WORKFLOW.md` (Cursor) or `CLAUDE.md` (Claude Code) for the full skill map.
+After `init`, see `.cursor/WORKFLOW.md` (Cursor) or `CLAUDE.md` (Claude Code) for the 4-skill map.
 
 ### How chat routing works
 
 | Piece | Role |
 |-------|------|
-| **Routing** | `_skill-router.md` + `ai-spector-routing.mdc` classify your message; `workflow_route` when ambiguous |
-| **Skill** | One workflow (analyze, generate SRS, review docs, …) with a runbook under `references/` |
+| **Routing** | `_skill-router.md` + `ai-spector-routing.mdc` classify your message → one of 4 skills; `workflow_route` when ambiguous |
+| **Skill** | One of four workflows (setup/work, generate, graph, contract) with a runbook under `references/` |
 
 Say what you want in natural language — same in Cursor and Claude Code. The agent reads the matching skill and follows its runbook. If intent is unclear (especially **“approve”**), it asks once before acting.
 
@@ -174,7 +201,7 @@ review documents
 | New or changed sources | “analyze data source” |
 | Check graph | “validate the graph”, “graph report” |
 | Regenerate docs | “generate SRS”, “generate basic design” |
-| Pause / resume work | “active tasks”, “resume my SRS”, “pause task” |
+| Pause / resume work | “active work”, “resume my SRS”, “pause work” |
 | One feature or section | “I want to add login with Google”, “update the auth section” |
 | After doc edits | “refresh the index”, “re-index the graph” |
 | Document sign-off | “review documents”, “approve srs/01-overview”, “what needs review” |
@@ -218,7 +245,11 @@ npx ai-spector course serve --open    # interactive course in browser
 npx ai-spector setup --check
 npx ai-spector docops status            # assess .docops/ layout and Writer readiness
 npx ai-spector docops init --lang en    # scaffold Writer-ready .docops/ contract
-npx ai-spector docops migrate           # legacy layout → .docops/ (+ templates)
+npx ai-spector docops migrate --from-docflow   # split legacy docflow.config.json
+npx ai-spector work list                # active/paused work sessions (replaces task)
+npx ai-spector work resume <workId>
+npx ai-spector contract review queue    # sign-off queue (capability: review)
+npx ai-spector contract comments inbox  # open comment threads (capability: comments)
 npx ai-spector graph validate
 npx ai-spector graph visualize --open
 npx ai-spector graph impact --git
@@ -226,6 +257,8 @@ npx ai-spector sync audit --fail-on-drift   # CI: design-layer drift since basel
 npx ai-spector prototype validate --strict
 ```
 
+MCP tools are grouped: `work_*` (session lifecycle), `contract_review` / `contract_comments` / `contract_prototype` / `contract_translate` (Writer contract ops). Legacy `task_*` and flat review/comments tools remain as deprecation wrappers for one release.
+
 Full list: `npx ai-spector --help`.
 
 ---
@@ -236,7 +269,7 @@ Full list: `npx ai-spector --help`.
 |-------|-----|
 | MCP tools unavailable | Reload MCP; confirm `.cursor/mcp.json` or `.mcp.json` has `ai-spector` server |
 | Setup incomplete | **“check ai-spector setup”** |
-| Skills not routing (Cursor) | Re-enable all folders under `.cursor/skills/` |
+| Skills not routing (Cursor) | Re-enable all **4** skill folders under `.cursor/skills/` |
 | Validate errors after edits | **“re-index the graph”** |
 | Pre-commit hook missing | **“install ai-spector git hook”** |
 | Agent stuck on CLI error | `.cursor/skills/ai-spector/references/cli-failures.md` |

package/README.vi.md

@@ -1,6 +1,8 @@
 # AI Spector
 
-Công cụ làm tài liệu phần mềm trên **Cursor** hoặc **Claude Code**: sơ đồ liên kết, SRS, basic design và prototype UI (HTML tĩnh hoặc SPA build ra file tĩnh). **Bạn chỉ cần nói trong chat** — agent sẽ tự chạy lệnh `ai-spector` hoặc MCP. Thường bạn không cần gõ lệnh terminal.
+Công cụ làm tài liệu phần mềm trên **Cursor** hoặc **Claude Code**: sơ đồ liên kết, SRS, basic design và prototype UI (HTML tĩnh hoặc SPA build ra file tĩnh). **Bạn chỉ cần nói trong chat** — agent chọn một trong **4 skills**, đọc runbook và chạy MCP `ai-spector`. Thường bạn không cần gõ lệnh terminal.
+
+**Kari Writer** chỉ sở hữu contract `.docops/` (không có agent skills). ai-spector là công cụ local tùy chọn triển khai contract qua file git.
 
 **Cần có:** Node 20+, Git, [Cursor](https://cursor.com) và/hoặc [Claude Code](https://docs.anthropic.com/en/docs/claude-code), Python 3.11+ *(không bắt buộc — dùng cho tìm kiếm thông minh với CocoIndex)*.
 
@@ -45,15 +47,46 @@ Wizard init sẽ hỏi: Cursor, Claude Code hay cả hai; ngôn ngữ; git hook;
 
 Sau khi chạy xong sẽ có:
 
-- `.ai-spector/` — cấu hình, sơ đồ, mẫu tài liệu
+- `.docops/` — contract Writer (`docops.config.json`, comments, review-queue, prototype)
+- `.ai-spector/` — engine (`engine.json`, graph, registry, work sessions)
 - `docs/data-source/`, `docs/srs/`, `docs/basic-design/`
-- **Cursor:** `.cursor/` — skills, rules, `mcp.json`
-- **Claude Code:** `CLAUDE.md` + `.claude/skills/` + `.mcp.json`
+- **Cursor:** `.cursor/` — **4 skills**, rules, `mcp.json`
+- **Claude Code:** `CLAUDE.md` + `.claude/skills/` (4 skills) + `.mcp.json`
 - Hook git trước khi commit *(nếu project có git)*
 
+Không còn `docflow.config.json` — `init` mới tạo mô hình 2 file cấu hình.
+
+### Cấu hình (2 file)
+
+| File | Sở hữu | Mục đích |
+|------|--------|----------|
+| `.docops/docops.config.json` | **Contract Writer** (dùng chung) | Ngôn ngữ, lớp tài liệu, đường dẫn, **capabilities** |
+| `.ai-spector/engine.json` | Engine ai-spector (local) | Đường dẫn graph/task, readiness, CocoIndex, `scaffoldVersion` |
+
+**Writer** định nghĩa schema contract (`kari-writer/contracts/CONTRACT.md`). **Không** ship agent skills. **Capabilities** trong `docops.config.json` điều khiển Writer web, CLI/MCP ai-spector, skills và quy tắc `check`.
+
+**`.docops/guide/`** dành cho người viết công cụ local — agent và skills **không** được đọc hoặc link tới thư mục này lúc chạy.
+
+**Docops CLI** (bootstrap contract Writer):
+
+```bash
+npx ai-spector docops status
+npx ai-spector docops init --lang en
+npx ai-spector docops migrate --from-docflow   # tách docflow.config.json → contract + engine
+npx ai-spector docops migrate --dry-run
+npx ai-spector docops migrate --repair
+```
+
+Nâng cấp project còn `docflow.config.json`:
+
+```bash
+npx ai-spector docops migrate --from-docflow
+npx ai-spector upgrade apply    # đồng bộ scaffold 4 skills
+```
+
 ### Nâng cấp (cập nhật skills & rules)
 
-Sau khi cài phiên bản `ai-spector` mới, refresh scaffold từ gói. Chỉ cập nhật skills và rules — **không** ghi đè `.ai-spector/`, graph, hay `docs/`.
+Sau khi cài phiên bản `ai-spector` mới, refresh scaffold **4 skills** từ gói. Chỉ cập nhật skills và rules — **không** ghi đè `.ai-spector/`, graph, hay `docs/`.
 
 ```bash
 npm install ai-spector@latest          # npm công khai; thêm --registry … cho Verdaccio
@@ -86,9 +119,18 @@ Agent sẽ cài gói npm (nếu thiếu), kiểm tra xem còn thiếu gì, hỏi
 
 ### Bước 3 — Bật skills *(làm tay một lần)*
 
+Bật **4 skills** (không phải bộ 23 skills cũ):
+
+| Skill | Vai trò |
+|-------|---------|
+| `ai-spector` | Setup, upgrade, adopt, check, work sessions |
+| `ai-spector-generate` | SRS, basic/detail design, prototype, import template |
+| `ai-spector-graph` | Analyze, index, validate, impact, search, sync audit |
+| `ai-spector-contract` | Duyệt tài liệu, comments, prototype comments, dịch |
+
 **Cursor**
 
-1. Vào **Settings → Rules → Agent Skills** — bật **hết** các thư mục trong `.cursor/skills/` (xem `.cursor/skills/README.md`)
+1. Vào **Settings → Rules → Agent Skills** — bật **4** thư mục trong `.cursor/skills/`
 2. **Reload MCP** — file `.cursor/mcp.json` đã cấu hình sẵn server `ai-spector`
 
 **Claude Code**
@@ -147,7 +189,7 @@ Hoặc chạy `npx ai-spector sync-cursor` / `sync-claude` — xem [Nâng cấp]
 
 ## Quy trình làm việc
 
-Sau khi `init`, xem thêm `.cursor/WORKFLOW.md` (Cursor) hoặc `CLAUDE.md` (Claude Code).
+Sau khi `init`, xem `.cursor/WORKFLOW.md` (Cursor) hoặc `CLAUDE.md` (Claude Code) — bản đồ **4 skills**.
 
 ### Lần đầu chạy
 
@@ -181,7 +223,7 @@ Sau đó: **“generate prototype for all screens”**. Với SPA, chạy build
 | Xem phần nào bị ảnh hưởng | “what’s the impact of my changes” |
 | Xử lý comment | “resolve comments”, “show open comments” |
 | Duyệt / phê duyệt tài liệu | “review documents”, “approve srs/01-overview” |
-| Tạm dừng / tiếp tục task | “active tasks”, “resume my SRS” |
+| Tạm dừng / tiếp tục work | “active work”, “resume my SRS”, “pause work” |
 | Thêm / sửa một phần nhỏ | “I want to add login with Google” |
 | Xem sơ đồ trực quan | “show the graph”, `npx ai-spector graph visualize --open` |
 | Kiểm tra workspace | “check my workspace” |
@@ -203,10 +245,18 @@ Chủ yếu dùng chat. Một số lệnh hữu ích:
 ```bash
 npx ai-spector course serve --open
 npx ai-spector setup --check
+npx ai-spector docops status
+npx ai-spector docops migrate --from-docflow
+npx ai-spector work list                 # work sessions (thay task)
+npx ai-spector work resume <workId>
+npx ai-spector contract review queue
+npx ai-spector contract comments inbox
 npx ai-spector graph validate
 npx ai-spector graph visualize --open
 ```
 
+MCP nhóm theo `work_*` và `contract_*` (review, comments, prototype, translate). Lệnh `task_*` cũ còn wrapper deprecation một phiên bản.
+
 Đầy đủ: `npx ai-spector --help`
 
 ---
@@ -217,7 +267,7 @@ npx ai-spector graph visualize --open
 |-----|------------|
 | MCP không chạy | Reload MCP; kiểm tra `.cursor/mcp.json` hoặc `.mcp.json` có server `ai-spector` |
 | Setup chưa xong | Trong chat: **“check ai-spector setup”** |
-| Agent không hiểu lệnh (Cursor) | Bật lại hết thư mục trong `.cursor/skills/` ở Settings → Rules |
+| Agent không hiểu lệnh (Cursor) | Bật lại **4** thư mục skill trong `.cursor/skills/` ở Settings → Rules |
 | Validate báo lỗi sau khi sửa | Trong chat: **“re-index the graph”** |
 | Thiếu hook git | Trong chat: **“install ai-spector git hook”** |
 | Agent bị kẹt vì lỗi CLI | Xem `.cursor/skills/ai-spector/references/cli-failures.md` |

package/dist/cli.js

@@ -22,8 +22,8 @@ import { runContextList, runContextRecord, runContextResolve, } from "./core/ope
 import { formatContextList, formatContextRecord, formatContextResolve, } from "./interfaces/cli/format/context.js";
 import { runSpecList, runSpecApprove, runSpecReject, } from "./core/operations/extracted.js";
 import { formatSpecList, formatSpecApprove, formatSpecReject, } from "./interfaces/cli/format/extracted.js";
-import { runTaskAbandon, runTaskApprovePlan, runTaskApproveImportPlan, runTaskApproveAdoptPlan, runTaskApprovePackDesign, runTaskComplete, runTaskCreate, runTaskGet, runTaskList, runTaskStatus, runTaskPause, runTaskResume, runTaskUpdate, recordGenerateWaveProgress, } from "./core/operations/task.js";
-import { formatTaskCreate, formatTaskGet, formatTaskList, formatTaskStatus, formatTaskSimple, formatTaskUpdate, } from "./interfaces/cli/format/task.js";
+import { registerWorkCommands, registerTaskCommands } from "./core/operations/work.js";
+import { registerContractCommands } from "./core/operations/contract-cli.js";
 import { buildClaudeScaffoldFromCursor } from "./core/scaffold/claude-from-cursor.js";
 import { runSyncClaude } from "./core/operations/sync-claude.js";
 import { runSyncCursor } from "./core/operations/sync-cursor.js";
@@ -308,302 +308,16 @@ spec
     else
         console.log(formatSpecReject(result));
 });
-const task = program
-    .command("task")
-    .description("Workflow task state (persist plan/progress across sessions)");
-task
-    .command("create")
-    .description("Create a new workflow task")
-    .requiredOption("-k, --kind <kind>", "generate | resolve | import")
-    .requiredOption("-w, --workflow <workflow>", "generate-srs | generate-basic-design | generate-detail-design | resolve | template-import")
-    .requiredOption("-t, --trigger <text>", "User intent that started this task")
-    .option("-C, --cwd <path>", "Project root", process.cwd())
-    .option("--doc-type <type>", "Doc type for generate workflows (e.g. srs)")
-    .option("--force", "Replace existing active task in the same slot")
-    .option("--json", "JSON output")
-    .action(async (opts) => {
-    const result = await runTaskCreate({
-        root: resolve(opts.cwd ?? process.cwd()),
-        kind: opts.kind,
-        workflow: opts.workflow,
-        trigger: opts.trigger,
-        docType: opts.docType,
-        force: opts.force,
-    });
-    if (opts.json)
-        console.log(JSON.stringify(result, null, 2));
-    else
-        console.log(formatTaskCreate(result));
-});
-task
-    .command("list")
-    .description("List tasks")
-    .option("-C, --cwd <path>", "Project root", process.cwd())
-    .option("-s, --status <status>", "Filter by status (comma-separated)")
-    .option("-k, --kind <kind>", "generate | resolve | import")
-    .option("-w, --workflow <workflow>", "Workflow id filter")
-    .option("--recent", "Only tasks in index.recent")
-    .option("--bootstrap-trigger <text>", "Create task if workflow slot is empty (requires -k and -w)")
-    .option("--doc-type <type>", "Doc type when bootstrapping a generate task")
-    .option("--force", "Replace existing active task when bootstrapping")
-    .option("--json", "JSON output")
-    .action(async (opts) => {
-    const status = opts.status
-        ? opts.status.split(",").map((s) => s.trim())
-        : undefined;
-    const bootstrapTrigger = opts.bootstrapTrigger;
-    if (bootstrapTrigger && (!opts.kind || !opts.workflow)) {
-        throw new Error("--bootstrap-trigger requires -k/--kind and -w/--workflow");
-    }
-    const result = await runTaskList({
-        root: resolve(opts.cwd ?? process.cwd()),
-        status: status?.length === 1 ? status[0] : status,
-        kind: opts.kind,
-        workflow: opts.workflow,
-        recentOnly: opts.recent,
-        bootstrap: bootstrapTrigger
-            ? {
-                kind: opts.kind,
-                workflow: opts.workflow,
-                trigger: bootstrapTrigger,
-                docType: opts.docType,
-                force: Boolean(opts.force),
-            }
-            : undefined,
-    });
-    if (opts.json)
-        console.log(JSON.stringify(result, null, 2));
-    else
-        console.log(formatTaskList(result));
-});
-task
-    .command("status")
-    .description("Show active workflow task slots (generate / resolve / import)")
-    .option("-C, --cwd <path>", "Project root", process.cwd())
-    .option("--json", "JSON output")
-    .action(async (opts) => {
-    const result = await runTaskStatus({
-        root: resolve(opts.cwd ?? process.cwd()),
-    });
-    if (opts.json)
-        console.log(JSON.stringify(result, null, 2));
-    else
-        console.log(formatTaskStatus(result));
-});
-task
-    .command("get <taskId>")
-    .description("Get full task state")
-    .option("-C, --cwd <path>", "Project root", process.cwd())
-    .option("--json", "JSON output")
-    .action(async (taskId, opts) => {
-    const result = await runTaskGet({
-        root: resolve(opts.cwd ?? process.cwd()),
-        taskId,
-    });
-    if (opts.json)
-        console.log(JSON.stringify(result, null, 2));
-    else
-        console.log(formatTaskGet(result));
-});
-task
-    .command("update <taskId>")
-    .description("Patch task state (pass --patch as JSON)")
-    .option("-C, --cwd <path>", "Project root", process.cwd())
-    .option("--patch <json>", "JSON patch object (TaskUpdatePatch)")
-    .option("--json", "JSON output")
-    .action(async (taskId, opts) => {
-    if (!opts.patch) {
-        throw new Error("--patch is required (JSON object)");
-    }
-    const patch = JSON.parse(opts.patch);
-    const result = await runTaskUpdate({
-        root: resolve(opts.cwd ?? process.cwd()),
-        taskId,
-        patch,
-    });
-    if (opts.json)
-        console.log(JSON.stringify(result, null, 2));
-    else
-        console.log(formatTaskUpdate(result));
-});
-task
-    .command("approve <taskId>")
-    .description("Approve the task plan and advance to the next step")
-    .option("-C, --cwd <path>", "Project root", process.cwd())
-    .option("--by <email>", "Approver email override (default: git user.email)")
-    .option("--username <name>", "Approver name override (default: git user.name)")
-    .option("--role <role>", "Actor role: user | client (default: user)")
-    .option("--plan <json>", "Plan JSON (StoredPlan) if not already set on task")
-    .option("--json", "JSON output")
-    .action(async (taskId, opts) => {
-    const result = await runTaskApprovePlan({
-        root: resolve(opts.cwd ?? process.cwd()),
-        taskId,
-        plan: opts.plan ? JSON.parse(opts.plan) : undefined,
-        by: opts.by,
-        username: opts.username,
-        role: opts.role,
-    });
-    if (opts.json)
-        console.log(JSON.stringify(result, null, 2));
-    else
-        console.log(formatTaskSimple("Approved plan for", result));
-});
-task
-    .command("approve-import-plan <taskId>")
-    .description("Import task: approve manifest plan after user yes (not task approve)")
-    .option("-C, --cwd <path>", "Project root", process.cwd())
-    .option("--plan <json>", "ImportPlan JSON (StoredPlan kind import) if not already on task")
-    .option("--json", "JSON output")
-    .action(async (taskId, opts) => {
-    const result = await runTaskApproveImportPlan({
-        root: resolve(opts.cwd ?? process.cwd()),
-        taskId,
-        plan: opts.plan ? JSON.parse(opts.plan) : undefined,
-    });
-    if (opts.json)
-        console.log(JSON.stringify(result, null, 2));
-    else
-        console.log(formatTaskSimple("Approved import manifest plan for", result));
-});
-task
-    .command("approve-adopt-plan <taskId>")
-    .description("Adopt task: approve migration move plan after user yes (not task approve)")
-    .option("-C, --cwd <path>", "Project root", process.cwd())
-    .option("--by <email>", "Approver identity")
-    .option("--plan <json>", "AdoptPlanSummary JSON (StoredPlan kind adopt) if not already on task")
-    .option("--json", "JSON output")
-    .action(async (taskId, opts) => {
-    const result = await runTaskApproveAdoptPlan({
-        root: resolve(opts.cwd ?? process.cwd()),
-        taskId,
-        plan: opts.plan ? JSON.parse(opts.plan) : undefined,
-        by: opts.by,
-    });
-    if (opts.json)
-        console.log(JSON.stringify(result, null, 2));
-    else
-        console.log(formatTaskSimple("Approved adopt migration plan for", result));
-});
-task
-    .command("approve-pack-design <taskId>")
-    .description("Import task: record approved pack design spec path after user yes")
-    .option("-C, --cwd <path>", "Project root", process.cwd())
-    .requiredOption("--design-spec <path>", "Relative path to approved pack design spec (e.g. docs/superpowers/specs/…-pack-design.md)")
-    .option("--json", "JSON output")
-    .action(async (taskId, opts) => {
-    const result = await runTaskApprovePackDesign({
-        root: resolve(opts.cwd ?? process.cwd()),
-        taskId,
-        designSpecPath: opts.designSpec,
-    });
-    if (opts.json)
-        console.log(JSON.stringify(result, null, 2));
-    else
-        console.log(formatTaskSimple("Approved pack design spec for", result));
-});
-task
-    .command("pause <taskId>")
-    .description("Pause a task")
-    .option("-C, --cwd <path>", "Project root", process.cwd())
-    .option("--json", "JSON output")
-    .action(async (taskId, opts) => {
-    const result = await runTaskPause({
-        root: resolve(opts.cwd ?? process.cwd()),
-        taskId,
-    });
-    if (opts.json)
-        console.log(JSON.stringify(result, null, 2));
-    else
-        console.log(formatTaskSimple("Paused", result));
-});
-task
-    .command("resume <taskId>")
-    .description("Resume a paused task (validates workspace and drift)")
-    .option("-C, --cwd <path>", "Project root", process.cwd())
-    .option("--json", "JSON output")
-    .action(async (taskId, opts) => {
-    const result = await runTaskResume({
-        root: resolve(opts.cwd ?? process.cwd()),
-        taskId,
-    });
-    if (opts.json)
-        console.log(JSON.stringify(result, null, 2));
-    else {
-        const lines = [
-            `Resume ${result.task.id} — canContinue: ${result.canContinue}`,
-            `  workspace: ${result.workspaceOk ? "ok" : "errors"}`,
-            `  drift:     ${result.drift.length} file(s)`,
-            `  stale:     ${result.staleContextIds.join(", ") || "none"}`,
-            `  next:      ${result.suggestedNext}`,
-        ];
-        if (result.drift.length > 0) {
-            for (const d of result.drift) {
-                lines.push(`    ${d.kind}: ${d.path}`);
-            }
-        }
-        console.log(lines.join("\n"));
-    }
-});
-task
-    .command("complete <taskId>")
-    .description("Mark a task complete")
-    .option("-C, --cwd <path>", "Project root", process.cwd())
-    .option("--summary <text>", "Completion summary")
-    .option("--json", "JSON output")
-    .action(async (taskId, opts) => {
-    const result = await runTaskComplete({
-        root: resolve(opts.cwd ?? process.cwd()),
-        taskId,
-        summary: opts.summary,
-    });
-    if (opts.json)
-        console.log(JSON.stringify(result, null, 2));
-    else
-        console.log(formatTaskSimple("Completed", result));
-});
-task
-    .command("record-wave <taskId> <waveId>")
-    .description("Record generate wave progress (e.g. wave-1 done with artifacts)")
-    .option("-C, --cwd <path>", "Project root", process.cwd())
-    .option("-s, --status <status>", "done | in-progress | blocked", "done")
-    .option("--artifacts <paths>", "Comma-separated doc paths written this wave")
-    .option("--blocker <text>", "Blocker message when status is blocked")
-    .option("--json", "JSON output")
-    .action(async (taskId, waveId, opts) => {
-    const result = await recordGenerateWaveProgress({
-        root: resolve(opts.cwd ?? process.cwd()),
-        taskId,
-        waveId,
-        status: opts.status,
-        artifacts: opts.artifacts
-            ? opts.artifacts.split(",").map((p) => p.trim()).filter(Boolean)
-            : undefined,
-        blocker: opts.blocker ?? null,
-    });
-    if (opts.json)
-        console.log(JSON.stringify(result, null, 2));
-    else
-        console.log(formatTaskUpdate(result));
-});
-task
-    .command("abandon <taskId>")
-    .description("Abandon a task")
-    .option("-C, --cwd <path>", "Project root", process.cwd())
-    .option("--reason <text>", "Why the task was abandoned")
-    .option("--json", "JSON output")
-    .action(async (taskId, opts) => {
-    const result = await runTaskAbandon({
-        root: resolve(opts.cwd ?? process.cwd()),
-        taskId,
-        reason: opts.reason,
-    });
-    if (opts.json)
-        console.log(JSON.stringify(result, null, 2));
-    else
-        console.log(formatTaskSimple("Abandoned", result));
+registerWorkCommands(program);
+registerTaskCommands(program);
+registerContractCommands(program);
+const LANG_DEPRECATION_WARNING = "[deprecated] lang — use `npx ai-spector contract translate` for queue operations; language config remains here for now\n";
+const lang = program
+    .command("lang")
+    .description("Manage project languages (deprecated — prefer contract translate for queue)")
+    .hook("preAction", () => {
+    process.stderr.write(LANG_DEPRECATION_WARNING);
 });
-const lang = program.command("lang").description("Manage project languages");
 lang
     .command("add <code>")
     .description("Add a language to the project (e.g. jp, vi)")
@@ -1514,12 +1228,14 @@ docops
     .option("--dry-run", "Print planned actions without writing files")
     .option("--repair", "Fill gaps in existing .docops/ without overwriting")
     .option("--templates-only", "Copy templates only")
+    .option("--from-docflow", "Split legacy docflow.config.json into docops.config.json + engine.json")
     .action(async (opts, cmd) => {
     await runDocopsMigrate({
         root: projectRootOpt(cmd),
         dryRun: opts.dryRun,
         repair: opts.repair,
         templatesOnly: opts.templatesOnly,
+        fromDocflow: opts.fromDocflow,
     });
 });
 const reviewSession = review.command("session").description("Persisted review session gate for sign-off");
@@ -1589,10 +1305,10 @@ prototype
 });
 prototype
     .command("auth")
-    .description("Configure HTTP basic auth (credentials in prototype/config.json, .htpasswd under prototype/)")
+    .description("Configure HTTP basic auth (credentials in .docops/prototype/config.json, .htpasswd under prototype/)")
     .option("--username <name>", "Basic auth username")
     .option("--password <secret>", "Basic auth password")
-    .option("--from-config", "Regenerate .htpasswd from stored prototype/config.json basicAuth")
+    .option("--from-config", "Regenerate .htpasswd from stored .docops/prototype/config.json basicAuth")
     .action(async (opts, cmd) => {
     await runPrototypeAuth({
         root: projectRootOpt(cmd),
@@ -1643,7 +1359,7 @@ prototype
 });
 prototype
     .command("map")
-    .description("Build prototype/screen-map.json from basic-design Screen Index + prototype/path-map.json (hosted / external prototypes)")
+    .description("Build .docops/prototype/screen-map.json from basic-design Screen Index + prototype/path-map.json (hosted / external prototypes)")
     .option("--from <path>", "Path map input (default: prototype/path-map.json)")
     .option("--theme <name>", "Theme name stored in screen-map.json")
     .option("--review-host <url>", "POC host for reviewUrl fields (overrides path-map.json)")