work-kit-cli 0.4.0 → 0.4.1

package/cli/src/commands/extract.ts

@@ -51,49 +51,39 @@ function parseStateMd(stateMd: string): RawEntry[] {
   const out: RawEntry[] = [];
   if (!stateMd) return out;
 
-  let section: "observations" | "decisions" | "deviations" | null = null;
+  // Only `## Observations` is auto-harvested. `## Decisions` and `## Deviations`
+  // are agent scratch space during normal phase work — they routinely contain
+  // test plans, acceptance-criteria checklists, and self-review dumps. Auto-
+  // routing them floods workflow.md with noise. Agents opt into harvesting by
+  // writing typed bullets (`- [lesson|convention|risk|workflow] text`) under
+  // `## Observations`.
+  let inObservations = false;
 
   for (const rawLine of stateMd.split("\n")) {
     const trimmed = rawLine.trim();
 
     if (trimmed.startsWith("## ")) {
-      const header = trimmed.slice(3).trim().toLowerCase();
-      if (header === "observations") section = "observations";
-      else if (header === "decisions") section = "decisions";
-      else if (header === "deviations") section = "deviations";
-      else section = null;
+      inObservations = trimmed.slice(3).trim().toLowerCase() === "observations";
       continue;
     }
 
-    if (section === null) continue;
+    if (!inObservations) continue;
     if (!trimmed.startsWith("-") || trimmed.startsWith("<!--")) continue;
 
-    if (section === "observations") {
-      const m = trimmed.match(OBSERVATION_RE);
-      if (!m) continue;
-      const tag = m[1].toLowerCase();
-      if (!isKnowledgeType(tag)) continue;
-      const phaseStep = m[2];
-      const text = m[3].trim();
-      if (text.length === 0) continue;
-      const entry: RawEntry = { type: tag, text, source: "auto-state-md" };
-      if (phaseStep) {
-        const [p, s] = phaseStep.split("/");
-        entry.phase = p;
-        entry.step = s;
-      }
-      out.push(entry);
-      continue;
-    }
-
-    const text = trimmed.replace(/^-\s*/, "").trim();
+    const m = trimmed.match(OBSERVATION_RE);
+    if (!m) continue;
+    const tag = m[1].toLowerCase();
+    if (!isKnowledgeType(tag)) continue;
+    const phaseStep = m[2];
+    const text = m[3].trim();
     if (text.length === 0) continue;
-
-    if (section === "decisions") {
-      out.push({ type: "convention", text, source: "auto-state-md" });
-    } else if (section === "deviations") {
-      out.push({ type: "workflow", text: `[deviation] ${text}`, source: "auto-state-md" });
+    const entry: RawEntry = { type: tag, text, source: "auto-state-md" };
+    if (phaseStep) {
+      const [p, s] = phaseStep.split("/");
+      entry.phase = p;
+      entry.step = s;
     }
+    out.push(entry);
   }
 
   return out;

package/cli/src/commands/learn.test.ts

@@ -176,6 +176,33 @@ describe("learnCommand", () => {
     assert.ok(workflowMd.includes("e2e step needs server"));
   });
 
+  it("ignores bullets under ## Decisions and ## Deviations", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+    setupSession(tmp);
+
+    // Simulate an agent dumping test-plan noise into Decisions/Deviations.
+    // None of these should be harvested — only ## Observations is auto-routed.
+    const stateMdPath = path.join(tmp, ".work-kit", "state.md");
+    const original = fs.readFileSync(stateMdPath, "utf-8");
+    const injected = original
+      .replace(
+        "## Decisions\n<!-- Append here whenever you choose between real alternatives -->",
+        "## Decisions\n<!-- Append here whenever you choose between real alternatives -->\n- Picked Zod over Yup\n- Use Firestore onSnapshot\n- **Expected:** Badge renders X / Y"
+      )
+      .replace(
+        "## Deviations\n<!-- Append here whenever implementation diverges from the Blueprint -->",
+        "## Deviations\n<!-- Append here whenever implementation diverges from the Blueprint -->\n- Navigate to / and verify cards render\n- Check badge shows 0 / 0\n- **Flow 3:** Pass"
+      );
+    fs.writeFileSync(stateMdPath, injected);
+
+    const r = extractCommand({ worktreeRoot: tmp });
+    assert.equal(r.action, "extracted");
+    assert.equal(r.written, 0, "no bullets from Decisions/Deviations should be harvested");
+    assert.equal(r.byType.convention, 0);
+    assert.equal(r.byType.workflow, 0);
+  });
+
   it("extract is idempotent (re-run produces only duplicates)", () => {
     const tmp = makeTmpDir();
     tmpDirs.push(tmp);

package/cli/src/commands/setup.ts

@@ -243,7 +243,23 @@ function installPlaywrightPackage(pm: PackageManager, projectDir: string): boole
     pm === "yarn" ? ["add", "-D", "@playwright/test"] :
     ["install", "-D", "@playwright/test"];
   console.error(`  ${dim(`$ ${pm} ${args.join(" ")}`)}`);
-  return runStreamed(pm, args, projectDir);
+  if (runStreamed(pm, args, projectDir)) return true;
+
+  // The most common npm failure here is ERESOLVE — the user's project has
+  // a pre-existing peer-dep conflict that npm refuses to resolve. Retry with
+  // --legacy-peer-deps so Playwright still installs; the user's underlying
+  // conflict is left for them to fix separately.
+  if (pm === "npm") {
+    console.error(`  ${yellow("!")} npm install failed (likely peer-dep conflict). Retrying with --legacy-peer-deps...`);
+    const fallbackArgs = [...args, "--legacy-peer-deps"];
+    console.error(`  ${dim(`$ ${pm} ${fallbackArgs.join(" ")}`)}`);
+    if (runStreamed(pm, fallbackArgs, projectDir)) {
+      console.error(`  ${dim("Note: installed with --legacy-peer-deps. Your project still has the original peer-dep conflict — fix it separately when convenient.")}`);
+      return true;
+    }
+  }
+
+  return false;
 }
 
 function installPlaywrightBrowsers(projectDir: string): boolean {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "work-kit-cli",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Structured development workflow for Claude Code. Two modes, 6 phases, 27 steps.",
   "type": "module",
   "bin": {

package/skills/wk-wrap-up/SKILL.md

@@ -26,7 +26,7 @@ The summary you write goes into `.work-kit/summary.md`; the CLI archives it into
 4. **Run** `work-kit complete wrap-up/summary --outcome done`
 
 ### Step 2: knowledge
-5. **Run `work-kit extract`** — mechanically routes Observations / Decisions / Deviations / loopbacks into `.work-kit-knowledge/` files
+5. **Run `work-kit extract`** — routes typed `## Observations` bullets and tracker loopbacks/skipped/failed steps into `.work-kit-knowledge/` files. `## Decisions` and `## Deviations` are not auto-harvested (they're scratch space).
 6. **Review the summary you just wrote** for subjective additions the parser would miss. For each, call `work-kit learn --type <lesson|convention|risk|workflow> --text "..."`.
 7. **Run** `work-kit complete wrap-up/knowledge --outcome done`
 

package/skills/wk-wrap-up/steps/knowledge.md

@@ -15,12 +15,12 @@ After `wrap-up/summary`. By now you've just re-read the full `state.md` and dist
    work-kit extract
    ```
    This parses `.work-kit/state.md` and `.work-kit/tracker.json` and routes entries to `.work-kit-knowledge/{lessons,conventions,risks,workflow}.md`. It pulls from:
-   - `## Observations` typed bullets (`- [lesson|convention|risk|workflow] text`)
-   - `## Decisions` → conventions
-   - `## Deviations` → workflow feedback
+   - `## Observations` typed bullets (`- [lesson|convention|risk|workflow] text`) — the only section that is auto-harvested
    - `tracker.json.loopbacks[]` → workflow feedback
    - Skipped/failed steps → workflow feedback
 
+   `## Decisions` and `## Deviations` are **not** auto-harvested — they're agent scratch space and routinely contain test plans and review notes. If something in there is worth preserving, restate it as a typed bullet under `## Observations` (or call `work-kit learn` directly in step 2).
+
    The output JSON tells you how many entries were `written` vs `duplicates`. Re-running is idempotent.
 
 2. **Read your `.work-kit/summary.md`** (the one you just wrote). For each non-obvious thing in it that the parser would NOT have captured automatically, call `work-kit learn`: