@abdullahsahmad/work-kit 0.1.2 → 0.1.4

package/cli/src/commands/complete.ts

@@ -1,9 +1,11 @@
-import { readState, writeState, findWorktreeRoot } from "../state/store.js";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { readState, writeState, findWorktreeRoot, readStateMd } from "../state/store.js";
 import { isPhaseComplete } from "../engine/transitions.js";
 import { checkLoopback } from "../engine/loopbacks.js";
 import { PHASE_ORDER } from "../config/phases.js";
 import { parseLocation, resetToLocation } from "../state/helpers.js";
-import type { Action, PhaseName } from "../state/schema.js";
+import type { Action, PhaseName, WorkKitState } from "../state/schema.js";
 
 export function completeCommand(target: string, outcome?: string, worktreeRoot?: string): Action {
   const root = worktreeRoot || findWorktreeRoot();
@@ -101,6 +103,7 @@ export function completeCommand(target: string, outcome?: string, worktreeRoot?:
       state.currentPhase = null;
       state.currentSubStage = null;
       writeState(root, state);
+      archiveCompleted(root, state);
       return { action: "complete", message: "All phases complete. Work-kit finished." };
     }
 
@@ -121,3 +124,40 @@ export function completeCommand(target: string, outcome?: string, worktreeRoot?:
     message: `${phase}/${subStage} complete${outcome ? ` (outcome: ${outcome})` : ""}. Run \`npx work-kit next\` to continue.`,
   };
 }
+
+// ── Archive on completion ──────────────────────────────────────────
+
+function archiveCompleted(worktreeRoot: string, state: WorkKitState): void {
+  const mainRoot = state.metadata.mainRepoRoot || worktreeRoot;
+  const date = new Date().toISOString().split("T")[0];
+  const slug = state.slug;
+  const wkDir = path.join(mainRoot, ".claude", "work-kit");
+  const archiveDir = path.join(wkDir, "archive");
+
+  // Ensure directories exist
+  fs.mkdirSync(archiveDir, { recursive: true });
+
+  // Archive state.md
+  const stateMd = readStateMd(worktreeRoot);
+  if (stateMd) {
+    const archivePath = path.join(archiveDir, `${date}-${slug}.md`);
+    fs.writeFileSync(archivePath, stateMd, "utf-8");
+  }
+
+  // Compute completed phases
+  const completedPhases = PHASE_ORDER
+    .filter(p => state.phases[p].status === "completed")
+    .join("→");
+
+  // Append to index.md
+  const indexPath = path.join(wkDir, "index.md");
+  let indexContent = "";
+  if (fs.existsSync(indexPath)) {
+    indexContent = fs.readFileSync(indexPath, "utf-8");
+  }
+  if (!indexContent.includes("| Date ")) {
+    indexContent = "| Date | Slug | PR | Status | Phases |\n| --- | --- | --- | --- | --- |\n";
+  }
+  indexContent += `| ${date} | ${slug} | n/a | completed | ${completedPhases} |\n`;
+  fs.writeFileSync(indexPath, indexContent, "utf-8");
+}

package/cli/src/commands/init.ts

@@ -154,7 +154,7 @@ export function initCommand(options: {
     version: 1,
     slug,
     branch,
-    started: new Date().toISOString().split("T")[0],
+    started: new Date().toISOString(),
     mode: modeLabel,
     ...(classification && { classification }),
     status: "in-progress",

package/cli/src/observer/data.ts

@@ -101,16 +101,18 @@ export function collectWorkItem(worktreeRoot: string): WorkItemView | null {
 
     const subStageKeys = Object.keys(phase.subStages);
     if (subStageKeys.length === 0) {
-      // Use default substages
+      // Use default substages — skip entirely skipped phases
+      if (phase.status === "skipped") continue;
       const defaults = SUBSTAGES_BY_PHASE[phaseName] || [];
       total += defaults.length;
       if (phase.status === "completed") completed += defaults.length;
-      else if (phase.status === "skipped") completed += defaults.length;
     } else {
       for (const key of subStageKeys) {
-        total++;
         const sub = phase.subStages[key];
-        if (sub.status === "completed" || sub.status === "skipped") {
+        // Skip excluded substages — they shouldn't affect progress
+        if (sub.status === "skipped") continue;
+        total++;
+        if (sub.status === "completed") {
           completed++;
         }
       }
@@ -172,20 +174,34 @@ export function collectCompletedItems(mainRepoRoot: string): CompletedItemView[]
 
   const items: CompletedItemView[] = [];
   // Parse markdown table or list entries
-  // Expected format: | slug | PR | date | phases |
+  // Format: | Date | Slug | PR | Status | Phases |
   // or list format: - slug (#PR) - date - phases
   const lines = content.split("\n");
   for (const line of lines) {
-    // Try table format: | slug | #PR | date | phases |
-    const tableMatch = line.match(/^\|\s*(.+?)\s*\|\s*(#?\d+)?\s*\|\s*(.+?)\s*\|\s*(.+?)\s*\|/);
-    if (tableMatch) {
-      const slug = tableMatch[1].trim();
-      if (slug === "Slug" || slug === "---" || slug.startsWith("-")) continue; // skip header
+    // Try 5-column table: | Date | Slug | PR | Status | Phases |
+    const table5Match = line.match(/^\|\s*(.+?)\s*\|\s*(.+?)\s*\|\s*(.+?)\s*\|\s*(.+?)\s*\|\s*(.+?)\s*\|/);
+    if (table5Match) {
+      const col1 = table5Match[1].trim();
+      if (col1 === "Date" || col1 === "---" || col1.startsWith("-")) continue; // skip header
+      items.push({
+        slug: table5Match[2].trim(),
+        pr: table5Match[3].trim() !== "n/a" ? table5Match[3].trim() : undefined,
+        completedAt: col1,
+        phases: table5Match[5].trim(),
+      });
+      continue;
+    }
+
+    // Try 4-column table: | slug | PR | date | phases |
+    const table4Match = line.match(/^\|\s*(.+?)\s*\|\s*(#?\d+)?\s*\|\s*(.+?)\s*\|\s*(.+?)\s*\|/);
+    if (table4Match) {
+      const slug = table4Match[1].trim();
+      if (slug === "Slug" || slug === "---" || slug.startsWith("-")) continue;
       items.push({
         slug,
-        pr: tableMatch[2]?.trim() || undefined,
-        completedAt: tableMatch[3].trim(),
-        phases: tableMatch[4].trim(),
+        pr: table4Match[2]?.trim() || undefined,
+        completedAt: table4Match[3].trim(),
+        phases: table4Match[4].trim(),
       });
       continue;
     }
@@ -210,10 +226,22 @@ export function collectCompletedItems(mainRepoRoot: string): CompletedItemView[]
 export function collectDashboardData(mainRepoRoot: string, cachedWorktrees?: string[]): DashboardData {
   const worktrees = cachedWorktrees ?? discoverWorktrees(mainRepoRoot);
   const activeItems: WorkItemView[] = [];
+  const completedFromWorktrees: CompletedItemView[] = [];
 
   for (const wt of worktrees) {
     const item = collectWorkItem(wt);
-    if (item && item.status !== "completed") {
+    if (!item) continue;
+    if (item.status === "completed") {
+      const phaseNames = item.phases
+        .filter(p => p.status === "completed")
+        .map(p => p.name)
+        .join("→");
+      completedFromWorktrees.push({
+        slug: item.slug,
+        completedAt: item.startedAt,
+        phases: phaseNames,
+      });
+    } else {
       activeItems.push(item);
     }
   }
@@ -227,7 +255,13 @@ export function collectDashboardData(mainRepoRoot: string, cachedWorktrees?: str
     return new Date(b.startedAt).getTime() - new Date(a.startedAt).getTime();
   });
 
-  const completedItems = collectCompletedItems(mainRepoRoot);
+  // Merge completed items from worktrees and index file, dedup by slug
+  const indexItems = collectCompletedItems(mainRepoRoot);
+  const seen = new Set(completedFromWorktrees.map(i => i.slug));
+  const completedItems = [
+    ...completedFromWorktrees,
+    ...indexItems.filter(i => !seen.has(i.slug)),
+  ];
 
   return {
     activeItems,

package/cli/src/observer/renderer.ts

@@ -8,12 +8,23 @@ function formatTimeAgo(dateStr: string): string {
   const then = new Date(dateStr).getTime();
   if (isNaN(then)) return "unknown";
 
+  // If only a date (no time component), show the date string as-is
+  // to avoid misleading hour-level precision
+  const isDateOnly = /^\d{4}-\d{2}-\d{2}$/.test(dateStr);
+
   const diffMs = now - then;
   const minutes = Math.floor(diffMs / 60000);
   const hours = Math.floor(diffMs / 3600000);
   const days = Math.floor(diffMs / 86400000);
   const weeks = Math.floor(days / 7);
 
+  if (isDateOnly) {
+    if (days < 1) return "today";
+    if (days === 1) return "yesterday";
+    if (days < 7) return `${days}d ago`;
+    return `${weeks}w ago`;
+  }
+
   if (minutes < 1) return "just now";
   if (minutes < 60) return `${minutes}m ago`;
   if (hours < 24) {

package/cli/src/observer/watcher.ts

@@ -27,12 +27,17 @@ export function startWatching(
 
   function watchStateFile(worktreeRoot: string): void {
     if (watchers.has(worktreeRoot)) return;
-    const stateFile = path.join(worktreeRoot, ".work-kit", "state.json");
-    if (!fs.existsSync(stateFile)) return;
+    const stateDir = path.join(worktreeRoot, ".work-kit");
+    if (!fs.existsSync(stateDir)) return;
 
     try {
-      const watcher = fs.watch(stateFile, { persistent: false }, () => {
-        debouncedUpdate();
+      // Watch the directory, not the file — writeState uses atomic
+      // rename (write tmp + rename), which replaces the inode and
+      // breaks fs.watch on the file on Linux.
+      const watcher = fs.watch(stateDir, { persistent: false }, (_event, filename) => {
+        if (filename === "state.json") {
+          debouncedUpdate();
+        }
       });
       watcher.on("error", () => {
         watcher.close();
@@ -40,7 +45,7 @@ export function startWatching(
       });
       watchers.set(worktreeRoot, watcher);
     } catch {
-      // File might not exist yet
+      // Directory might not exist yet
     }
   }
 

package/package.json

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

package/skills/deploy/SKILL.md

@@ -23,7 +23,7 @@ For each sub-stage:
 
 ## Key Principle
 
-**Verify before acting, monitor after acting.** Never merge without checking CI. Never walk away after merge without checking deployment.
+**Verify before acting, monitor after acting.** Never merge with failing CI. Merge is automatic after review approval — no user confirmation needed. Never walk away after merge without checking deployment.
 
 ## Recording
 

package/skills/deploy/stages/merge.md

@@ -9,16 +9,26 @@ description: "Deploy sub-stage: Get the PR merged safely."
 
 ## Instructions
 
-1. Check CI status on the PR — all checks must pass
-2. Check for merge conflicts — resolve if any
-3. Rebase on main if the branch is behind
-4. Post a readiness summary as a PR comment:
-   - Tests: pass/fail
-   - Review: approved
-   - Conflicts: none/resolved
-   - Risk: low/medium/high
-5. **Prepare a merge readiness summary** and return it to the orchestrator for user approval — don't auto-merge
-6. Once the orchestrator confirms user approval, merge using the project's preferred method (check CONTRIBUTING.md or README for merge preferences; default to squash if unspecified)
+1. Determine the default branch (`main` or `master`):
+   ```bash
+   git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@' || echo "main"
+   ```
+2. Sync the feature branch with the default branch:
+   ```bash
+   git fetch origin
+   git rebase origin/<default-branch>
+   ```
+   If rebase conflicts occur, resolve them. If they're non-trivial, report to the user and abort.
+3. If a PR exists, check CI status — all checks must pass. If CI fails, diagnose and fix (loop back to Build if needed).
+4. Merge automatically using the project's preferred method (check CONTRIBUTING.md or README; default to squash):
+   - If a PR exists: merge via `gh pr merge --squash --delete-branch`
+   - If no PR: merge locally:
+     ```bash
+     git checkout <default-branch>
+     git merge --squash feature/<slug>
+     git commit -m "feat: <slug>"
+     git branch -d feature/<slug>
+     ```
 
 ## Output (append to state.md)
 
@@ -40,8 +50,8 @@ description: "Deploy sub-stage: Get the PR merged safely."
 
 ## Rules
 
-- NEVER force push to main
+- NEVER force push to main/master
 - NEVER merge with failing CI
-- ALWAYS return to the orchestrator for user approval before merging
 - If CI fails, diagnose the issue — don't just retry
-- If conflicts are non-trivial, explain them to the user before resolving
+- If rebase conflicts are non-trivial, explain them to the user before resolving
+- Merge is automatic — do NOT ask the user for permission (review phase already approved it)

package/skills/wrap-up/SKILL.md

@@ -12,12 +12,12 @@ allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 
 ## Instructions
 
+> **Note:** Archiving state.md and appending to `.claude/work-kit/index.md` are handled automatically by the CLI when you run `work-kit complete` on the last sub-stage. You do NOT need to do these manually.
+
 1. **Read the full `.work-kit/state.md`** — every phase output from Plan through the last completed phase
-2. **Archive the full state** — copy `.work-kit/state.md` to `.claude/work-kit/archive/<YYYY-MM-DD>-<slug>.md` on the **main branch** (this is the unedited, complete record)
-3. **Synthesize the work-kit log entry** — not a copy-paste of state, but a distilled record that a future developer (or agent) would find useful
-4. **Write the summary file** to `.claude/work-kit/<date>-<slug>.md` on the **main branch** (not the worktree)
-5. **Append to the index** in `.claude/work-kit/index.md`
-6. **Ask the user** if they want the worktree removed
+2. **Synthesize the work-kit log entry** — not a copy-paste of state, but a distilled record that a future developer (or agent) would find useful
+3. **Write the summary file** to `.claude/work-kit/<date>-<slug>.md` on the **main branch** (not the worktree)
+4. **Ask the user** if they want the worktree and branch removed
 
 ## Work-Kit Log Entry Format
 
@@ -48,14 +48,6 @@ status: <completed | partial | rolled-back>
 - <what changed and why>
 ```
 
-## Index Entry
-
-Append one row to `.claude/work-kit/index.md`:
-
-```
-| <YYYY-MM-DD> | <slug> | <#PR or n/a> | <completed/partial/rolled-back> | <phases completed, e.g. "all 6" or "plan→review (no deploy)"> |
-```
-
 ## What to Include vs. Exclude
 
 **Include:**
@@ -71,27 +63,9 @@ Append one row to `.claude/work-kit/index.md`:
 - Internal process notes ("ran tests 3 times before they passed")
 - Anything derivable from the git diff or PR description
 
-## Archive
-
-The archive is the full, unedited copy of `.work-kit/state.md` — every phase output, every decision, every deviation. It exists so you can always go back to the complete record.
-
-When archiving, prepend a reference header to the copy so the archive knows where its summary lives:
-
-```markdown
-> **Summary:** [<YYYY-MM-DD>-<slug>](../<YYYY-MM-DD>-<slug>.md)
-
-<rest of state.md content>
-```
-
-```bash
-# From the worktree, copy state to the archive on main
-cp .work-kit/state.md <main-repo-root>/.claude/work-kit/archive/<YYYY-MM-DD>-<slug>.md
-# Then prepend the summary reference to the archive file
-```
-
 ## Cleanup
 
-After writing the archive, summary, and index:
+After writing the summary:
 
 1. Switch to main branch: `cd` back to the main repo root
 2. Stage and commit all work-kit log files:
@@ -99,9 +73,10 @@ After writing the archive, summary, and index:
    git add .claude/work-kit/
    git commit -m "work-kit: <slug>"
    ```
-3. Ask the user: "Remove the worktree `worktrees/<slug>`?"
+3. Ask the user: "Remove the worktree `worktrees/<slug>` and delete branch `feature/<slug>`?"
 4. If yes:
    ```bash
    git worktree remove worktrees/<slug>
+   git branch -d feature/<slug>
    ```
-5. Report: summary written, worktree status, done.
+5. Report: summary written, worktree removed, branch deleted, done.