slopflow 0.1.0 → 0.2.1

package/README.md

@@ -10,6 +10,9 @@ The first vertical slice provides:
 slopflow init
 slopflow status
 slopflow start <issue-id>
+slopflow pause <issue-id> --reason <text>
+slopflow resume <issue-id>
+slopflow cancel <issue-id> --reason <text>
 slopflow test <issue-id> --name <gate> -- <command...>
 slopflow review <issue-id>
 slopflow complete <issue-id>
@@ -19,12 +22,121 @@ slopflow complete <issue-id>
 
 Slopflow requires Node.js 24 or newer.
 
+## CLI output contract
+
+Slopflow's default command output is an agent-facing, TOON-like key-block format: a named block followed by compact `key: value` fields and a concrete `next-step` or `help[...]` hint when useful.
+
+Example success output:
+
+```text
+status:
+  state: initialized
+  repo: owner/name
+  issue_tracker: github
+  vcs: jj
+  artifact-root: .slopflow/work
+  next-step: slopflow start <issue-id>
+```
+
+Example structured error output:
+
+```text
+error:
+  status: blocked
+  message: <short reason>
+  hint: <optional next action>
+```
+
+Canonical Slopflow status, gate, and error output is written to stdout so agents can parse a single structured stream. Stderr is reserved for debug output and wrapped-command logs; `slopflow test` captures wrapped command stdout/stderr in evidence logs under `.slopflow/work/<issue-id>/evidence/logs/`.
+
+Use `--json` only when scripts or integrations need machine JSON output. The default remains compact key-block output for agents. Initial JSON modes are:
+
+```bash
+slopflow status --json
+slopflow doctor --json
+```
+
+Errors with `--json` return structured JSON error objects:
+
+```json
+{
+  "error": {
+    "status": "blocked",
+    "message": "Slopflow machine config is missing.",
+    "hint": "Run `slopflow init` first."
+  }
+}
+```
+
+### Doctor output and severity
+
+`slopflow doctor` is a read-only setup diagnostic. It uses the same compact key-block format and reports a top-level status plus grouped severities:
+
+```text
+doctor:
+  status: warn
+  core: passed
+  project-docs: passed
+  recommended: warn
+  failed-count: 0
+  warning-count: 1
+  next-step: run npx -y gh-axi --help when GitHub AXI operations are needed
+checks[...]:
+  core.node: passed node v26.1.0 satisfies >=24
+  core.jj: passed jj executable found
+  recommended.gh-axi: warn unchecked; run npx -y gh-axi --help when GitHub AXI operations are needed
+```
+
+Severity rules:
+
+- `passed` — all core, project-doc, and recommended checks passed.
+- `warn` — core checks passed, but at least one project-doc or recommended check is missing, optional, or unchecked.
+- `failed` — at least one core readiness check failed; the command exits with code `2`.
+
+Doctor detail strings are intentionally bounded and summarized so setup diagnostics stay agent-readable instead of dumping full command output.
+
 Initialize Slopflow machine config in a Jujutsu-backed GitHub repo:
 
 ```bash
 slopflow init
 ```
 
+Preview minimal project-local setup without writing files:
+
+```bash
+slopflow install minimal
+```
+
+Apply minimal project-local setup after reviewing the plan:
+
+```bash
+slopflow install minimal --yes
+```
+
+`install minimal` only writes project-local Slopflow files such as `.slopflow/config.json` and `.slopflow/work/`. It does not mutate global agent configuration, install packages globally, push, publish, create PRs, close issues, or merge changes. Existing incompatible config blocks unless rerun with explicit `--force`.
+
+Preview recommended project-local setup without writing files:
+
+```bash
+slopflow install recommended
+```
+
+Apply recommended project-local setup after reviewing the plan:
+
+```bash
+slopflow install recommended --yes
+```
+
+`install recommended` applies the minimal Slopflow setup and writes a project-local `.pi/slopflow-packages.json` manifest with suggested skill installation commands. It does not run those commands automatically and does not mutate global Claude, Pi, Cursor, or other agent harness configuration.
+
+Validate repository-distributed Slopflow skills without modifying files:
+
+```bash
+slopflow skill lint
+```
+
+`skill lint` checks that portable skills avoid shell interpolation, live skills use read-only interpolation, Slopflow safety rules are present, and setup templates include OKF frontmatter where applicable.
+
 Inspect current Slopflow state:
 
 ```bash
@@ -49,6 +161,16 @@ next-steps.md
 
 It does not create placeholder evidence, review, or completion files.
 
+Pause, resume, or cancel local issue work without running gates or mutating Jujutsu history:
+
+```bash
+slopflow pause 2 --reason "waiting for external review"
+slopflow resume 2
+slopflow cancel 2 --reason "superseded by another issue"
+```
+
+Lifecycle commands preserve the work directory and record local status only. They do not push, close issues, publish, delete evidence, or abandon Jujutsu changes.
+
 Capture command-based quality evidence for started issue work:
 
 ```bash
@@ -76,6 +198,20 @@ slopflow complete 2
 
 ## Agent skills
 
+For a new project, install and run the setup skill before the Slopflow execution skill. It records the repository's issue tracker, triage labels, and domain-documentation layout so later engineering skills have the local context they expect:
+
+```bash
+npx skills add aivv73/slopflow --skill setup-slopflow-skills
+```
+
+If your agent runtime supports Claude-compatible skill interpolation, use the live setup variant instead:
+
+```bash
+npx skills add aivv73/slopflow --skill setup-slopflow-skills-live
+```
+
+The setup skills create OKF-compatible `docs/agents/*.md` concept documents and update the repo's `AGENTS.md` or `CLAUDE.md` instructions. They are adapted from Matt Pocock's engineering skills (https://github.com/mattpocock/skills/) for Slopflow onboarding. Run one of them first in a newly onboarded project, then initialize Slopflow and use the execution skill.
+
 Install the portable Slopflow skill:
 
 ```bash
@@ -88,13 +224,15 @@ Install the live-context Slopflow skill for Claude Code or Pi with `pi-skill-int
 npx skills add aivv73/slopflow --skill slopflow-live
 ```
 
-The portable skill does not execute shell commands during rendering. The live skill uses Claude-compatible read-only shell interpolation to inject current Slopflow and Jujutsu context.
+The portable skills do not execute shell commands during rendering. The live skills use Claude-compatible read-only shell interpolation to inject setup or Slopflow context.
 
 Agent skills are installed separately through Vercel Skills. The Slopflow npm package distributes the CLI and does not install skills into Claude, Pi, Cursor, or other agent harness directories.
 
 ## Install
 
-Once Slopflow is published to npm, install the CLI globally:
+Slopflow is published on npm: https://www.npmjs.com/package/slopflow
+
+Install the CLI globally:
 
 ```bash
 npm install -g slopflow

package/dist/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { spawnSync } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, statSync, writeFileSync } from "node:fs";
 import { readdir } from "node:fs/promises";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -11,20 +11,39 @@ const REVIEW_DIFF_LIMIT = 50_000;
 class SlopflowError extends Error {
     hint;
     code;
-    constructor(message, hint, code = 1) {
+    details;
+    constructor(message, hint, code = 1, details = {}) {
         super(message);
         this.hint = hint;
         this.code = code;
+        this.details = details;
     }
 }
 export async function main(argv = process.argv.slice(2)) {
+    const wantsJson = argv.includes("--json");
     try {
         const [command, ...args] = argv;
+        if (!command) {
+            return await homeCommand();
+        }
+        if (command === "--help" || command === "-h") {
+            printHelp();
+            return 0;
+        }
         if (command === "init") {
             return initCommand({ force: args.includes("--force") });
         }
         if (command === "status") {
-            return await statusCommand();
+            return await statusCommand({ json: args.includes("--json") });
+        }
+        if (command === "doctor") {
+            return doctorCommand({ json: args.includes("--json") });
+        }
+        if (command === "install") {
+            return installCommand(args);
+        }
+        if (command === "skill") {
+            return skillCommand(args);
         }
         if (command === "start") {
             return startCommand(args[0]);
@@ -32,27 +51,406 @@ export async function main(argv = process.argv.slice(2)) {
         if (command === "test") {
             return testCommand(args);
         }
+        if (command === "pause") {
+            return lifecycleCommand("pause", args);
+        }
+        if (command === "resume") {
+            return lifecycleCommand("resume", args);
+        }
+        if (command === "cancel") {
+            return lifecycleCommand("cancel", args);
+        }
         if (command === "review") {
             return reviewCommand(args[0]);
         }
         if (command === "complete") {
             return completeCommand(args[0]);
         }
-        printHelp();
-        return 0;
+        throw new SlopflowError(`Unknown command: ${command}`, "Run `slopflow --help`.", 2);
     }
     catch (error) {
         if (error instanceof SlopflowError) {
-            printBlock("error", {
+            const payload = {
                 status: "blocked",
                 message: error.message,
+                ...error.details,
                 ...(error.hint ? { hint: error.hint } : {}),
-            }, process.stderr);
+            };
+            if (wantsJson)
+                printJson({ error: payload });
+            else
+                printBlock("error", payload);
             return error.code;
         }
         throw error;
     }
 }
+function doctorCommand({ json = false } = {}) {
+    const checks = [];
+    checks.push({ name: "core.slopflow", status: "passed", detail: "cli running" });
+    const root = findRepoRoot(process.cwd());
+    const nodeEngine = root ? readPackageNodeEngine(root) : null;
+    const nodeSatisfies = nodeEngine ? nodeVersionSatisfies(process.versions.node, nodeEngine) : true;
+    checks.push({
+        name: "core.node",
+        status: nodeSatisfies ? "passed" : "failed",
+        detail: nodeEngine ? `node v${process.versions.node} satisfies ${nodeEngine}` : `node v${process.versions.node}; package.json engines.node not found`,
+    });
+    const jjPresent = commandExists("jj");
+    checks.push({
+        name: "core.jj",
+        status: jjPresent ? "passed" : "failed",
+        detail: jjPresent ? "jj executable found" : "jj executable missing",
+    });
+    checks.push({
+        name: "core.repository",
+        status: root ? "passed" : "failed",
+        detail: root ? `root ${relativeToCwd(root)}` : "no .jj or .git repository root found",
+    });
+    const jjRepo = root ? existsSync(join(root, ".jj")) : false;
+    checks.push({
+        name: "core.jj-repo",
+        status: jjRepo ? "passed" : "failed",
+        detail: jjRepo ? ".jj present" : "Jujutsu repository not detected",
+    });
+    const configPath = root ? join(root, ".slopflow", "config.json") : "";
+    const configExists = Boolean(root && existsSync(configPath));
+    checks.push({
+        name: "core.config",
+        status: configExists ? "passed" : "failed",
+        detail: configExists ? relativeToCwd(configPath) : ".slopflow/config.json missing",
+    });
+    let artifactRoot = DEFAULT_ARTIFACT_ROOT;
+    if (root && configExists) {
+        try {
+            artifactRoot = readMachineConfig(root).artifact_root;
+        }
+        catch {
+            artifactRoot = DEFAULT_ARTIFACT_ROOT;
+        }
+    }
+    const workRoot = root ? join(root, artifactRoot) : "";
+    const workRootExists = Boolean(root && existsSync(workRoot));
+    checks.push({
+        name: "core.work-root",
+        status: workRootExists ? "passed" : "failed",
+        detail: workRootExists ? relativeToCwd(workRoot) : `${artifactRoot} missing`,
+    });
+    for (const [name, path] of [
+        ["project-docs.issue-tracker", "docs/agents/issue-tracker.md"],
+        ["project-docs.triage-labels", "docs/agents/triage-labels.md"],
+        ["project-docs.domain", "docs/agents/domain.md"],
+        ["project-docs.context", "CONTEXT.md"],
+        ["project-docs.adr", "docs/adr"],
+    ]) {
+        const present = Boolean(root && existsSync(join(root, path)));
+        checks.push({ name, status: present ? "passed" : "warn", detail: present ? path : `${path} missing` });
+    }
+    const ghPresent = commandExists("gh");
+    checks.push({
+        name: "recommended.gh",
+        status: ghPresent ? "passed" : "warn",
+        detail: doctorDetail(ghPresent ? "gh executable found" : "gh executable missing; GitHub issue start may fail"),
+    });
+    const ghAxiPresent = commandExists("gh-axi");
+    checks.push({
+        name: "recommended.gh-axi",
+        status: ghAxiPresent ? "passed" : "warn",
+        detail: doctorDetail(ghAxiPresent ? "gh-axi executable found" : "unchecked; run npx -y gh-axi --help when GitHub AXI operations are needed"),
+    });
+    const failedCount = checks.filter((check) => check.status === "failed").length;
+    const warningCount = checks.filter((check) => check.status === "warn").length;
+    const status = failedCount > 0 ? "failed" : warningCount > 0 ? "warn" : "passed";
+    const coreStatus = checks.some((check) => check.name.startsWith("core.") && check.status === "failed") ? "failed" : "passed";
+    const projectDocsStatus = groupStatus(checks, "project-docs.");
+    const recommendedStatus = groupStatus(checks, "recommended.");
+    const doctor = {
+        status,
+        core: coreStatus,
+        "project-docs": projectDocsStatus,
+        recommended: recommendedStatus,
+        "failed-count": failedCount,
+        "warning-count": warningCount,
+        "next-step": nextStepForDoctor(status, checks),
+    };
+    const checksOutput = Object.fromEntries(checks.map((check) => [check.name, `${check.status} ${check.detail}`]));
+    if (json) {
+        printJson({ doctor, checks: checksOutput });
+    }
+    else {
+        printBlock("doctor", doctor);
+        printBlock(`checks[${checks.length}]`, checksOutput);
+    }
+    return failedCount > 0 ? 2 : 0;
+}
+function groupStatus(checks, prefix) {
+    const group = checks.filter((check) => check.name.startsWith(prefix));
+    if (group.some((check) => check.status === "failed"))
+        return "failed";
+    if (group.some((check) => check.status === "warn"))
+        return "warn";
+    return "passed";
+}
+function nextStepForDoctor(status, checks) {
+    if (status === "passed")
+        return "slopflow start <issue-id>";
+    const firstFailed = checks.find((check) => check.status === "failed");
+    if (firstFailed?.name === "core.config")
+        return "slopflow init";
+    if (firstFailed?.name === "core.work-root")
+        return "slopflow init";
+    if (firstFailed?.name === "core.jj")
+        return "install jj";
+    if (firstFailed?.name === "core.repository" || firstFailed?.name === "core.jj-repo")
+        return "run inside a Jujutsu repository";
+    const firstWarn = checks.find((check) => check.status === "warn");
+    if (firstWarn?.name === "recommended.gh")
+        return "install gh or continue if GitHub start is not needed";
+    if (firstWarn?.name === "recommended.gh-axi")
+        return "run npx -y gh-axi --help when GitHub AXI operations are needed";
+    return "inspect doctor checks";
+}
+function doctorDetail(value, limit = 160) {
+    const normalized = value.replace(/\s+/g, " ").trim();
+    return normalized.length > limit ? `${normalized.slice(0, limit)}...` : normalized;
+}
+function installCommand(args) {
+    const [profile, ...flags] = args;
+    if (profile !== "minimal" && profile !== "recommended") {
+        throw new SlopflowError("Unsupported install profile.", "Run `slopflow install minimal` or `slopflow install recommended`.", 2);
+    }
+    const yes = flags.includes("--yes");
+    const force = flags.includes("--force");
+    const repo = discoverRepoContext(process.cwd());
+    const configPath = join(repo.root, ".slopflow", "config.json");
+    const desired = desiredConfig(repo.githubRepo);
+    const workPath = join(repo.root, desired.artifact_root);
+    const configExists = existsSync(configPath);
+    const workExists = existsSync(workPath);
+    const manifestPath = join(repo.root, ".pi", "slopflow-packages.json");
+    const manifestExists = existsSync(manifestPath);
+    let configAction = configExists ? "preserve" : "create";
+    if (configExists) {
+        const existing = readJson(configPath);
+        if (stableStringify(existing) !== stableStringify(desired)) {
+            if (!force) {
+                throw new SlopflowError("Existing .slopflow/config.json differs from detected config.", "Inspect it or rerun with `slopflow install minimal --yes --force` to refresh project-local config.", 2);
+            }
+            configAction = "refresh";
+        }
+    }
+    const workAction = workExists ? "preserve" : "create";
+    const manifestAction = manifestExists ? "preserve" : "create";
+    if (!yes) {
+        printBlock("install", {
+            status: "planned",
+            profile,
+            mode: "dry-run",
+            repo: repo.githubRepo,
+            config: relativeToCwd(configPath),
+            "config-action": configAction,
+            "work-root": desired.artifact_root,
+            "work-root-action": workAction,
+            ...(profile === "recommended" ? {
+                manifest: relativeToCwd(manifestPath),
+                "manifest-action": manifestAction,
+                "suggested-command": "npx skills add aivv73/slopflow --skill slopflow-live",
+            } : {}),
+            writes: "none",
+            "next-step": `slopflow install ${profile} --yes`,
+        });
+        return 0;
+    }
+    if (configAction !== "preserve") {
+        mkdirSync(dirname(configPath), { recursive: true });
+        writeJson(configPath, desired);
+    }
+    mkdirSync(workPath, { recursive: true });
+    if (profile === "recommended" && manifestAction !== "preserve") {
+        mkdirSync(dirname(manifestPath), { recursive: true });
+        writeJson(manifestPath, buildRecommendedInstallManifest());
+    }
+    printBlock("install", {
+        status: configAction === "preserve" && workAction === "preserve" && (profile === "minimal" || manifestAction === "preserve") ? "unchanged" : "applied",
+        profile,
+        mode: "apply",
+        repo: repo.githubRepo,
+        config: relativeToCwd(configPath),
+        "config-action": configAction,
+        "work-root": desired.artifact_root,
+        "work-root-action": workAction,
+        ...(profile === "recommended" ? {
+            manifest: relativeToCwd(manifestPath),
+            "manifest-action": manifestAction,
+            "suggested-command": "npx skills add aivv73/slopflow --skill slopflow-live",
+        } : {}),
+        writes: "project-local",
+        "next-step": "slopflow doctor",
+    });
+    return 0;
+}
+function buildRecommendedInstallManifest() {
+    return {
+        schema_version: 1,
+        profile: "recommended",
+        generated_by: "slopflow install recommended",
+        project_local_only: true,
+        suggested_commands: [
+            "npx skills add aivv73/slopflow --skill setup-slopflow-skills-live",
+            "npx skills add aivv73/slopflow --skill slopflow-live",
+            "npx skills add aivv73/slopflow --skill slopflow",
+        ],
+        notes: [
+            "Slopflow does not run these commands automatically.",
+            "Review agent harness documentation before installing global or user-level integrations.",
+        ],
+    };
+}
+function skillCommand(args) {
+    const [subcommand] = args;
+    if (subcommand !== "lint") {
+        throw new SlopflowError("Unsupported skill command.", "Run `slopflow skill lint`.", 2);
+    }
+    const root = findRepoRoot(process.cwd()) ?? process.cwd();
+    const skillsDir = join(root, "skills");
+    const checks = lintSkills(skillsDir);
+    const failedCount = checks.filter((check) => check.status === "failed").length;
+    printBlock("skill-lint", {
+        status: failedCount > 0 ? "failed" : "passed",
+        "skills-dir": relativeToCwd(skillsDir),
+        "failed-count": failedCount,
+        "check-count": checks.length,
+        "next-step": failedCount > 0 ? "fix failing skill checks" : "no skill lint action required",
+    });
+    printBlock(`checks[${checks.length}]`, Object.fromEntries(checks.map((check) => [check.name, `${check.status} ${check.detail}`])));
+    return failedCount > 0 ? 2 : 0;
+}
+function lintSkills(skillsDir) {
+    const checks = [];
+    const portablePath = join(skillsDir, "slopflow", "SKILL.md");
+    const livePath = join(skillsDir, "slopflow-live", "SKILL.md");
+    const portable = readOptionalText(portablePath);
+    const live = readOptionalText(livePath);
+    checks.push({ name: "slopflow.exists", status: portable ? "passed" : "failed", detail: portable ? "skills/slopflow/SKILL.md" : "missing skills/slopflow/SKILL.md" });
+    if (portable) {
+        checks.push({ name: "slopflow.no-interpolation", status: /!`/.test(portable) ? "failed" : "passed", detail: /!`/.test(portable) ? "portable skill contains shell interpolation" : "no shell interpolation" });
+        checks.push(skillTextCheck("slopflow.canonical", portable, /artifacts are canonical/i, "states CLI/artifacts are canonical"));
+        checks.push(skillTextCheck("slopflow.no-fabrication", portable, /Do not manually fabricate/i, "forbids fabricated artifacts"));
+        checks.push(skillTextCheck("slopflow.no-push-without-request", portable, /Do not push, merge, publish, create a pull request, or close an issue unless/i, "forbids push/merge/publish/PR/close unless requested"));
+    }
+    checks.push({ name: "slopflow-live.exists", status: live ? "passed" : "failed", detail: live ? "skills/slopflow-live/SKILL.md" : "missing skills/slopflow-live/SKILL.md" });
+    if (live) {
+        checks.push({ name: "slopflow-live.read-only-interpolation", status: liveInterpolationIsReadOnly(live) ? "passed" : "failed", detail: liveInterpolationIsReadOnly(live) ? "interpolation commands look read-only" : "interpolation includes mutating command" });
+        checks.push(skillTextCheck("slopflow-live.canonical", live, /artifacts are canonical/i, "states CLI/artifacts are canonical"));
+        checks.push(skillTextCheck("slopflow-live.no-fabrication", live, /Do not manually fabricate/i, "forbids fabricated artifacts"));
+        checks.push(skillTextCheck("slopflow-live.no-push-without-request", live, /Do not push, merge, publish, create a pull request, or close an issue unless/i, "forbids push/merge/publish/PR/close unless requested"));
+    }
+    for (const template of setupTemplateFiles(skillsDir)) {
+        const relativePath = relative(skillsDir, template);
+        const content = readOptionalText(template) ?? "";
+        const ok = /^---\n[\s\S]+?\n---\n/.test(content) && /^type:\s*\S.+$/m.test(content.match(/^---\n([\s\S]+?)\n---\n/)?.[1] ?? "");
+        checks.push({ name: `setup-template.${relativePath}`, status: ok ? "passed" : "failed", detail: ok ? "OKF frontmatter with type" : "missing OKF frontmatter type" });
+    }
+    return checks;
+}
+function skillTextCheck(name, content, pattern, passedDetail) {
+    return { name, status: pattern.test(content) ? "passed" : "failed", detail: pattern.test(content) ? passedDetail : `missing ${passedDetail}` };
+}
+function liveInterpolationIsReadOnly(content) {
+    const commands = [...content.matchAll(/!`([^`]+)`/g)].map((match) => match[1] ?? "");
+    return commands.every((command) => !/\b(slopflow\s+(init|start|test|review|complete|pause|resume|cancel)|jj\s+(new|desc|rebase|git\s+push)|gh\s+(issue|pr)\s+(create|edit|close|comment)|rm\s+-|write|curl\s+-X\s*(POST|PUT|PATCH|DELETE))\b/i.test(command));
+}
+function setupTemplateFiles(skillsDir) {
+    const result = [];
+    for (const setupName of ["setup-slopflow-skills", "setup-slopflow-skills-live"]) {
+        const dir = join(skillsDir, setupName);
+        if (!existsSync(dir))
+            continue;
+        for (const entry of readdirSyncSafe(dir)) {
+            const path = join(dir, entry);
+            if (entry === "SKILL.md" || !entry.endsWith(".md") || !statSync(path).isFile())
+                continue;
+            result.push(path);
+        }
+    }
+    return result.sort();
+}
+function readOptionalText(path) {
+    return existsSync(path) ? readFileSync(path, "utf8") : null;
+}
+function readdirSyncSafe(path) {
+    try {
+        return existsSync(path) ? readdirSync(path) : [];
+    }
+    catch {
+        return [];
+    }
+}
+function readPackageNodeEngine(root) {
+    const packagePath = join(root, "package.json");
+    if (!existsSync(packagePath))
+        return null;
+    try {
+        const packageJson = readJson(packagePath);
+        return typeof packageJson.engines?.node === "string" ? packageJson.engines.node : null;
+    }
+    catch {
+        return null;
+    }
+}
+function nodeVersionSatisfies(version, engine) {
+    const major = Number(version.split(".")[0] ?? "0");
+    const minimumMajor = engine.match(/>=\s*(\d+)/)?.[1];
+    if (minimumMajor)
+        return major >= Number(minimumMajor);
+    return true;
+}
+async function homeCommand() {
+    const bin = process.argv[1] ? relativeToCwd(realpathSync(process.argv[1])) : "slopflow";
+    const description = "Controlled issue execution for AI coding agents.";
+    const root = findRepoRoot(process.cwd());
+    if (!root) {
+        printBlock("slopflow", {
+            bin,
+            description,
+            state: "no-repository",
+            "next-step": "cd to a Slopflow repository or run `slopflow --help`",
+        });
+        return 0;
+    }
+    const configPath = join(root, ".slopflow", "config.json");
+    if (!existsSync(configPath)) {
+        printBlock("slopflow", {
+            bin,
+            description,
+            state: "uninitialized",
+            "repo-root": relativeToCwd(root),
+            vcs: existsSync(join(root, ".jj")) ? "jj" : "unknown",
+            "next-step": "slopflow init",
+        });
+        return 0;
+    }
+    const config = readMachineConfig(root);
+    const artifactRoot = String(config.artifact_root ?? DEFAULT_ARTIFACT_ROOT);
+    const workRoot = join(root, artifactRoot);
+    const workCounts = await countWorkDirsByStatus(workRoot);
+    printBlock("slopflow", {
+        bin,
+        description,
+        state: "initialized",
+        repo: config.issue_tracker.repo,
+        issue_tracker: config.issue_tracker.type,
+        vcs: config.vcs.type,
+        "artifact-root": artifactRoot,
+        "current-jj-change": readCurrentJjChange(root),
+        "active-work-count": workCounts.active,
+        "paused-work-count": workCounts.paused,
+        "cancelled-work-count": workCounts.cancelled,
+        "complete-work-count": workCounts.complete,
+        "next-step": "slopflow start <issue-id>",
+    });
+    return 0;
+}
 function completeCommand(issueId) {
     if (!issueId) {
         throw new SlopflowError("Missing issue id.", "Run `slopflow complete <issue-id>`.", 2);
@@ -70,6 +468,9 @@ function completeCommand(issueId) {
     const workStatus = readWorkStatus(workDir, issueId, "complete");
     const issue = workStatus.issue;
     const issueText = `${issue.provider}:${issue.repo}#${issue.number}`;
+    if (workStatus.status === "cancelled") {
+        return completeBlocked(issueText, "issue work is cancelled", `inspect ${relativeToCwd(join(workDir, "cancel-note.md"))} or start new work`, workDir);
+    }
     const contractPath = join(workDir, "contract.md");
     if (!existsSync(contractPath)) {
         return completeBlocked(issueText, "missing contract.md", "restore contract.md or rerun slopflow start", workDir);
@@ -294,16 +695,151 @@ function testCommand(args) {
     });
     return exitCode;
 }
+function lifecycleCommand(action, args) {
+    const issueId = args[0];
+    const reason = action === "resume" ? undefined : parseReasonArg(args.slice(1), action);
+    const { root, workDir, workStatus, statusPath } = readLifecycleContext(issueId, action);
+    const issue = workStatus.issue;
+    const issueText = `${issue.provider}:${issue.repo}#${issue.number}`;
+    const now = new Date().toISOString();
+    if (action === "pause") {
+        if (workStatus.status === "cancelled") {
+            throw new SlopflowError("Cancelled issue work cannot be paused.", `Inspect ${relativeToCwd(join(workDir, "cancel-note.md"))}.`, 2);
+        }
+        if (workStatus.status === "complete") {
+            throw new SlopflowError("Complete issue work cannot be paused.", `Inspect ${relativeToCwd(join(workDir, "completion-note.md"))}.`, 2);
+        }
+        const pauseNotePath = join(workDir, "pause-note.md");
+        writeFileSync(pauseNotePath, buildLifecycleNote("Pause", issueText, reason, now), "utf8");
+        writeJson(statusPath, { ...workStatus, status: "paused", paused_at: now, pause_reason: reason });
+        printBlock("pause", {
+            status: "paused",
+            issue: issueText,
+            "pause-note": relativeToCwd(pauseNotePath),
+            "next-step": `slopflow resume ${issueId}`,
+        });
+        return 0;
+    }
+    if (action === "cancel") {
+        if (workStatus.status === "complete") {
+            throw new SlopflowError("Complete issue work cannot be cancelled.", `Inspect ${relativeToCwd(join(workDir, "completion-note.md"))}.`, 2);
+        }
+        const cancelNotePath = join(workDir, "cancel-note.md");
+        writeFileSync(cancelNotePath, buildLifecycleNote("Cancel", issueText, reason, now), "utf8");
+        writeJson(statusPath, { ...workStatus, status: "cancelled", cancelled_at: now, cancel_reason: reason });
+        printBlock("cancel", {
+            status: "cancelled",
+            issue: issueText,
+            "cancel-note": relativeToCwd(cancelNotePath),
+            artifacts: "preserved",
+            "next-step": "inspect artifacts or manually abandon related VCS work if desired",
+        });
+        return 0;
+    }
+    if (workStatus.status === "cancelled") {
+        throw new SlopflowError("Cancelled issue work cannot be resumed.", `Inspect ${relativeToCwd(join(workDir, "cancel-note.md"))}.`, 2);
+    }
+    const wasPaused = workStatus.status === "paused";
+    if (wasPaused) {
+        writeJson(statusPath, { ...workStatus, status: "active", resumed_at: now });
+    }
+    const testsSummary = summarizeLatestTests(workDir);
+    const reviewStatus = summarizeReviewVerdict(workDir);
+    const completionStatus = existsSync(join(workDir, "completion-note.md")) || workStatus.status === "complete" ? "complete" : "incomplete";
+    printBlock("resume", {
+        status: wasPaused ? "active" : String(workStatus.status ?? "active"),
+        issue: issueText,
+        contract: relativeToCwd(join(workDir, "contract.md")),
+        tests: testsSummary,
+        review: reviewStatus,
+        completion: completionStatus,
+        "current-jj-change": readCurrentJjChange(root),
+        "next-step": nextStepForWork(issueId, workDir, reviewStatus, completionStatus),
+    });
+    return 0;
+}
+function readLifecycleContext(issueId, command) {
+    if (!issueId) {
+        throw new SlopflowError("Missing issue id.", `Run \`slopflow ${command} <issue-id>${command === "resume" ? "" : " --reason <text>"}\`.`, 2);
+    }
+    if (!/^\d+$/.test(issueId)) {
+        throw new SlopflowError("Issue id must be a plain number for the configured repository.", undefined, 2);
+    }
+    const root = findRepoRoot(process.cwd());
+    if (!root) {
+        throw new SlopflowError("Could not find a repository root.", "Run Slopflow inside an initialized repository.", 2);
+    }
+    const config = readMachineConfig(root);
+    const workDir = join(root, config.artifact_root, issueId);
+    const statusPath = join(workDir, "status.json");
+    return { root, workDir, statusPath, workStatus: readWorkStatus(workDir, issueId, command) };
+}
+function parseReasonArg(args, command) {
+    const reasonIndex = args.indexOf("--reason");
+    const reason = reasonIndex >= 0 ? args[reasonIndex + 1] : undefined;
+    if (!reason || reason.trim().length === 0) {
+        throw new SlopflowError("Missing required `--reason <text>`.", `Run \`slopflow ${command} <issue-id> --reason <text>\`.`, 2);
+    }
+    return reason.trim();
+}
+function buildLifecycleNote(kind, issue, reason, timestamp) {
+    const verb = kind === "Pause" ? "Paused" : "Cancelled";
+    return `# ${kind} Note\n\n` +
+        `Issue: ${issue}\n\n` +
+        `${verb} at: ${timestamp}\n\n` +
+        `## Reason\n\n${reason}\n`;
+}
+function summarizeLatestTests(workDir) {
+    const testsPath = join(workDir, "evidence", "tests.json");
+    if (!existsSync(testsPath))
+        return "missing";
+    const evidence = readTestEvidence(testsPath);
+    const latest = Object.entries(evidence.latest);
+    if (latest.length === 0)
+        return "missing";
+    return latest.map(([name, gate]) => `${name}:${gate.status}`).join(",");
+}
+function summarizeReviewVerdict(workDir) {
+    const reviewPath = join(workDir, "review.json");
+    if (!existsSync(reviewPath))
+        return "missing";
+    const validation = readAndValidateReviewVerdict(reviewPath);
+    return validation.ok ? validation.verdict.verdict : "invalid";
+}
+function nextStepForWork(issueId, workDir, reviewStatus, completionStatus) {
+    if (completionStatus === "complete")
+        return "no local action required";
+    if (summarizeLatestTests(workDir) === "missing")
+        return `slopflow test ${issueId} --name <gate> -- <command>`;
+    if (reviewStatus === "missing" || reviewStatus === "invalid")
+        return `slopflow review ${issueId}`;
+    if (reviewStatus === "changes-requested")
+        return "address required changes";
+    return `slopflow complete ${issueId}`;
+}
 function readWorkStatus(workDir, issueId, command) {
     const workStatusPath = join(workDir, "status.json");
     if (!existsSync(workStatusPath)) {
-        throw new SlopflowError(`Issue work status not found for #${issueId}.`, `Run \`slopflow start ${issueId}\` before ${command === "test" ? "capturing test evidence" : command === "review" ? "preparing review" : "completing work"}.`, 2);
+        throw new SlopflowError(`Issue work status not found for #${issueId}.`, `Run \`slopflow start ${issueId}\` before ${workStatusCommandPhrase(command)}.`, 2);
     }
     const workStatus = readJson(workStatusPath);
     if (!workStatus.issue) {
         throw new SlopflowError(`Issue work status is missing issue metadata for #${issueId}.`, "Inspect the work directory before retrying.", 2);
     }
-    return { issue: workStatus.issue };
+    return workStatus;
+}
+function workStatusCommandPhrase(command) {
+    if (command === "test")
+        return "capturing test evidence";
+    if (command === "review")
+        return "preparing review";
+    if (command === "complete")
+        return "completing work";
+    if (command === "pause")
+        return "pausing work";
+    if (command === "resume")
+        return "resuming work";
+    return "cancelling work";
 }
 function parseTestArgs(args) {
     const issueId = args[0];
@@ -419,7 +955,7 @@ function initCommand({ force }) {
     });
     return 0;
 }
-async function statusCommand() {
+async function statusCommand({ json = false } = {}) {
     const root = findRepoRoot(process.cwd());
     if (!root) {
         throw new SlopflowError("Could not find a repository root.", "Run Slopflow inside a Jujutsu repository.", 2);
@@ -427,18 +963,25 @@ async function statusCommand() {
     const config = readMachineConfig(root);
     const artifactRoot = String(config.artifact_root ?? DEFAULT_ARTIFACT_ROOT);
     const workRoot = join(root, artifactRoot);
-    const activeWorkCount = await countWorkDirs(workRoot);
+    const workCounts = await countWorkDirsByStatus(workRoot);
     const currentJjChange = readCurrentJjChange(root);
-    printBlock("status", {
+    const status = {
         state: "initialized",
         repo: config.issue_tracker.repo,
         issue_tracker: config.issue_tracker.type,
         vcs: config.vcs.type,
         "artifact-root": artifactRoot,
         "current-jj-change": currentJjChange,
-        "active-work-count": activeWorkCount,
+        "active-work-count": workCounts.active,
+        "paused-work-count": workCounts.paused,
+        "cancelled-work-count": workCounts.cancelled,
+        "complete-work-count": workCounts.complete,
         "next-step": "slopflow start <issue-id>",
-    });
+    };
+    if (json)
+        printJson({ status });
+    else
+        printBlock("status", status);
     return 0;
 }
 function readMachineConfig(root) {
@@ -453,27 +996,107 @@ function readMachineConfig(root) {
     return config;
 }
 function fetchGitHubItem(repo, number) {
-    const issue = runGhJson(["issue", "view", String(number), "--repo", repo, "--json", "number,title,body,url,state"]);
-    if (issue) {
-        return normalizeGitHubItem(issue, "issue");
-    }
-    const pr = runGhJson(["pr", "view", String(number), "--repo", repo, "--json", "number,title,body,url,state"]);
-    if (pr) {
-        return normalizeGitHubItem(pr, "pull_request");
-    }
-    throw new SlopflowError(`Could not read GitHub issue or PR #${number} from ${repo}.`, "Ensure `gh` is installed, authenticated, and the item exists.", 2);
+    const issueArgs = ["issue", "view", String(number), "--repo", repo, "--json", "number,title,body,url,state"];
+    const issue = runGhJson(issueArgs);
+    if (issue.ok) {
+        return normalizeGitHubItem(issue.value, "issue");
+    }
+    if (!issue.notFound) {
+        throw githubCommandError(issue);
+    }
+    const prArgs = ["pr", "view", String(number), "--repo", repo, "--json", "number,title,body,url,state"];
+    const pr = runGhJson(prArgs);
+    if (pr.ok) {
+        return normalizeGitHubItem(pr.value, "pull_request");
+    }
+    if (!pr.notFound) {
+        throw githubCommandError(pr);
+    }
+    throw new SlopflowError(`Could not read GitHub issue or PR #${number} from ${repo}.`, "Ensure the issue or PR exists in the configured repository.", 2, {
+        command: `gh ${issueArgs.join(" ")} && gh ${prArgs.join(" ")}`,
+        "exit-code": pr.exitCode,
+        detail: summarizeCommandFailure(pr),
+        "next-step": `verify #${number} exists in ${repo}`,
+    });
 }
 function runGhJson(args) {
     const result = spawnSync("gh", args, { encoding: "utf8" });
-    if (result.error || result.status !== 0) {
-        return null;
+    if (result.error) {
+        return {
+            ok: false,
+            args,
+            exitCode: "spawn-error",
+            stdout: result.stdout ?? "",
+            stderr: result.stderr ?? "",
+            message: result.error.message,
+            notFound: false,
+            spawnError: result.error.message,
+        };
+    }
+    if (result.status !== 0) {
+        const stdout = result.stdout ?? "";
+        const stderr = result.stderr ?? "";
+        return {
+            ok: false,
+            args,
+            exitCode: typeof result.status === "number" ? result.status : 1,
+            stdout,
+            stderr,
+            message: summarizeText(stderr || stdout || "gh command failed"),
+            notFound: isLikelyNotFound(stdout, stderr),
+        };
     }
     try {
-        return JSON.parse(result.stdout);
+        return { ok: true, value: JSON.parse(result.stdout) };
     }
-    catch {
-        return null;
+    catch (error) {
+        return {
+            ok: false,
+            args,
+            exitCode: 0,
+            stdout: result.stdout ?? "",
+            stderr: result.stderr ?? "",
+            message: error instanceof Error ? error.message : "GitHub JSON parse failed",
+            notFound: false,
+        };
+    }
+}
+function githubCommandError(failure) {
+    return new SlopflowError("GitHub command failed while reading issue work.", nextStepForGithubFailure(failure), 2, {
+        command: `gh ${failure.args.join(" ")}`,
+        "exit-code": failure.exitCode,
+        detail: summarizeCommandFailure(failure),
+        "next-step": nextStepForGithubFailure(failure),
+    });
+}
+function summarizeCommandFailure(failure) {
+    const parts = [failure.message, summarizeText(failure.stderr), summarizeText(failure.stdout)].filter(Boolean);
+    return parts.length > 0 ? parts.join(" | ") : "gh command failed";
+}
+function summarizeText(value, limit = 300) {
+    const normalized = value.replace(/\s+/g, " ").trim();
+    if (!normalized)
+        return "";
+    return normalized.length > limit ? `${normalized.slice(0, limit)}...` : normalized;
+}
+function isLikelyNotFound(stdout, stderr) {
+    const text = `${stdout}\n${stderr}`.toLowerCase();
+    return /not found|could not resolve|no .* found|404/.test(text) && !isLikelyAuthFailure(stdout, stderr);
+}
+function isLikelyAuthFailure(stdout, stderr) {
+    return /auth|authentication|authorize|login|401|403|forbidden|permission/i.test(`${stdout}\n${stderr}`);
+}
+function nextStepForGithubFailure(failure) {
+    if (failure.spawnError) {
+        return "install GitHub CLI `gh` and ensure it is on PATH";
     }
+    if (isLikelyAuthFailure(failure.stdout, failure.stderr)) {
+        return "gh auth login";
+    }
+    if (failure.exitCode === 0) {
+        return "inspect gh JSON output or update GitHub response parsing";
+    }
+    return "inspect gh output and retry";
 }
 function normalizeGitHubItem(value, kind) {
     const item = value;
@@ -493,7 +1116,7 @@ function buildStartArtifacts({ issue, issueReference, workDir, root, }) {
     const contract = buildContract(issue, issueReference);
     const status = {
         schema_version: 1,
-        status: "started",
+        status: "active",
         issue: issueReference,
         work_directory: relative(root, workDir),
         artifacts: {
@@ -798,13 +1421,32 @@ function stableStringify(value) {
     }
     return JSON.stringify(value);
 }
-async function countWorkDirs(workRoot) {
+async function countWorkDirsByStatus(workRoot) {
+    const counts = { active: 0, paused: 0, cancelled: 0, complete: 0 };
     try {
         const entries = await readdir(workRoot, { withFileTypes: true });
-        return entries.filter((entry) => entry.isDirectory()).length;
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            const statusPath = join(workRoot, entry.name, "status.json");
+            let status = "active";
+            if (existsSync(statusPath)) {
+                const value = readJson(statusPath);
+                status = value.status ?? "active";
+            }
+            if (status === "paused")
+                counts.paused += 1;
+            else if (status === "cancelled")
+                counts.cancelled += 1;
+            else if (status === "complete")
+                counts.complete += 1;
+            else
+                counts.active += 1;
+        }
+        return counts;
     }
     catch {
-        return 0;
+        return counts;
     }
 }
 function readCurrentJjChange(root) {
@@ -844,8 +1486,11 @@ function printBlock(name, values, stream = process.stdout) {
         stream.write(`  ${key}: ${String(value)}\n`);
     }
 }
+function printJson(value, stream = process.stdout) {
+    stream.write(`${JSON.stringify(value, null, 2)}\n`);
+}
 function printHelp() {
-    process.stdout.write(`Usage: slopflow <command>\n\nCommands:\n  init [--force]\n  status\n  start <issue-id>\n  test <issue-id> --name <gate> -- <command...>\n  review <issue-id>\n  complete <issue-id>\n`);
+    process.stdout.write(`Usage: slopflow <command>\n\nCommands:\n  init [--force]\n  status\n  doctor\n  install minimal [--yes] [--force]\n  install recommended [--yes] [--force]\n  start <issue-id>\n  pause <issue-id> --reason <text>\n  resume <issue-id>\n  cancel <issue-id> --reason <text>\n  test <issue-id> --name <gate> -- <command...>\n  review <issue-id>\n  complete <issue-id>\n`);
 }
 if (process.argv[1] && realpathSync(fileURLToPath(import.meta.url)) === realpathSync(process.argv[1])) {
     process.exitCode = await main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "slopflow",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Controlled issue execution workflow for AI coding agents",
   "license": "MIT",
   "type": "module",
@@ -21,7 +21,7 @@
     "url": "https://github.com/aivv73/slopflow/issues"
   },
   "bin": {
-    "slopflow": "./dist/cli.js"
+    "slopflow": "dist/cli.js"
   },
   "files": [
     "dist",