harnessed 4.5.0 → 4.6.0

package/README.md

@@ -21,7 +21,7 @@
 
 ### 🔁 The operating loop
 
-> **Discuss → Plan → Build → Verify → Ship → Learn** — one repeatable loop, machine-executed across the three-layer stack (gstack governance · GSD orchestration · superpowers TDD · checkpoint evidence). Raw agent work drifts; harnessed turns it into a source-of-truth path where progress, evidence, and learnings persist instead of living in chat.
+> **Discuss → Plan → Build → Verify → Ship**, closed by a **Learn** loop — machine-executed across the three-layer stack (gstack governance · GSD orchestration · superpowers TDD · checkpoint evidence). Raw agent work drifts; harnessed turns it into a source-of-truth path where progress and evidence persist instead of living in chat. **Learning is automatic**: every completed workflow appends its failure/loop/reject signals to `.planning/LEARNINGS.md`, which are injected into the next cycle — this is always-on, **not** gated on the optional Retro. Retro (`/retro`) is a separate, optional milestone summary.
 
 ```mermaid
 flowchart LR
@@ -30,9 +30,9 @@ flowchart LR
   P --> T(["③ Task<br/>TDD build + checkpoint"])
   T --> V(["④ Verify<br/>independent review + evidence gate"])
   V --> S(["⑤ Ship<br/>release-preflight → tag-ready (publish via CI)"])
-  S --> L(["⑥ Retro<br/>capture learnings → next session smarter"])
+  S -. "milestone summary" .-> RT(["Retro<br/>(optional)"]):::opt
   V -. "fail / gap" .-> T
-  L -. "next requirement" .-> D
+  S == "🔁 Learn — learnings captured on every workflow completion → injected next cycle" ==> D
   classDef opt stroke-dasharray:5,opacity:0.8
 ```
 
@@ -405,10 +405,18 @@ planning-with-files /plan (cross-cutting tool) → write artifacts to .planning/
 | `harnessed gates <master>` | Evaluate which sub-workflows fire for a master stage (JSON: fire/skip/parallelism). Used by slash commands to orchestrate native spawns. |
 | `harnessed prompt <sub>` | Output a spawn-ready prompt (role + checklist + disciplines + completion/clarification protocols) for a sub-workflow. |
 | `harnessed checkpoint <action> <sub>` | Record sub-workflow start/complete/fail to `~/.claude/harnessed/checkpoints/`. |
+| `harnessed next` | Deterministic next-step contract (`NEXT: auto\|manual\|done`) for the active workflow. |
+| `harnessed reject <sub>` | Mark a sub as user-rejected (terminal, distinct from `failed`). |
+| `harnessed compact [--tokens <n>]` | Summarize+evict resolved ledger entries (G6-safe: `fail_count>0` never evicted); auto-triggers on `checkpoint complete --tokens`. |
+| `harnessed workflows` | List in-flight workflows (one per repo). |
+| `harnessed learn "<lesson>"` | Append a prose learning to this repo's `.planning/LEARNINGS.md`. |
 | `harnessed run <name>` | Run a workflow via in-process SDK spawn (CI/headless mode). Slash commands use CC-native spawn instead. |
 | `harnessed resume` | Resume from the most recent checkpoint after a session interruption |
 | `harnessed status` | Current phase + lock holder |
-| `harnessed doctor` | 8-check health check (Node / MCP / jq / Win bash / routing / token budget, etc.) |
+| `harnessed doctor` | 14-check health check (Node / MCP / jq / Win bash / routing / token budget / mattpocock / CodeGraph / update-available, etc.) |
+| `harnessed update [--check\|--upstreams\|--migration-report]` | Self-update (`npm i -g harnessed@latest`); `--check` reports the latest version; `--upstreams` re-runs the base manifests; `--migration-report` is a read-only stale-state inventory |
+| `harnessed release-preflight` | Read-only release-readiness gate (CHANGELOG `[Unreleased]` / version / git-clean / tag-absent); exits 1 if not ready. The Ship-stage gate. |
+| `harnessed retro --done` | Reset the retro-reminder phase counter after running `/retro` (clears the per-turn RETRO-DUE nudge). |
 | `harnessed install <name>` | Install an upstream manifest |
 | `harnessed uninstall [name]` | Reverse uninstall |
 | `harnessed backup` | Snapshot backup management |

package/bin/harnessed-inject-state.mjs

@@ -65,6 +65,17 @@ function workflowStateBlock(wf) {
         `BREAK-LOOP: sub '${e.sub}' failed ${e.fail_count}x — stop retrying, run break-loop skill`,
       )
   }
+  // Phase 22 — smart-reminder lines from envelope flags (parity with injectState.ts).
+  if (wf.ship_ready) {
+    lines.push(
+      `SHIP-READY: ${wf.ship_commits ?? 0} commit(s) since the last release tag — consider shipping (harnessed release-preflight, then /ship)`,
+    )
+  }
+  if (wf.retro_due) {
+    lines.push(
+      'RETRO-DUE: enough phases completed since the last retro — run /retro, then `harnessed retro --done`',
+    )
+  }
   lines.push('</workflow-state>')
   return lines.join('\n')
 }

package/dist/cli.mjs

@@ -38,7 +38,7 @@ var init_package = __esm({
   "package.json"() {
     package_default = {
       name: "harnessed",
-      version: "4.5.0",
+      version: "4.6.0",
       description: "AI coding harness package manager + composition orchestrator",
       type: "module",
       license: "Apache-2.0",
@@ -944,6 +944,10 @@ async function backup(plan, ctx) {
         });
         continue;
       }
+      if (code === "EISDIR") {
+        entries.push({ target: file.target, backup: "", sha1: "", eol: "lf" });
+        continue;
+      }
       return {
         ok: false,
         error: {
@@ -1287,7 +1291,19 @@ var init_currentWorkflow_v1 = __esm({
             },
             { additionalProperties: false }
           )
-        )
+        ),
+        // Phase 22 — smart reminders. Additive-optional flags set by `checkpoint
+        // complete` (allResolved) and read by the G4 inject twins (booleans only; the
+        // bin computes neither git nor thresholds). Old files without them Value.Check-pass
+        // → NO schemaVersion bump.
+        //   ship_ready  — there are unshipped commits since the last vX.Y.Z tag (git-derived,
+        //                 recomputed each completion; self-heals to false after a release).
+        //   ship_commits — commit count since that tag (feeds the SHIP-READY hint text).
+        //   retro_due   — phases_since_retro (store sidecar) has crossed the threshold;
+        //                 cleared by `harnessed retro --done`.
+        ship_ready: Type.Optional(Type.Boolean()),
+        ship_commits: Type.Optional(Type.Integer({ minimum: 0 })),
+        retro_due: Type.Optional(Type.Boolean())
       },
       { additionalProperties: false }
     );
@@ -1305,6 +1321,7 @@ var init_schema2 = __esm({
 // src/checkpoint/workflowStore.ts
 var workflowStore_exports = {};
 __export(workflowStore_exports, {
+  RetroMetaEntry: () => RetroMetaEntry,
   WorkflowStoreV1: () => WorkflowStoreV1,
   listWorkflows: () => listWorkflows,
   readStoreRaw: () => readStoreRaw,
@@ -1365,17 +1382,26 @@ async function listWorkflows() {
     status: wf.status
   }));
 }
-var WorkflowStoreV1;
+var RetroMetaEntry, WorkflowStoreV1;
 var init_workflowStore = __esm({
   "src/checkpoint/workflowStore.ts"() {
     init_harnessedRoot();
     init_schemaVersion();
     init_atomicWrite();
     init_currentWorkflow_v1();
+    RetroMetaEntry = Type.Object(
+      {
+        phases_since_retro: Type.Integer({ minimum: 0 }),
+        last_retro_at: Type.Optional(Type.String({ minLength: 1 }))
+      },
+      { additionalProperties: false }
+    );
     WorkflowStoreV1 = Type.Object(
       {
         schemaVersion: Type.Literal(SCHEMA_VERSIONS.workflowStore),
-        workflows: Type.Record(Type.String(), CurrentWorkflowV1)
+        workflows: Type.Record(Type.String(), CurrentWorkflowV1),
+        // Additive-optional (no schemaVersion bump — old stores Value.Check-pass).
+        retro_meta: Type.Optional(Type.Record(Type.String(), RetroMetaEntry))
       },
       { additionalProperties: false }
     );
@@ -1389,6 +1415,7 @@ __export(state_exports, {
   WorkflowStateError: () => WorkflowStateError,
   activate: () => activate,
   complete: () => complete,
+  mutateStore: () => mutateStore,
   mutateSubProgress: () => mutateSubProgress,
   pause: () => pause,
   readCurrentWorkflow: () => readCurrentWorkflow,
@@ -1448,6 +1475,12 @@ async function mutateSubProgress(fn) {
     await writeCurrentWorkflowUnlocked({ ...s, sub_progress: next });
   });
 }
+async function mutateStore(fn) {
+  await withLock(async () => {
+    const store = await readStoreRaw();
+    await writeStoreRaw(fn(store));
+  });
+}
 async function activate(phase, checkpointPath = null) {
   await writeCurrentWorkflow({
     schemaVersion: SCHEMA_VERSIONS.currentWorkflow,
@@ -3797,6 +3830,91 @@ var init_compact = __esm({
   }
 });
 
+// src/checkpoint/shipReady.ts
+var shipReady_exports = {};
+__export(shipReady_exports, {
+  collectShipReady: () => collectShipReady,
+  defaultShipReady: () => defaultShipReady,
+  pickLatestReleaseTag: () => pickLatestReleaseTag
+});
+function pickLatestReleaseTag(tags) {
+  let best = null;
+  for (const tag of tags) {
+    const m = RELEASE_TAG.exec(tag.trim());
+    if (!m) continue;
+    const n = [Number(m[1]), Number(m[2]), Number(m[3])];
+    if (!best || n[0] > best.n[0] || n[0] === best.n[0] && n[1] > best.n[1] || n[0] === best.n[0] && n[1] === best.n[1] && n[2] > best.n[2]) {
+      best = { tag: tag.trim(), n };
+    }
+  }
+  return best?.tag ?? null;
+}
+function collectShipReady(tags, countSince) {
+  const baseTag = pickLatestReleaseTag(tags);
+  const commits = countSince(baseTag);
+  return { ready: commits > 0, commits, baseTag };
+}
+function defaultShipReady(cwd) {
+  let tags = [];
+  try {
+    tags = execFileSync("git", ["tag", "-l"], { cwd, encoding: "utf8" }).split("\n").map((s) => s.trim()).filter(Boolean);
+  } catch {
+    return { ready: false, commits: 0, baseTag: null };
+  }
+  const countSince = (tag) => {
+    try {
+      const range = tag ? `${tag}..HEAD` : "HEAD";
+      const out = execFileSync("git", ["rev-list", range, "--count"], {
+        cwd,
+        encoding: "utf8"
+      }).trim();
+      const n = Number(out);
+      return Number.isFinite(n) ? n : 0;
+    } catch {
+      return 0;
+    }
+  };
+  return collectShipReady(tags, countSince);
+}
+var RELEASE_TAG;
+var init_shipReady = __esm({
+  "src/checkpoint/shipReady.ts"() {
+    RELEASE_TAG = /^v(\d+)\.(\d+)\.(\d+)$/;
+  }
+});
+
+// src/checkpoint/retroMeta.ts
+var retroMeta_exports = {};
+__export(retroMeta_exports, {
+  DEFAULT_RETRO_THRESHOLD: () => DEFAULT_RETRO_THRESHOLD,
+  incrementPhases: () => incrementPhases,
+  isRetroDue: () => isRetroDue,
+  resetRetro: () => resetRetro,
+  retroThreshold: () => retroThreshold
+});
+function retroThreshold(env) {
+  const raw = env.HARNESSED_RETRO_PHASE_THRESHOLD;
+  if (raw === void 0) return DEFAULT_RETRO_THRESHOLD;
+  const n = Number(raw);
+  return Number.isInteger(n) && n > 0 ? n : DEFAULT_RETRO_THRESHOLD;
+}
+function incrementPhases(entry) {
+  if (!entry) return { phases_since_retro: 1 };
+  return entry.last_retro_at ? { phases_since_retro: entry.phases_since_retro + 1, last_retro_at: entry.last_retro_at } : { phases_since_retro: entry.phases_since_retro + 1 };
+}
+function isRetroDue(count, threshold) {
+  return count >= threshold;
+}
+function resetRetro(now) {
+  return { phases_since_retro: 0, last_retro_at: now };
+}
+var DEFAULT_RETRO_THRESHOLD;
+var init_retroMeta = __esm({
+  "src/checkpoint/retroMeta.ts"() {
+    DEFAULT_RETRO_THRESHOLD = 5;
+  }
+});
+
 // src/checkpoint/breakLoop.ts
 var breakLoop_exports = {};
 __export(breakLoop_exports, {
@@ -4816,7 +4934,7 @@ function expandTildeForWindows(cmd) {
   const home = homedir().replace(/\\/g, "/");
   return cmd.replace(/(^|[\s"'`(])~\//g, `$1${home}/`);
 }
-async function spawnCmd(ctx, cmd, args, timeoutMs) {
+async function spawnCmd(ctx, cmd, args, timeoutMs, opts) {
   const violation = checkCmdString(cmd);
   if (violation) {
     return {
@@ -4837,14 +4955,21 @@ async function spawnCmd(ctx, cmd, args, timeoutMs) {
   const env = { ...process.env, ...installCfg.env ?? {} };
   const cwd = installCfg.cwd ?? ctx.cwd;
   let child;
+  let triedBash = false;
   if (process.platform === "win32") {
-    const expandedCmd = expandTildeForWindows(cmd);
-    const expandedArgs = args.map(expandTildeForWindows);
-    child = spawn("cmd.exe", ["/c", expandedCmd, ...expandedArgs], {
-      cwd,
-      env,
-      windowsHide: true
-    });
+    if (opts?.posixShell) {
+      const joined = args.length > 0 ? `${cmd} ${args.join(" ")}` : cmd;
+      triedBash = true;
+      child = spawn("bash", ["-c", joined], { cwd, env, windowsHide: true });
+    } else {
+      const expandedCmd = expandTildeForWindows(cmd);
+      const expandedArgs = args.map(expandTildeForWindows);
+      child = spawn("cmd.exe", ["/c", expandedCmd, ...expandedArgs], {
+        cwd,
+        env,
+        windowsHide: true
+      });
+    }
   } else {
     const joined = args.length > 0 ? `${cmd} ${args.join(" ")}` : cmd;
     child = spawn("/bin/sh", ["-c", joined], { cwd, env });
@@ -4875,16 +5000,17 @@ async function spawnCmd(ctx, cmd, args, timeoutMs) {
     }, effectiveTimeoutMs);
     child.on("error", (err2) => {
       clearTimeout(timer);
+      const bashMissing = triedBash && err2.code === "ENOENT";
       resolve20({
         ok: false,
         phase: "spawn",
         error: {
           file: ctx.manifest.metadata.name,
           path: "/spec/install/cmd",
-          message: `spawn failed: ${err2.message}`,
+          message: bashMissing ? "Git Bash is required for this component on Windows, but `bash` was not found on PATH. Install Git for Windows (https://git-scm.com/download/win) and re-run `harnessed setup`." : `spawn failed: ${err2.message}`,
           line: null,
           column: null,
-          keyword: "spawn-error"
+          keyword: bashMissing ? "bash-missing" : "spawn-error"
         }
       });
     });
@@ -4899,7 +5025,7 @@ var init_spawn = __esm({
   "src/installers/lib/spawn.ts"() {
     init_security();
     DEFAULT_VERIFY_TIMEOUT_MS = 15e3;
-    DEFAULT_INSTALL_TIMEOUT_MS = 6e4;
+    DEFAULT_INSTALL_TIMEOUT_MS = 12e4;
   }
 });
 function extractSkillName(cmd, fallback) {
@@ -5335,7 +5461,7 @@ var init_gitCloneWithSetup2 = __esm({
       if (ctx.opts.dryRun) return { aborted: true, reason: "user-cancel" };
       const bk = await backup(plan, ctx);
       if (!bk.ok) return { ok: false, phase: "preflight", error: bk.error };
-      const sp = await spawnCmd(ctx, install.cmd, [], DEFAULT_INSTALL_TIMEOUT_MS);
+      const sp = await spawnCmd(ctx, install.cmd, [], DEFAULT_INSTALL_TIMEOUT_MS, { posixShell: true });
       if (!("exitCode" in sp)) return { ...sp, backupId: bk.backupId };
       if (sp.exitCode !== 0) {
         return {
@@ -5378,7 +5504,9 @@ var init_gitCloneWithSetup2 = __esm({
         };
       }
       const verifyTimeoutMs = ctx.manifest.spec.verify.timeout_ms ?? DEFAULT_VERIFY_TIMEOUT_MS;
-      const vr = await spawnCmd(ctx, ctx.manifest.spec.verify.cmd, [], verifyTimeoutMs);
+      const vr = await spawnCmd(ctx, ctx.manifest.spec.verify.cmd, [], verifyTimeoutMs, {
+        posixShell: true
+      });
       if (!("exitCode" in vr)) return { ...vr, backupId: bk.backupId };
       const expected = ctx.manifest.spec.verify.expected_exit_code ?? 0;
       if (vr.exitCode !== expected) {
@@ -5809,7 +5937,9 @@ var init_npmCli2 = __esm({
         };
       }
       const verifyTimeoutMs = ctx.manifest.spec.verify.timeout_ms ?? DEFAULT_VERIFY_TIMEOUT_MS;
-      const vr = await spawnCmd(ctx, ctx.manifest.spec.verify.cmd, [], verifyTimeoutMs);
+      const vr = await spawnCmd(ctx, ctx.manifest.spec.verify.cmd, [], verifyTimeoutMs, {
+        posixShell: true
+      });
       if (!("exitCode" in vr)) return { ...vr, backupId: bk.backupId };
       const expected = ctx.manifest.spec.verify.expected_exit_code ?? 0;
       if (vr.exitCode !== expected) {
@@ -5938,7 +6068,9 @@ var init_npxSkillInstaller2 = __esm({
         };
       }
       const verifyTimeoutMs = ctx.manifest.spec.verify.timeout_ms ?? DEFAULT_VERIFY_TIMEOUT_MS;
-      const vr = await spawnCmd(ctx, ctx.manifest.spec.verify.cmd, [], verifyTimeoutMs);
+      const vr = await spawnCmd(ctx, ctx.manifest.spec.verify.cmd, [], verifyTimeoutMs, {
+        posixShell: true
+      });
       if (!("exitCode" in vr)) return { ...vr, backupId: bk.backupId };
       const expected = ctx.manifest.spec.verify.expected_exit_code ?? 0;
       if (vr.exitCode !== expected) {
@@ -6981,6 +7113,35 @@ function registerCheckpoint(program2) {
             );
           }
         }
+        if (allResolved) {
+          try {
+            const { defaultShipReady: defaultShipReady2 } = await Promise.resolve().then(() => (init_shipReady(), shipReady_exports));
+            const { incrementPhases: incrementPhases2, isRetroDue: isRetroDue2, retroThreshold: retroThreshold2 } = await Promise.resolve().then(() => (init_retroMeta(), retroMeta_exports));
+            const { mutateStore: mutateStore2, readCurrentWorkflow: readCurrentWorkflow4, writeCurrentWorkflow: writeCurrentWorkflow3 } = await Promise.resolve().then(() => (init_state(), state_exports));
+            const { repoKey: repoKey2 } = await Promise.resolve().then(() => (init_workflowStore(), workflowStore_exports));
+            const ship = defaultShipReady2(process.cwd());
+            const key = repoKey2();
+            const threshold = retroThreshold2(process.env);
+            let retroDue = false;
+            await mutateStore2((store) => {
+              const meta = { ...store.retro_meta ?? {} };
+              const next = incrementPhases2(meta[key]);
+              meta[key] = next;
+              retroDue = isRetroDue2(next.phases_since_retro, threshold);
+              return { ...store, retro_meta: meta };
+            });
+            const latest2 = await readCurrentWorkflow4();
+            if (latest2) {
+              await writeCurrentWorkflow3({
+                ...latest2,
+                ship_ready: ship.ready,
+                ship_commits: ship.commits,
+                retro_due: retroDue
+              });
+            }
+          } catch {
+          }
+        }
         console.log(`[harnessed] checkpoint complete: ${sub} (evidence: ${evidenceStatus})`);
         process.exit(0);
         return;
@@ -7725,6 +7886,37 @@ function registerResume(program2) {
     process.exit(0);
   });
 }
+
+// src/cli/retro.ts
+init_retroMeta();
+async function runRetroDone(now) {
+  const { mutateStore: mutateStore2, readCurrentWorkflow: readCurrentWorkflow2, writeCurrentWorkflow: writeCurrentWorkflow2 } = await Promise.resolve().then(() => (init_state(), state_exports));
+  const { repoKey: repoKey2 } = await Promise.resolve().then(() => (init_workflowStore(), workflowStore_exports));
+  const key = repoKey2();
+  await mutateStore2((store) => {
+    const meta = { ...store.retro_meta ?? {} };
+    meta[key] = resetRetro(now);
+    return { ...store, retro_meta: meta };
+  });
+  const wf = await readCurrentWorkflow2();
+  if (wf?.retro_due) await writeCurrentWorkflow2({ ...wf, retro_due: false });
+  return { reset: true };
+}
+function registerRetro(program2) {
+  program2.command("retro").description("Retro cadence: --done resets the phase counter after running /retro").option(
+    "--done",
+    "mark a retro as done \u2014 reset the phase counter + clear the RETRO-DUE reminder"
+  ).action(async (opts) => {
+    if (!opts.done) {
+      console.error("[harnessed] retro: nothing to do \u2014 pass --done after running /retro");
+      process.exit(1);
+      return;
+    }
+    await runRetroDone((/* @__PURE__ */ new Date()).toISOString());
+    console.log("[harnessed] retro recorded \u2014 phase counter reset, RETRO-DUE reminder cleared");
+    process.exit(0);
+  });
+}
 init_backup();
 function normalizeEol(buf, eol) {
   const lf = buf.toString("utf8").replace(/\r\n/g, "\n");
@@ -9220,6 +9412,7 @@ registerWorkflows(program);
 registerLearn(program);
 registerUpdate(program);
 registerReleasePreflight(program);
+registerRetro(program);
 program.parse(process.argv);
 //# sourceMappingURL=cli.mjs.map
 //# sourceMappingURL=cli.mjs.map