slopflow 0.2.0 → 0.2.1

package/README.md

@@ -22,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
@@ -89,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
@@ -101,7 +224,7 @@ 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.
 

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]);
@@ -47,21 +66,391 @@ export async function main(argv = process.argv.slice(2)) {
         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);
@@ -566,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);
@@ -576,7 +965,7 @@ async function statusCommand() {
     const workRoot = join(root, artifactRoot);
     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,
@@ -588,7 +977,11 @@ async function statusCommand() {
         "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) {
@@ -603,28 +996,108 @@ 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;
     if (typeof item.number !== "number" || typeof item.title !== "string") {
@@ -1013,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  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`);
+    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.2.0",
+  "version": "0.2.1",
   "description": "Controlled issue execution workflow for AI coding agents",
   "license": "MIT",
   "type": "module",