slopflow 0.1.0 → 0.2.0

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>
@@ -49,6 +52,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
@@ -94,7 +107,9 @@ Agent skills are installed separately through Vercel Skills. The Slopflow npm pa
 
 ## 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

@@ -32,6 +32,15 @@ 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]);
         }
@@ -70,6 +79,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 +306,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];
@@ -427,7 +574,7 @@ 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", {
         state: "initialized",
@@ -436,7 +583,10 @@ async function statusCommand() {
         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>",
     });
     return 0;
@@ -493,7 +643,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 +948,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) {
@@ -845,7 +1014,7 @@ function printBlock(name, values, stream = process.stdout) {
     }
 }
 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  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.0",
   "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",