work-kit-cli 0.2.2 → 0.2.3

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

@@ -0,0 +1,117 @@
+import { describe, it, afterEach } from "node:test";
+import * as assert from "node:assert/strict";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import { randomUUID } from "node:crypto";
+import { bootstrapCommand } from "./bootstrap.js";
+import { initCommand } from "./init.js";
+
+function makeTmpDir(): string {
+  const dir = path.join(os.tmpdir(), `work-kit-test-${randomUUID()}`);
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+let tmpDirs: string[] = [];
+
+afterEach(() => {
+  for (const dir of tmpDirs) {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+  tmpDirs = [];
+});
+
+describe("bootstrapCommand", () => {
+  it("returns inactive when no state exists", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+
+    const result = bootstrapCommand(tmp);
+    assert.equal(result.active, false);
+    assert.ok(result.nextAction?.includes("/full-kit"));
+  });
+
+  it("returns active state after init", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+
+    initCommand({
+      mode: "full",
+      description: "Test feature",
+      worktreeRoot: tmp,
+    });
+
+    const result = bootstrapCommand(tmp);
+    assert.equal(result.active, true);
+    assert.equal(result.slug, "test-feature");
+    assert.equal(result.mode, "full-kit");
+    assert.equal(result.status, "in-progress");
+    assert.equal(result.phase, "plan");
+    assert.equal(result.recovery, null);
+  });
+
+  it("detects stale state", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+
+    initCommand({
+      mode: "full",
+      description: "Stale test",
+      worktreeRoot: tmp,
+    });
+
+    // Backdate the state.json file to 3 hours ago
+    const stateFile = path.join(tmp, ".work-kit", "state.json");
+    const threeHoursAgo = new Date(Date.now() - 3 * 60 * 60 * 1000);
+    fs.utimesSync(stateFile, threeHoursAgo, threeHoursAgo);
+
+    const result = bootstrapCommand(tmp);
+    assert.equal(result.active, true);
+    assert.ok(result.recovery !== null);
+    assert.ok(result.recovery?.includes("stale"));
+  });
+
+  it("reports completed state", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+
+    initCommand({
+      mode: "full",
+      description: "Done feature",
+      worktreeRoot: tmp,
+    });
+
+    // Manually set status to completed
+    const stateFile = path.join(tmp, ".work-kit", "state.json");
+    const state = JSON.parse(fs.readFileSync(stateFile, "utf-8"));
+    state.status = "completed";
+    fs.writeFileSync(stateFile, JSON.stringify(state, null, 2));
+
+    const result = bootstrapCommand(tmp);
+    assert.equal(result.active, true);
+    assert.equal(result.status, "completed");
+    assert.ok(result.nextAction?.includes("complete"));
+  });
+
+  it("reports failed state", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+
+    initCommand({
+      mode: "full",
+      description: "Failed feature",
+      worktreeRoot: tmp,
+    });
+
+    const stateFile = path.join(tmp, ".work-kit", "state.json");
+    const state = JSON.parse(fs.readFileSync(stateFile, "utf-8"));
+    state.status = "failed";
+    fs.writeFileSync(stateFile, JSON.stringify(state, null, 2));
+
+    const result = bootstrapCommand(tmp);
+    assert.equal(result.active, true);
+    assert.equal(result.status, "failed");
+    assert.ok(result.nextAction?.includes("failed"));
+  });
+});

package/cli/src/commands/bootstrap.ts

@@ -0,0 +1,65 @@
+import fs from "node:fs";
+import { findWorktreeRoot, readState, statePath } from "../state/store.js";
+
+export interface BootstrapResult {
+  active: boolean;
+  slug?: string;
+  branch?: string;
+  mode?: string;
+  phase?: string | null;
+  subStage?: string | null;
+  status?: string;
+  nextAction?: string;
+  recovery?: string | null;
+}
+
+export function bootstrapCommand(startDir?: string): BootstrapResult {
+  const root = findWorktreeRoot(startDir);
+
+  if (!root) {
+    return {
+      active: false,
+      nextAction:
+        "No active work-kit session. Start one with /full-kit <description> or /auto-kit <description>.",
+    };
+  }
+
+  const state = readState(root);
+
+  // Check for staleness: if state file hasn't been modified in over 1 hour
+  let recovery: string | null = null;
+  try {
+    const stateFile = statePath(root);
+    const stat = fs.statSync(stateFile);
+    const hourAgo = Date.now() - 60 * 60 * 1000;
+    if (stat.mtimeMs < hourAgo) {
+      const hoursAgo = Math.round((Date.now() - stat.mtimeMs) / (60 * 60 * 1000));
+      recovery = `State appears stale (last update ~${hoursAgo}h ago). Run \`npx work-kit-cli status\` to diagnose. If the agent crashed mid-stage, run \`npx work-kit-cli next\` to resume.`;
+    }
+  } catch {
+    // Ignore stat errors
+  }
+
+  let nextAction: string;
+  if (state.status === "completed") {
+    nextAction = "Work-kit session is complete. Run wrap-up or start a new session.";
+  } else if (state.status === "failed") {
+    nextAction = "Work-kit session failed. Run `npx work-kit-cli status` to see details.";
+  } else if (recovery) {
+    nextAction = recovery;
+  } else {
+    nextAction = `Continue ${state.currentPhase ?? "next phase"}${state.currentSubStage ? "/" + state.currentSubStage : ""}. Run \`npx work-kit-cli next\` to get the agent prompt.`;
+  }
+
+  return {
+    active: true,
+    slug: state.slug,
+    branch: state.branch,
+    mode: state.mode,
+    phase: state.currentPhase,
+    subStage: state.currentSubStage,
+    status: state.status,
+    nextAction,
+    recovery,
+  };
+}

package/cli/src/commands/complete.ts

@@ -1,5 +1,6 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { execFileSync } from "node:child_process";
 import { readState, writeState, findWorktreeRoot, readStateMd } from "../state/store.js";
 import { isPhaseComplete, nextSubStageInPhase } from "../engine/transitions.js";
 import { checkLoopback } from "../engine/loopbacks.js";
@@ -135,8 +136,24 @@ export function completeCommand(target: string, outcome?: string, worktreeRoot?:
 
 // ── Archive on completion ──────────────────────────────────────────
 
+function resolveMainRepoRoot(worktreeRoot: string): string {
+  try {
+    // git worktree list --porcelain — first "worktree" line is always the main repo
+    const output = execFileSync("git", ["worktree", "list", "--porcelain"], {
+      cwd: worktreeRoot,
+      encoding: "utf-8",
+      timeout: 5000,
+    });
+    const firstLine = output.split("\n").find(l => l.startsWith("worktree "));
+    if (firstLine) return firstLine.slice("worktree ".length).trim();
+  } catch {
+    // fallback
+  }
+  return worktreeRoot;
+}
+
 function archiveCompleted(worktreeRoot: string, state: WorkKitState): void {
-  const mainRoot = state.metadata.mainRepoRoot || worktreeRoot;
+  const mainRoot = resolveMainRepoRoot(worktreeRoot);
   const date = new Date().toISOString().split("T")[0];
   const slug = state.slug;
   const wkDir = path.join(mainRoot, ".claude", "work-kit");

package/cli/src/context/extractor.ts

@@ -1,10 +1,11 @@
 import { readStateMd } from "../state/store.js";
+import { redactIgnoredBlocks } from "./redactor.js";
 
 /**
  * Extract a specific ### section from state.md by heading.
  * Returns the content between the heading and the next ### heading (or end of file).
  */
-export function extractSection(stateMd: string, heading: string): string | null {
+export function extractSection(stateMd: string, heading: string, redact?: boolean): string | null {
   // Normalize heading — ensure it starts with ###
   const prefix = heading.startsWith("###") ? heading : `### ${heading}`;
   const lines = stateMd.split("\n");
@@ -25,13 +26,15 @@ export function extractSection(stateMd: string, heading: string): string | null
     }
   }
 
-  return captured.length > 0 ? captured.join("\n").trim() : null;
+  if (captured.length === 0) return null;
+  const content = captured.join("\n").trim();
+  return redact ? redactIgnoredBlocks(content) : content;
 }
 
 /**
  * Extract a ## section (top-level section like Description, Criteria).
  */
-export function extractTopSection(stateMd: string, heading: string): string | null {
+export function extractTopSection(stateMd: string, heading: string, redact?: boolean): string | null {
   const prefix = heading.startsWith("##") ? heading : `## ${heading}`;
   const lines = stateMd.split("\n");
   let capturing = false;
@@ -51,7 +54,9 @@ export function extractTopSection(stateMd: string, heading: string): string | nu
     }
   }
 
-  return captured.length > 0 ? captured.join("\n").trim() : null;
+  if (captured.length === 0) return null;
+  const content = captured.join("\n").trim();
+  return redact ? redactIgnoredBlocks(content) : content;
 }
 
 /**

package/cli/src/context/prompt-builder.ts

@@ -3,6 +3,7 @@ import { getContextFor } from "../config/agent-map.js";
 import { extractSection, extractTopSection } from "./extractor.js";
 import { readStateMd } from "../state/store.js";
 import { skillFilePath } from "../config/phases.js";
+import { redactIgnoredBlocks } from "./redactor.js";
 
 /**
  * Build a complete agent prompt for a given phase/sub-stage.
@@ -66,5 +67,5 @@ export function buildAgentPrompt(
     parts.push(`When done, report your outcome so the orchestrator can run: \`npx work-kit-cli complete ${phase}/${subStage} --outcome <outcome>\``);
   }
 
-  return parts.join("\n");
+  return redactIgnoredBlocks(parts.join("\n"));
 }

package/cli/src/context/redactor.test.ts

@@ -0,0 +1,111 @@
+import { describe, it } from "node:test";
+import * as assert from "node:assert/strict";
+import { redactIgnoredBlocks } from "./redactor.js";
+
+describe("redactIgnoredBlocks", () => {
+  it("passes through content with no markers", () => {
+    const input = "line 1\nline 2\nline 3";
+    assert.equal(redactIgnoredBlocks(input), input);
+  });
+
+  it("redacts a block between start and end markers (// style)", () => {
+    const input = [
+      "before",
+      "// @wk-ignore-start",
+      "secret line 1",
+      "secret line 2",
+      "// @wk-ignore-end",
+      "after",
+    ].join("\n");
+
+    const result = redactIgnoredBlocks(input);
+    assert.ok(result.includes("before"));
+    assert.ok(result.includes("after"));
+    assert.ok(!result.includes("secret"));
+    assert.ok(result.includes("[redacted: 4 lines — @wk-ignore]"));
+  });
+
+  it("redacts a block with # comment style", () => {
+    const input = [
+      "before",
+      "# @wk-ignore-start",
+      "hidden = true",
+      "# @wk-ignore-end",
+      "after",
+    ].join("\n");
+
+    const result = redactIgnoredBlocks(input);
+    assert.ok(!result.includes("hidden"));
+    assert.ok(result.includes("[redacted: 3 lines — @wk-ignore]"));
+  });
+
+  it("redacts a block with HTML comment style", () => {
+    const input = [
+      "before",
+      "<!-- @wk-ignore-start -->",
+      "<div>secret</div>",
+      "<!-- @wk-ignore-end -->",
+      "after",
+    ].join("\n");
+
+    const result = redactIgnoredBlocks(input);
+    assert.ok(!result.includes("secret"));
+    assert.ok(result.includes("[redacted: 3 lines — @wk-ignore]"));
+  });
+
+  it("handles unclosed marker by redacting to EOF", () => {
+    const input = [
+      "before",
+      "// @wk-ignore-start",
+      "line 1",
+      "line 2",
+      "line 3",
+    ].join("\n");
+
+    const result = redactIgnoredBlocks(input);
+    assert.ok(result.includes("before"));
+    assert.ok(!result.includes("line 1"));
+    assert.ok(result.includes("(unclosed marker)"));
+    assert.ok(result.includes("[redacted: 4 lines"));
+  });
+
+  it("handles multiple separate blocks", () => {
+    const input = [
+      "top",
+      "// @wk-ignore-start",
+      "hidden1",
+      "// @wk-ignore-end",
+      "middle",
+      "// @wk-ignore-start",
+      "hidden2",
+      "// @wk-ignore-end",
+      "bottom",
+    ].join("\n");
+
+    const result = redactIgnoredBlocks(input);
+    assert.ok(result.includes("top"));
+    assert.ok(result.includes("middle"));
+    assert.ok(result.includes("bottom"));
+    assert.ok(!result.includes("hidden1"));
+    assert.ok(!result.includes("hidden2"));
+    // Two separate redaction placeholders
+    const matches = result.match(/\[redacted:/g);
+    assert.equal(matches?.length, 2);
+  });
+
+  it("handles single-line block (start and end on same concept)", () => {
+    const input = [
+      "before",
+      "// @wk-ignore-start",
+      "// @wk-ignore-end",
+      "after",
+    ].join("\n");
+
+    const result = redactIgnoredBlocks(input);
+    assert.ok(result.includes("[redacted: 2 lines — @wk-ignore]"));
+  });
+
+  it("returns empty string for empty input", () => {
+    assert.equal(redactIgnoredBlocks(""), "");
+  });
+});

package/cli/src/context/redactor.ts

@@ -0,0 +1,38 @@
+/**
+ * Redact blocks between @wk-ignore-start and @wk-ignore-end markers.
+ * Supports comment styles: //, #, --, <!-- -->
+ * Replaces annotated blocks with a placeholder.
+ */
+
+const IGNORE_START = /@wk-ignore-start/;
+const IGNORE_END = /@wk-ignore-end/;
+
+export function redactIgnoredBlocks(content: string): string {
+  const lines = content.split("\n");
+  const result: string[] = [];
+  let inBlock = false;
+  let blockStart = -1;
+  let blockLineCount = 0;
+
+  for (let i = 0; i < lines.length; i++) {
+    if (!inBlock && IGNORE_START.test(lines[i])) {
+      inBlock = true;
+      blockStart = i;
+      blockLineCount = 0;
+    }
+
+    if (inBlock) {
+      blockLineCount++;
+      if (IGNORE_END.test(lines[i]) || i === lines.length - 1) {
+        // Emit placeholder
+        const warning = IGNORE_END.test(lines[i]) ? "" : " (unclosed marker)";
+        result.push(`// [redacted: ${blockLineCount} lines — @wk-ignore${warning}]`);
+        inBlock = false;
+      }
+    } else {
+      result.push(lines[i]);
+    }
+  }
+
+  return result.join("\n");
+}

package/cli/src/index.ts

@@ -15,6 +15,7 @@ import { upgradeCommand } from "./commands/upgrade.js";
 import { completionsCommand } from "./commands/completions.js";
 import { observeCommand } from "./commands/observe.js";
 import { uninstallCommand } from "./commands/uninstall.js";
+import { bootstrapCommand } from "./commands/bootstrap.js";
 import { bold, green, yellow, red } from "./utils/colors.js";
 import type { Classification, PhaseName } from "./state/schema.js";
 
@@ -250,4 +251,20 @@ program
     await uninstallCommand(targetPath);
   });
 
+// ── bootstrap ───────────────────────────────────────────────────────
+
+program
+  .command("bootstrap")
+  .description("Detect work-kit state and output session orientation")
+  .option("--json", "Output as JSON", true)
+  .action((opts) => {
+    try {
+      const result = bootstrapCommand();
+      console.log(JSON.stringify(result, null, 2));
+    } catch (e: any) {
+      console.error(JSON.stringify({ action: "error", message: e.message }));
+      process.exit(1);
+    }
+  });
+
 program.parse();

package/package.json

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

package/skills/auto-kit/SKILL.md

@@ -104,10 +104,14 @@ The table is a guide, not a rigid rule. Adjust based on the actual request:
 
 ## Continuing Work (`/auto-kit` with no args)
 
-1. Find the active worktree — check `git worktree list` or look for `.work-kit/state.md`
-2. Run `npx work-kit-cli status` to see current state
-3. Run `npx work-kit-cli next` to get the next action
-4. Follow the execution loop below
+1. Run `npx work-kit-cli bootstrap` to detect session state
+2. Parse the JSON response:
+   - If `active: false` — no session found, ask the user for a description and start new work
+   - If `recovery` is set — report the recovery suggestion to the user before continuing
+   - If `active: true` — report current state (slug, phase, sub-stage) to the user
+3. `cd` into the worktree directory
+4. Run `npx work-kit-cli next` to get the next action
+5. Follow the execution loop below
 
 ## Step Validation
 

package/skills/full-kit/SKILL.md

@@ -44,10 +44,14 @@ Do not proceed until `doctor` reports all checks passed.
 
 ## Continuing Work (`/full-kit` with no args)
 
-1. Find the active worktree — check `git worktree list` or look for `.work-kit/state.md`
-2. Run `npx work-kit-cli status` to see current state
-3. Run `npx work-kit-cli next` to get the next action
-4. Follow the execution loop below
+1. Run `npx work-kit-cli bootstrap` to detect session state
+2. Parse the JSON response:
+   - If `active: false` — no session found, ask the user for a description and start new work
+   - If `recovery` is set — report the recovery suggestion to the user before continuing
+   - If `active: true` — report current state (slug, phase, sub-stage) to the user
+3. `cd` into the worktree directory
+4. Run `npx work-kit-cli next` to get the next action
+5. Follow the execution loop below
 
 ## Execution Loop
 

package/skills/wk-bootstrap/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: bootstrap
+description: "Session bootstrap — detect work-kit state and orient the agent at session start."
+user-invocable: false
+allowed-tools: Bash, Read
+---
+
+# Session Bootstrap
+
+Run `npx work-kit-cli bootstrap` to detect work-kit state.
+
+## If active work exists
+
+- Report current state to the user: slug, phase, sub-stage, status
+- If recovery is suggested: follow the recovery instruction
+- Otherwise: run `npx work-kit-cli next` to continue the workflow
+
+## If no active work
+
+- Inform the user that work-kit is available
+- Available commands: `/full-kit <description>` or `/auto-kit <description>`
+- Do not start work unprompted
+
+## If session is stale
+
+- Report the staleness warning to the user
+- Run `npx work-kit-cli status` to get full diagnostics
+- If the state is recoverable, run `npx work-kit-cli next` to resume
+- If the state is corrupted, suggest starting fresh

package/skills/wk-build/SKILL.md

@@ -40,6 +40,29 @@ Throughout every sub-stage, capture three things in the shared state.md sections
 
 These feed into the final work-kit log summary. If you don't record them here, they're lost.
 
+## Boundaries
+
+### Always
+- Follow the Blueprint step order unless a dependency requires reordering
+- Run the test suite after every sub-stage that changes code
+- Record every deviation from the Blueprint in the ## Deviations section
+- Match existing codebase patterns found during Plan/Investigate
+- Commit .work-kit/ files separately from feature code
+
+### Ask First
+- Redesigning any part of the Blueprint (adapt minimally, don't redesign)
+- Adding dependencies not specified in the Blueprint
+- Changing the data model beyond what Architecture specified
+- Skipping the Red (failing tests) sub-stage
+
+### Never
+- Write implementation code before writing failing tests (Red comes before Core)
+- Introduce new conventions that differ from existing codebase patterns
+- Refactor code you did not write or modify in this feature
+- Force push to any branch
+- Include .env files, secrets, or credentials in commits
+- Proceed with failing pre-existing tests without explaining why they changed
+
 ## Loop-back
 
 If **Refactor** returns "broken" (tests failing after refactor):
@@ -64,6 +87,7 @@ After all sub-stages are done, append a `### Build: Final` section to state.md.
 ```markdown
 ### Build: Final
 
+**Verdict:** complete | complete_with_issues
 **PR:** #<number> — <title>
 **PR URL:** <url>
 **Branch:** feature/<slug>

package/skills/wk-build/stages/commit.md

@@ -41,3 +41,11 @@ description: "Build sub-stage: Create clean commits, push branch, create PR."
 - If there are secrets or env files staged, remove them
 - Prefer multiple focused commits over one giant commit
 - PR description should be useful to a reviewer — not a wall of text
+
+## Anti-Rationalization
+
+| Excuse | Reality |
+|--------|---------|
+| "One big commit is fine for this feature" | Atomic commits make review possible, bisection useful, and reverts safe. A 500-line single commit is a review nightmare and an unrevertable blob. |
+| "The PR description can be minimal since reviewers have context" | Reviewers do not have your context. The PR description is the first thing they read — it determines whether they understand or misunderstand every line of your diff. |
+| "I'll clean up the commit history later" | You will not. Commit hygiene happens at commit time or not at all. Write the message as if you are explaining this change to someone six months from now. |

package/skills/wk-build/stages/core.md

@@ -46,3 +46,13 @@ description: "Build sub-stage: Make failing tests pass — service layer, API, b
 - Don't build UI yet — that's the UI sub-stage
 - If a test expectation seems wrong, fix the test only if the Blueprint supports it
 - Match existing code patterns exactly — naming, file structure, error handling
+
+## Anti-Rationalization
+
+| Excuse | Reality |
+|--------|---------|
+| "The Blueprint approach won't work, let me redesign" | Adapt, don't redesign. If the Blueprint truly cannot work, record a Deviation and make the minimal change needed. Full redesigns during Build invalidate the entire Plan phase. |
+| "I should add this extra feature while I'm here" | Scope creep disguised as efficiency. Every addition not in the Blueprint is untested, unreviewed, and unplanned. Add it to a follow-up task instead. |
+| "This pattern is better than what the codebase uses" | Consistency beats local optimization. The next developer expects the established pattern. Introduce new patterns in dedicated refactoring work, not mid-feature. |
+
+> **Note:** If you encounter `[redacted: N lines — @wk-ignore]` placeholders in source code, these blocks are intentionally hidden. Do not attempt to reconstruct or work around them.

package/skills/wk-build/stages/integration.md

@@ -42,3 +42,11 @@ description: "Build sub-stage: Wire everything together, verify full data flow e
 - Check TypeScript types across boundaries — mismatches here cause runtime bugs
 - If the dev server is available, actually navigate the flow
 - Document any issues found — they indicate gaps in the Blueprint for future reference
+
+## Anti-Rationalization
+
+| Excuse | Reality |
+|--------|---------|
+| "Unit tests passing means integration is fine" | Unit tests mock boundaries. Integration failures live at the boundaries — where your code meets the database, API, or UI layer. |
+| "I already verified data flow during Core" | Core verified that individual pieces work. Integration verifies they work together. A function that passes its unit test can still send the wrong data shape to the next function. |
+| "Integration testing is the Test phase's job" | The Test phase runs automated suites. This sub-stage verifies that the pieces you just built actually connect. Finding a wiring bug here takes 5 minutes; finding it in Test takes 30. |

package/skills/wk-build/stages/red.md

@@ -30,6 +30,8 @@ description: "Build sub-stage: Write failing tests BEFORE implementation (TDD re
 **Test Output:**
 <summary of test run — X tests, Y failing, Z passing (pre-existing)>
 
+**Coverage:** <N>/<total> criteria have failing tests
+
 **Criteria Coverage:**
 - "<criterion>" → tested by <test name>
 ```
@@ -42,3 +44,11 @@ description: "Build sub-stage: Write failing tests BEFORE implementation (TDD re
 - Existing tests must still pass — only NEW tests should fail
 - Match the project's existing test patterns and frameworks
 - If the project has no test framework set up, set one up as part of this step
+
+## Anti-Rationalization
+
+| Excuse | Reality |
+|--------|---------|
+| "Writing tests after implementation is more efficient" | Writing tests first defines the contract. Tests written after implementation test what you built, not what you should have built — they encode bugs as features. |
+| "The code is simple enough it doesn't need tests" | Simple code is the easiest to test. If you skip tests here, you will also skip them for complex code with a different excuse. The Red stage exists to build the safety net before you need it. |
+| "The Test phase will cover this" | The Test phase verifies the feature works end-to-end. Unit-level coverage must exist before that. Discovering a logic error in Test means rebuilding from Core. |

package/skills/wk-build/stages/refactor.md

@@ -27,6 +27,8 @@ description: "Build sub-stage: Improve code quality while keeping all tests gree
 **Refactoring Summary:**
 - <what was improved and why>
 
+**Changes Made:** <N> files touched
+**Tests:** before=<N> passing, after=<N> passing
 **Test Status:** passing | broken
 
 **If broken:**
@@ -46,3 +48,11 @@ description: "Build sub-stage: Improve code quality while keeping all tests gree
 - Don't refactor code you didn't write/modify in this feature
 - If code is already clean, say so and move on — don't refactor for its own sake
 - Small, incremental changes — not a big-bang rewrite
+
+## Anti-Rationalization
+
+| Excuse | Reality |
+|--------|---------|
+| "The code is fine as-is, nothing to refactor" | Fresh code always has cleanup opportunities — redundant variables, unclear names, duplicated logic. Read your code as if reviewing someone else's PR. |
+| "I should refactor this unrelated code too" | Refactor only touches code you wrote or modified in this feature. Unrelated refactoring expands the diff, makes review harder, and risks regressions in code you don't fully understand. |
+| "Tests are flaky, the refactoring didn't really break them" | If tests fail after refactoring, the refactoring changed behavior. Flaky tests that suddenly fail consistently are not flaky — they caught something. Investigate before dismissing. |

package/skills/wk-deploy/SKILL.md

@@ -42,6 +42,25 @@ This phase runs as a **fresh agent**. Read only these sections from `.work-kit/s
 - `### Build: Final` — PR URL, branch
 - `## Criteria` — for final confirmation
 
+## Boundaries
+
+### Always
+- Check CI status before merging
+- Rebase on the default branch before merging to catch integration issues
+- Verify the merge actually completed successfully
+- Monitor deployment status after merge (where applicable)
+
+### Ask First
+- Resolving non-trivial rebase conflicts (show conflicts to the user first)
+- Rolling back a deployment (except for data corruption or security — those are immediate)
+
+### Never
+- Force push to main or master
+- Merge with failing CI checks
+- Skip the rebase step to "save time"
+- Delete branches before confirming the merge succeeded
+- Proceed past a failed deployment without fixing or rolling back
+
 ## Final Output
 
 After all sub-stages are done, append a `### Deploy: Final` section to state.md. This is what **Wrap-up reads**.
@@ -49,6 +68,7 @@ After all sub-stages are done, append a `### Deploy: Final` section to state.md.
 ```markdown
 ### Deploy: Final
 
+**Verdict:** shipped | fix_needed | rolled_back
 **PR:** #<number>
 **Merge status:** merged | fix_needed | abort
 **Deploy status:** deployed | failed | not_applicable

package/skills/wk-deploy/stages/merge.md

@@ -35,8 +35,8 @@ description: "Deploy sub-stage: Get the PR merged safely."
 ```markdown
 ### Deploy: Merge
 
+**CI Status:** passing | failing | N/A
 **PR:** #<number>
-**CI Status:** passing | failing
 **Conflicts:** none | resolved
 **Merge Method:** squash | merge | rebase
 **Result:** merged | fix_needed | abort
@@ -57,3 +57,11 @@ description: "Deploy sub-stage: Get the PR merged safely."
 - Merge is fully autonomous — do NOT ask the user for permission at any step (review phase already approved it)
 - Push, create PR, and merge without stopping for confirmation
 - The entire sync → push → PR → merge flow should complete in one agent pass
+
+## Anti-Rationalization
+
+| Excuse | Reality |
+|--------|---------|
+| "CI is probably fine, no need to wait for the check" | "Probably" is not evidence. CI exists to catch what you missed. Wait for the green check — it takes minutes and prevents shipping broken code. |
+| "The conflict is trivial, I'll just force through" | Trivial conflicts still need manual resolution. Force-merging overwrites someone else's work. Resolve conflicts properly — if they are truly trivial, it takes 30 seconds. |
+| "Rebasing will mess up my history, better to merge directly" | A clean rebase on the default branch catches integration issues before they reach main. The few minutes spent rebasing prevent broken builds that affect the entire team. |

package/skills/wk-plan/SKILL.md

@@ -54,6 +54,8 @@ After all sub-stages are done, append a `### Plan: Final` section to state.md. T
 ```markdown
 ### Plan: Final
 
+**Verdict:** ready | revised_with_caveats
+
 **Blueprint:**
 <the full ordered implementation plan from Blueprint sub-stage — copy it here>
 
@@ -75,3 +77,24 @@ After all sub-stages are done, append a `### Plan: Final` section to state.md. T
 Then:
 - Update state: `**Phase:** plan (complete)`
 - Commit state: `git add .work-kit/ && git commit -m "work-kit: complete plan"`
+
+## Boundaries
+
+### Always
+- Read every file referenced in the Description before proposing solutions
+- Ask clarifying questions when requirements have multiple valid interpretations
+- Map blast radius by tracing actual code paths, not guessing from file names
+- Include exact file paths in Blueprint steps
+- Map every acceptance criterion to at least one Blueprint step
+
+### Ask First
+- Changing the scope after Clarify (user must approve scope changes)
+- Adding acceptance criteria the user did not request
+- Recommending a complexity rating of x-large (confirm before proceeding)
+
+### Never
+- Propose solutions during Clarify (that is Sketch's job)
+- Skip Investigate to "save time" — code understanding prevents rework
+- Write vague Blueprint steps like "update relevant files" without exact paths
+- Assume the codebase follows standard patterns without verifying in Investigate
+- Proceed past Audit with unresolved gaps in the Blueprint

package/skills/wk-plan/stages/audit.md

@@ -25,6 +25,12 @@ description: "Plan sub-stage: Audit the Blueprint for gaps, contradictions, and
 ### Plan: Audit
 
 **Result:** proceed | revise
+**Checklist:**
+- [ ] Every criterion maps to at least one Blueprint step
+- [ ] Every Blueprint step has exact file paths
+- [ ] Dependencies are ordered correctly
+- [ ] Error/edge cases are addressed
+- [ ] No scope creep beyond what Scope defined
 
 **Gaps Found:**
 - <gap description — or "None">
@@ -56,3 +62,11 @@ description: "Plan sub-stage: Audit the Blueprint for gaps, contradictions, and
 - "Proceed" means you'd bet money this plan works
 - "Revise" is not failure — it's the audit doing its job
 - Max 2 revision loops — after that, proceed with noted caveats
+
+## Anti-Rationalization
+
+| Excuse | Reality |
+|--------|---------|
+| "The Blueprint looks complete, proceed without nitpicking" | Audit exists because plans always have gaps. If you cannot find any, you are not looking hard enough — check criterion coverage, missing error paths, and dependency order. |
+| "Revising would waste time, the gaps are minor" | A 'minor' gap in the plan becomes a major blocker in Build. Sending back to Blueprint now costs minutes; discovering the gap mid-implementation costs hours. |
+| "I already wrote the Blueprint, so I know it's correct" | Self-review bias is real. Audit requires you to read the Blueprint as if someone else wrote it. Check each criterion against the steps — does every criterion have a step that delivers it? |

package/skills/wk-plan/stages/blueprint.md

@@ -58,3 +58,11 @@ description: "Plan sub-stage: Produce a full ordered step-by-step implementation
 - If a step is "update 5 files", break it into 5 steps
 - The Blueprint is the contract — Build phase follows it literally
 - Include commands to run (migrations, test commands) as steps
+
+## Anti-Rationalization
+
+| Excuse | Reality |
+|--------|---------|
+| "High-level steps are sufficient, exact paths aren't needed" | Vague steps like "update the API" become ambiguous during Build. Exact file paths eliminate guesswork and prevent the wrong file from being modified. |
+| "The Architecture section already covers the implementation plan" | Architecture describes structure. Blueprint describes execution order. Without a step-by-step plan, the Build agent will invent its own order — often wrong. |
+| "Adding more detail will just slow things down" | A detailed Blueprint is the single highest-leverage artifact in the entire pipeline. Every minute here saves ten in Build. |

package/skills/wk-plan/stages/clarify.md

@@ -59,3 +59,11 @@ Update the `## Criteria` section with acceptance criteria, then append:
 - **Do ask questions** — ambiguity caught here saves hours later
 - If the request is crystal clear, don't invent questions just to ask them
 - Ask questions only when the answer materially changes what gets built
+
+## Anti-Rationalization
+
+| Excuse | Reality |
+|--------|---------|
+| "The request is clear enough, no questions needed" | Ambiguity hides in assumptions. One clarifying question now prevents a wrong turn that wastes an entire Build phase. |
+| "I should start reading code to understand better" | That is Investigate's job. Clarify defines *what* to build; Investigate discovers *how*. Mixing them leads to solution-driven requirements. |
+| "Acceptance criteria can be refined later" | Vague criteria produce vague implementations. If you cannot write a testable criterion now, you do not understand the request yet. |

package/skills/wk-plan/stages/investigate.md

@@ -45,3 +45,13 @@ description: "Plan sub-stage: Read codebase systematically, trace paths, map bla
 - Do NOT propose solutions yet — that's Sketch
 - Note file paths precisely — these will be referenced in Blueprint
 - If the codebase has no tests for affected areas, note that as a risk
+
+## Anti-Rationalization
+
+| Excuse | Reality |
+|--------|---------|
+| "I already understand the codebase from the description" | You understand the *intent*, not the *implementation*. Blast radius, existing patterns, and hidden dependencies live in the code, not the request. |
+| "Checking more files would waste context" | Skipping investigation wastes far more context when you discover mid-Build that your assumptions were wrong and must restart. |
+| "The blast radius is obvious, no need to trace paths" | Obvious blast radius is the most common source of missed side-effects. Trace the actual call chain — surprises live one hop beyond what seems obvious. |
+
+> **Note:** If you encounter `[redacted: N lines — @wk-ignore]` placeholders in source code, these blocks are intentionally hidden. Do not attempt to reconstruct or work around them.

package/skills/wk-plan/stages/scope.md

@@ -44,3 +44,11 @@ description: "Plan sub-stage: Define in/out scope, estimate complexity, refine c
 - If Clarify criteria are too vague, sharpen them now
 - "Out of scope" is a decision, not a deferral — explain why
 - Complexity estimate should factor in blast radius from Investigate
+
+## Anti-Rationalization
+
+| Excuse | Reality |
+|--------|---------|
+| "Everything is in scope, no need to exclude anything" | Unbounded scope is how features balloon. Explicitly listing what is out of scope prevents drift during Build. |
+| "This is too small to scope formally" | Small tasks with unclear boundaries grow silently. A 2-line scope section costs nothing and prevents "while I'm here" additions. |
+| "The scope is implied by the acceptance criteria" | Criteria say what must work. Scope says what you will and will not touch. A criterion can be met many ways — scope constrains which way. |

package/skills/wk-review/SKILL.md

@@ -64,6 +64,27 @@ Each writes its own `### Review: <sub-stage>` section to state.md.
 
 **Handoff agent** reads all 4 review sections + Test: Final → makes the ship decision.
 
+## Boundaries
+
+### Always
+- Read the full git diff before making any review judgments
+- Fix issues directly when fixable in under 5 minutes
+- Run the test suite after any fixes made during review
+- Check every Blueprint step in the Compliance review
+- Produce a clear ship/no-ship verdict with specific reasoning
+
+### Ask First
+- Approving with known failing criteria (explain which and why acceptable)
+- Rejecting a PR (confirm the fundamental problem is not fixable)
+- Making architectural changes during review
+
+### Never
+- Approve a PR with critical or high severity security issues
+- Approve without checking acceptance criteria status
+- Rubber-stamp without reading the diff ("looks good" is not a review)
+- Make changes_requested without specifying exactly what needs to change
+- Skip any of the 4 parallel review sub-stages
+
 ## Final Output
 
 After Handoff completes, append a `### Review: Final` section to state.md. This is what **Deploy and Wrap-up read**.
@@ -71,7 +92,7 @@ After Handoff completes, append a `### Review: Final` section to state.md. This
 ```markdown
 ### Review: Final
 
-**Decision:** approved | changes_requested | rejected
+**Verdict:** approved | changes_requested | rejected
 
 **Summary:** <1-2 sentences — overall assessment>
 

package/skills/wk-review/stages/compliance.md

@@ -28,9 +28,9 @@ description: "Review sub-stage: Compare final code against Blueprint."
 
 **Result:** compliant | deviations_found
 
-**Blueprint Steps:**
-- Step 1: <implemented | deviated | missing>
-- Step 2: <implemented | deviated | missing>
+**Blueprint Steps:** (every step MUST appear with a status)
+- Step 1: <done | deviated | skipped>
+- Step 2: <done | deviated | skipped>
 - ...
 
 **Deviations:**
@@ -46,3 +46,11 @@ description: "Review sub-stage: Compare final code against Blueprint."
 - But deviations need justification — "I felt like it" is not acceptable
 - Missing steps are a red flag — they need to be implemented or explicitly dropped with reason
 - Scope creep should be called out even if the extra code is good
+
+## Anti-Rationalization
+
+| Excuse | Reality |
+|--------|---------|
+| "The deviations are improvements over the Blueprint" | Improvements still need documentation. If the implementation differs from the plan, record why — future readers need to know the deviation was intentional, not accidental. |
+| "The Blueprint was wrong, so compliance doesn't apply" | If the Blueprint was wrong, that is itself a finding worth recording. Compliance review catches plan-vs-reality drift — both accidental deviations and deliberate corrections need documentation. |
+| "Minor scope additions don't count as scope creep" | Minor additions compound. Each one is "just a small thing" until the PR is 3x the original scope. If it was not in the Blueprint, it is scope creep — document it as a Deviation. |

package/skills/wk-review/stages/handoff.md

@@ -35,6 +35,9 @@ description: "Review sub-stage: Finalize PR, make ship/no-ship decision."
 **Concerns:**
 - <any remaining concerns — or "None">
 
+**Criteria Met:** <N>/<total>
+**Blockers:** <N> (list each if > 0)
+
 **Decision:** approved | changes_requested | rejected
 
 **If changes_requested:**
@@ -57,3 +60,11 @@ description: "Review sub-stage: Finalize PR, make ship/no-ship decision."
 - Don't block on cosmetic issues — fix them directly before finalizing
 - The PR should be ready for a human reviewer after this step
 - If you're unsure between approved and changes_requested, ask the user
+
+## Anti-Rationalization
+
+| Excuse | Reality |
+|--------|---------|
+| "Changes_requested would slow things down, it's good enough" | Shipping known issues to "save time" moves the cost to production users and the next developer. Requesting changes now is faster than a hotfix later. |
+| "The gaps are minor, we can fix them after merge" | After merge, the context is gone, the branch is deleted, and the priority shifts. Post-merge fixes have a completion rate near zero. Fix it now or accept it will never be fixed. |
+| "Requesting changes will frustrate the developer" | A clear, specific change request is more respectful than silently approving broken code. Developers prefer honest feedback over discovering issues in production. |

package/skills/wk-review/stages/performance.md

@@ -27,6 +27,7 @@ Fix what you can. Document what needs deeper investigation.
 ```markdown
 ### Review: Performance
 
+**Verdict:** clear | issues_noted
 **Findings:**
 - <finding — or "None">
 

package/skills/wk-review/stages/security.md

@@ -29,6 +29,9 @@ Fix issues directly when possible. Document what you can't fix.
 ```markdown
 ### Review: Security
 
+> **Note:** If you encounter `[redacted: N lines — @wk-ignore]` placeholders, these blocks are excluded from security review. If you suspect a security issue may exist within a redacted area, flag it for human review rather than attempting to reconstruct the code.
+
+**Verdict:** clear | risks_noted | blocked
 **Findings:**
 - <finding with severity: critical/high/medium/low — or "None">
 
@@ -47,3 +50,11 @@ Fix issues directly when possible. Document what you can't fix.
 - Not every feature touches all 10 categories — skip irrelevant ones
 - Don't add security theater (unnecessary complexity for non-existent threats)
 - If you find a critical issue, fix it immediately and note it prominently
+
+## Anti-Rationalization
+
+| Excuse | Reality |
+|--------|---------|
+| "This feature doesn't touch auth, so there are no security concerns" | Security is not just authentication. Input validation, data exposure, injection, CSRF, and insecure defaults exist in every feature that handles user data or external input. |
+| "Input validation is handled elsewhere" | Verify that claim. "Handled elsewhere" is the most common source of security gaps — each layer assumes another layer validates. Check the actual validation at every boundary. |
+| "This is internal-only, security doesn't matter" | Internal APIs become external when architectures change. Internal networks get compromised. Treat every input as potentially hostile — the cost of basic validation is negligible. |

package/skills/wk-review/stages/self-review.md

@@ -27,6 +27,9 @@ description: "Review sub-stage: Review your own diff for obvious issues."
 ```markdown
 ### Review: Self-Review
 
+> **Note:** If you encounter `[redacted: N lines — @wk-ignore]` placeholders in source code, these blocks are intentionally hidden. Do not attempt to reconstruct or work around them.
+
+**Verdict:** clean | issues_remain
 **Issues Found:** <N>
 **Issues Fixed:** <M>
 **Remaining Concerns:**
@@ -39,3 +42,11 @@ description: "Review sub-stage: Review your own diff for obvious issues."
 - Remove ALL debug code (console.log, debugger statements, etc.)
 - This is about catching careless mistakes, not redesigning the architecture
 - Be honest — pretending your code is perfect helps no one
+
+## Anti-Rationalization
+
+| Excuse | Reality |
+|--------|---------|
+| "My code is already clean, nothing to review" | You wrote it minutes ago — you cannot objectively review your own fresh code. Read it as if someone else wrote it. Look for naming issues, missing error handling, and unclear logic. |
+| "These are minor style issues, not worth fixing" | Accumulated minor issues make code hard to read and maintain. Fix them now while the context is fresh — they take seconds each but compound into significant tech debt. |
+| "The linter didn't flag anything, so the code is fine" | Linters catch syntax and formatting. They do not catch unclear names, missing edge cases, redundant logic, or poor abstractions. Self-review catches what linters cannot. |

package/skills/wk-test/SKILL.md

@@ -53,6 +53,25 @@ Agent: E2E    ──┘
 
 Each sub-agent reads the same Context Input sections and writes its own `### Test: <sub-stage>` section to state.md.
 
+## Boundaries
+
+### Always
+- Run the full test suite, not just new tests
+- Provide explicit evidence for every satisfied criterion (test name, output, or code reference)
+- Report honest confidence levels — do not inflate confidence
+- Fix regressions immediately rather than documenting them for later
+
+### Ask First
+- Marking a criterion as "not testable" (explain why and get confirmation)
+- Changing or reinterpreting acceptance criteria discovered during testing
+- Disabling or modifying pre-existing tests
+
+### Never
+- Skip failing tests or disable them to make the suite pass
+- Claim a criterion is satisfied without specific evidence
+- Write E2E tests that test implementation details rather than user behavior
+- Modify feature code during Test phase (report issues, don't fix)
+
 ## Final Output
 
 After all sub-stages are done, append a `### Test: Final` section to state.md. This is what **Review agents read**.
@@ -60,6 +79,7 @@ After all sub-stages are done, append a `### Test: Final` section to state.md. T
 ```markdown
 ### Test: Final
 
+**Verdict:** pass | gaps_found
 **Suite status:** all passing | <N> failures
 **Total tests:** <count> (passing: <N>, failing: <N>)
 

package/skills/wk-test/stages/e2e.md

@@ -22,6 +22,7 @@ description: "Test sub-stage: Test user flows end-to-end."
 ```markdown
 ### Test: E2E
 
+**Verdict:** pass | fail
 **Tests Written:**
 - `<test file>`: <flow description>
 
@@ -42,3 +43,11 @@ description: "Test sub-stage: Test user flows end-to-end."
 - Focus on user-visible behavior, not internal implementation
 - Screenshots are evidence — capture them for key states
 - If a flow fails, fix the implementation (not the test) unless the test expectation is wrong
+
+## Anti-Rationalization
+
+| Excuse | Reality |
+|--------|---------|
+| "Manual verification counts as E2E testing" | Manual verification is not repeatable, not documented, and not run in CI. If you cannot automate it, at minimum document the exact manual steps with expected results. |
+| "Unit tests already cover this flow" | Unit tests mock boundaries. E2E tests verify the real flow across boundaries — database, API, UI. A function can pass its unit test and still fail in the real pipeline. |
+| "E2E tests are slow and fragile, not worth the effort" | Slow tests that catch real bugs are more valuable than fast tests that miss them. Write focused E2E tests for critical paths, not exhaustive ones for every edge case. |

package/skills/wk-test/stages/validate.md

@@ -32,6 +32,7 @@ Also append:
 ```markdown
 ### Test: Validate
 
+**Verdict:** pass | gaps_found
 **Criteria Status:**
 - Satisfied: <N> / <total>
 - Gaps: <list of unsatisfied criteria>
@@ -49,3 +50,11 @@ Also append:
 - If a criterion is genuinely not testable, explain why
 - Low confidence should trigger concern in the Review phase
 - Criteria should not change during Test — if a new criterion is discovered, note it but don't add it to the checklist mid-test
+
+## Anti-Rationalization
+
+| Excuse | Reality |
+|--------|---------|
+| "The test suite passing counts as evidence for all criteria" | A passing suite proves the tests pass, not that the criteria are met. Each criterion needs a specific test or evidence mapped to it — "tests pass" is not a mapping. |
+| "This criterion is obviously satisfied, no explicit evidence needed" | If it is obvious, it is easy to provide evidence. If you cannot point to specific evidence, the criterion might not actually be met — your confidence is based on assumption, not proof. |
+| "Low confidence is fine because the tests pass" | Low confidence means you are not sure the criterion is met. That is a signal to investigate further, not to accept and move on. The purpose of Validate is to resolve uncertainty, not document it. |

package/skills/wk-test/stages/verify.md

@@ -24,6 +24,7 @@ description: "Test sub-stage: Run existing test suite, check for regressions."
 ```markdown
 ### Test: Verify
 
+**Verdict:** pass | fail
 **Suite Result:** pass | fail
 **Total Tests:** <N> passing, <M> failing
 **Regressions Found:**
@@ -39,3 +40,11 @@ description: "Test sub-stage: Run existing test suite, check for regressions."
 - Do NOT disable tests to make the suite pass
 - If a pre-existing test fails and it's a legitimate behavior change, update the test with a comment explaining why
 - Run the suite at least twice — once to find issues, once to confirm fixes
+
+## Anti-Rationalization
+
+| Excuse | Reality |
+|--------|---------|
+| "Disabling this flaky test is easier than fixing it" | Disabling tests erodes the safety net. A flaky test is a test with a real problem — intermittent failures often reveal race conditions or state leaks that will bite production. |
+| "The failing test was testing the old behavior" | Then update the test to match the new behavior and verify the update is intentional. Deleting a test because it fails is destroying evidence — it might be catching a real regression. |
+| "All tests pass, so everything works" | Tests only prove what they test. Check the criteria — does each one have a test that would fail if the criterion were not met? Passing tests with missing coverage is a false sense of security. |

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

@@ -63,6 +63,24 @@ status: <completed | partial | rolled-back>
 - Internal process notes ("ran tests 3 times before they passed")
 - Anything derivable from the git diff or PR description
 
+## Boundaries
+
+### Always
+- Read the full state.md before writing the summary
+- Include every non-obvious decision in the Key Decisions section
+- Include every deviation from the Blueprint in the Deviations section
+- Write the archive to the main branch, not the worktree
+
+### Ask First
+- Deleting the worktree and feature branch (confirm with user)
+- Omitting sections from the summary
+
+### Never
+- Copy-paste full phase outputs into the summary (distill, don't dump)
+- Include routine implementation details (file lists, command logs)
+- Skip the criteria checklist in the summary
+- Commit the archive on the feature branch instead of main
+
 ## Cleanup
 
 After writing the summary: