@tianhai/pi-workflow-kit 0.8.0 → 0.8.2

package/docs/plans/2026-04-21-workflow-guard-safe-commands-design.md

@@ -0,0 +1,172 @@
+# Workflow Guard: Safe Commands Expansion
+
+**Date:** 2026-04-21
+**Status:** Draft
+
+## Problem
+
+The workflow guard blocks several read-only bash commands that are genuinely needed during brainstorm and plan phases. Two specific user reports:
+
+1. `cd /path && git remote -v 2>/dev/null; echo "---"; ls` — blocked due to `cd` not being allowlisted and `2>/dev/null` caught by the stdout-redirect pattern.
+2. `gh pr view 1564 --json ... 2>/dev/null || echo "gh failed"` — blocked because `gh` is not allowlisted at all.
+
+Additionally, `git status --short` is blocked because the safe regex only allows `git status` without flags.
+
+## Design
+
+### 1. Harmless redirect stripping
+
+Add a `stripHarmlessRedirects(cmd)` helper that removes `2>/dev/null` and `2>&1` before pattern matching. These are purely cosmetic (suppress stderr noise) and have no side effects.
+
+```ts
+function stripHarmlessRedirects(cmd: string): string {
+  return cmd.replace(/\s*2\s*>\s*(\/dev\/null|&1)\b/g, "");
+}
+```
+
+Apply it inside `isSafeCommand` on each sub-command before checking DESTRUCTIVE and SAFE patterns. This fixes `2>/dev/null` without loosening the redirect catch (which still blocks real writes).
+
+### 2. New SAFE_PATTERNS entries
+
+| Pattern | Rationale |
+|---------|-----------|
+| `/^\s*cd\b/` | Directory navigation — zero side effects |
+| `/^\s*gh\s+pr\s+(view\|list\|diff\|checks\|status)\b/i` | Read-only PR inspection |
+| `/^\s*gh\s+issue\s+(view\|list)\b/i` | Read-only issue inspection |
+| `/^\s*gh\s+repo\s+(view\|fork\|list)\b/i` | Read-only repo metadata |
+| `/^\s*gh\s+release\s+(view\|list\|download)\b/i` | Read-only release inspection |
+| `/^\s*gh\s+run\s+(view\|list)\b/i` | Read-only CI run inspection |
+| `/^\s*git\s+blame\b/` | Read-only file annotation |
+| `/^\s*git\s+shortlog\b/` | Read-only commit summary |
+| `/^\s*git\s+stash\s+list\b/i` | Read-only stash listing |
+| `/^\s*git\s+tag\s+(-l\|--list)\b/i` | Read-only tag listing |
+| `/^\s*git\s+describe\b/` | Read-only version info |
+
+### 3. Fix: `git status` flag handling
+
+Current regex `/^\s*git\s+(status|log|...)/i` doesn't allow common flags like `--short`, `--oneline`, `--format=...`. Refine all git safe patterns to optionally accept trailing flags and args:
+
+```ts
+/^\s*git\s+status\b/i,
+/^\s*git\s+log\b/i,
+/^\s*git\s+diff\b/i,
+/^\s*git\s+show\b/i,
+/^\s*git\s+blame\b/i,
+// etc.
+```
+
+The existing patterns already anchor to `^\s*git\s+<subcommand>` — the issue was that `git status --short` didn't match because some patterns had more restrictive anchoring. Reviewing the code: the patterns use `\b` word boundaries which should allow flags. The actual issue with `git status --short && git log --oneline -5` is that the `git log --oneline -5` part is safe, but `git status --short` — let me verify: `/^\s*git\s+(status|log|diff|show|branch|remote|config\s+--get)/i` — `git status` has a `\b` after the group? No, there's no trailing `\b`. So `git status --short` **should** match since the pattern doesn't require end-of-string. The real blocker for that compound command was the `&&` splitting — `git log --oneline -5` — `-5` shouldn't be an issue either.
+
+**Conclusion on item 3:** The `git status --short` case was a false alarm caused by compound command parsing combined with the `2>/dev/null` redirect in the user's actual commands, not a pattern bug. No change needed here beyond the redirect fix.
+
+### 4. What we're NOT adding (YAGNI)
+
+- `sed -i` (in-place editing) — correctly destructive
+- `gh pr create/merge/close` — write operations
+- `curl -o file` (output to file) — the redirect catch blocks this
+- `cut`, `tr`, `column`, `base64` — rarely needed; can add later on demand
+- `gh api` — too broad; can be used for mutations. Require specific subcommands.
+
+## Data flow
+
+No new data flow. The changes are purely additive to the pattern-matching logic in `isSafeCommand`.
+
+## Error handling
+
+No new error paths. The existing block-and-warn behavior remains unchanged.
+
+## Testing
+
+Manual verification with the exact commands that were blocked:
+
+1. `cd /some/path && git remote -v 2>/dev/null; echo "---"; ls` → allowed
+2. `gh pr view 1564 --repo owner/repo --json title,body,files 2>/dev/null || echo "gh failed"` → allowed
+3. `git stash list` → allowed
+4. `git tag -l` → allowed
+5. `rm -rf /` → still blocked ✓
+6. `git push origin main` → still blocked ✓
+
+## Tests
+
+Add the following test cases to the existing `tests/workflow-guard.test.ts` `isSafeCommand` describe block:
+
+### New: `cd` navigation
+```ts
+it("allows cd", () => {
+	expect(isSafeCommand("cd /some/path")).toBe(true);
+	expect(isSafeCommand("cd src && ls")).toBe(true);
+});
+```
+
+### New: GitHub CLI read-only subcommands
+```ts
+it("allows gh read-only subcommands", () => {
+	expect(isSafeCommand("gh pr view 1564 --json title,body")).toBe(true);
+	expect(isSafeCommand("gh pr list --repo owner/repo")).toBe(true);
+	expect(isSafeCommand("gh pr diff 1564")).toBe(true);
+	expect(isSafeCommand("gh issue view 42")).toBe(true);
+	expect(isSafeCommand("gh issue list --label bug")).toBe(true);
+	expect(isSafeCommand("gh repo view owner/repo")).toBe(true);
+	expect(isSafeCommand("gh run view 12345")).toBe(true);
+});
+
+it("blocks gh write subcommands", () => {
+	expect(isSafeCommand("gh pr create --title 'fix'")).toBe(false);
+	expect(isSafeCommand("gh pr merge 1564")).toBe(false);
+	expect(isSafeCommand("gh issue close 42")).toBe(false);
+	expect(isSafeCommand("gh release create v1.0")).toBe(false);
+});
+```
+
+### New: Git read-only subcommands
+```ts
+it("allows git read-only subcommands (new additions)", () => {
+	expect(isSafeCommand("git blame src/index.ts")).toBe(true);
+	expect(isSafeCommand("git shortlog -sn")).toBe(true);
+	expect(isSafeCommand("git stash list")).toBe(true);
+	expect(isSafeCommand("git tag -l")).toBe(true);
+	expect(isSafeCommand("git tag --list 'v*'")).toBe(true);
+	expect(isSafeCommand("git describe --tags")).toBe(true);
+});
+
+it("still blocks git stash mutations", () => {
+	expect(isSafeCommand("git stash push -m 'wip'")).toBe(false);
+	expect(isSafeCommand("git stash pop")).toBe(false);
+});
+```
+
+### New: Harmless stderr redirect stripping
+```ts
+it("allows 2>/dev/null on safe commands", () => {
+	expect(isSafeCommand("git remote -v 2>/dev/null")).toBe(true);
+	expect(isSafeCommand("gh pr view 1564 2>/dev/null")).toBe(true);
+	expect(isSafeCommand("npm list 2>/dev/null")).toBe(true);
+});
+
+it("allows 2>&1 on safe commands", () => {
+	expect(isSafeCommand("git log 2>&1")).toBe(true);
+});
+
+it("still blocks stdout redirects even with stderr redirect present", () => {
+	expect(isSafeCommand("echo 'hello' > file.ts 2>/dev/null")).toBe(false);
+	expect(isSafeCommand("cat config > backup.txt 2>/dev/null")).toBe(false);
+});
+```
+
+### New: Compound commands from real user scenarios
+```ts
+it("allows the exact user-reported blocked commands", () => {
+	// Scenario 1: directory navigation + git remote + ls
+	expect(isSafeCommand("cd /Users/u/partying/pt-room && git remote -v 2>/dev/null; echo '---'; ls")).toBe(true);
+	// Scenario 2: gh pr view with fallback
+	expect(isSafeCommand("gh pr view 1564 --repo olachat/pt-partying --json title,body,files,additions,deletions 2>/dev/null || echo 'gh failed'")).toBe(true);
+});
+```
+
+## Summary
+
+| Change | Location | Size |
+|--------|----------|------|
+| Add `stripHarmlessRedirects()` | Above `isSafeCommand` | ~3 lines |
+| Call it in `isSafeCommand` loop body | Inside `isSafeCommand` | 1 line changed |
+| Add 10 new SAFE_PATTERNS entries | `SAFE_PATTERNS` array | ~10 lines |

package/docs/plans/2026-04-21-workflow-guard-safe-commands-implementation.md

@@ -0,0 +1,168 @@
+# Workflow Guard: Safe Commands Expansion — Implementation Plan
+
+**Design:** `docs/plans/2026-04-21-workflow-guard-safe-commands-design.md`
+**Date:** 2026-04-21
+
+---
+
+## Task 1: Add `stripHarmlessRedirects` helper and wire it into `isSafeCommand`
+
+**Scenario:** Modifying tested code
+**File:** `extensions/workflow-guard.ts`
+
+1. Run existing tests to confirm baseline:
+   ```bash
+   npx vitest run tests/workflow-guard.test.ts
+   ```
+   Expected: all pass.
+
+2. Add `stripHarmlessRedirects` function above `isSafeCommand`:
+   ```ts
+   /** Strip stderr redirects that are purely cosmetic (no side effects). */
+   function stripHarmlessRedirects(cmd: string): string {
+   	return cmd.replace(/\s*2\s*>\s*(\/dev\/null|&1)\b/g, "");
+   }
+   ```
+
+3. Wire it into `isSafeCommand` — apply `stripHarmlessRedirects` to each part before pattern matching:
+   ```ts
+   export function isSafeCommand(command: string): boolean {
+   	const parts = splitCompoundCommand(command);
+   	return parts.every((part) => {
+   		const cleaned = stripHarmlessRedirects(part);
+   		const isDestructive = DESTRUCTIVE_PATTERNS.some((p) => p.test(cleaned));
+   		const isSafe = SAFE_PATTERNS.some((p) => p.test(cleaned));
+   		return !isDestructive && isSafe;
+   	});
+   }
+   ```
+
+4. Run tests:
+   ```bash
+   npx vitest run tests/workflow-guard.test.ts
+   ```
+   Expected: all existing tests still pass (no behavior change yet since no new SAFE_PATTERNS).
+
+5. Commit:
+   ```bash
+   git add extensions/workflow-guard.ts
+   git commit -m "feat(workflow-guard): add stripHarmlessRedirects helper"
+   ```
+
+---
+
+## Task 2: Add new SAFE_PATTERNS entries
+
+**Scenario:** Modifying tested code
+**File:** `extensions/workflow-guard.ts`
+
+1. Add the following entries to the `SAFE_PATTERNS` array (after the existing `gh`-related area or at end):
+
+   ```ts
+   /^\s*cd\b/,
+   /^\s*gh\s+pr\s+(view|list|diff|checks|status)\b/i,
+   /^\s*gh\s+issue\s+(view|list)\b/i,
+   /^\s*gh\s+repo\s+(view|fork|list)\b/i,
+   /^\s*gh\s+release\s+(view|list|download)\b/i,
+   /^\s*gh\s+run\s+(view|list)\b/i,
+   /^\s*git\s+blame\b/,
+   /^\s*git\s+shortlog\b/,
+   /^\s*git\s+stash\s+list\b/i,
+   /^\s*git\s+tag\s+(-l|--list)\b/i,
+   /^\s*git\s+describe\b/,
+   ```
+
+2. Run tests:
+   ```bash
+   npx vitest run tests/workflow-guard.test.ts
+   ```
+   Expected: all existing tests pass.
+
+3. Commit:
+   ```bash
+   git add extensions/workflow-guard.ts
+   git commit -m "feat(workflow-guard): add safe patterns for cd, gh, and git read-only subcommands"
+   ```
+
+---
+
+## Task 3: Add tests for `cd`, `gh`, git new subcommands, and redirect stripping
+
+**Scenario:** New feature (test-first)
+**File:** `tests/workflow-guard.test.ts`
+
+**checkpoint: test** — pause after writing failing tests, before implementation.
+
+> Note: Implementation was already done in Tasks 1–2. These tests should all pass immediately. The checkpoint label is kept for review purposes in case the user wants to verify test design.
+
+1. Add the following test blocks inside the `describe("isSafeCommand", ...)` block, after the existing tests:
+
+   ```ts
+   it("allows cd", () => {
+   	expect(isSafeCommand("cd /some/path")).toBe(true);
+   	expect(isSafeCommand("cd src && ls")).toBe(true);
+   });
+
+   it("allows gh read-only subcommands", () => {
+   	expect(isSafeCommand("gh pr view 1564 --json title,body")).toBe(true);
+   	expect(isSafeCommand("gh pr list --repo owner/repo")).toBe(true);
+   	expect(isSafeCommand("gh pr diff 1564")).toBe(true);
+   	expect(isSafeCommand("gh issue view 42")).toBe(true);
+   	expect(isSafeCommand("gh issue list --label bug")).toBe(true);
+   	expect(isSafeCommand("gh repo view owner/repo")).toBe(true);
+   	expect(isSafeCommand("gh run view 12345")).toBe(true);
+   });
+
+   it("blocks gh write subcommands", () => {
+   	expect(isSafeCommand("gh pr create --title 'fix'")).toBe(false);
+   	expect(isSafeCommand("gh pr merge 1564")).toBe(false);
+   	expect(isSafeCommand("gh issue close 42")).toBe(false);
+   	expect(isSafeCommand("gh release create v1.0")).toBe(false);
+   });
+
+   it("allows git read-only subcommands (new additions)", () => {
+   	expect(isSafeCommand("git blame src/index.ts")).toBe(true);
+   	expect(isSafeCommand("git shortlog -sn")).toBe(true);
+   	expect(isSafeCommand("git stash list")).toBe(true);
+   	expect(isSafeCommand("git tag -l")).toBe(true);
+   	expect(isSafeCommand("git tag --list 'v*'")).toBe(true);
+   	expect(isSafeCommand("git describe --tags")).toBe(true);
+   });
+
+   it("still blocks git stash mutations", () => {
+   	expect(isSafeCommand("git stash push -m 'wip'")).toBe(false);
+   	expect(isSafeCommand("git stash pop")).toBe(false);
+   });
+
+   it("allows 2>/dev/null on safe commands", () => {
+   	expect(isSafeCommand("git remote -v 2>/dev/null")).toBe(true);
+   	expect(isSafeCommand("gh pr view 1564 2>/dev/null")).toBe(true);
+   	expect(isSafeCommand("npm list 2>/dev/null")).toBe(true);
+   });
+
+   it("allows 2>&1 on safe commands", () => {
+   	expect(isSafeCommand("git log 2>&1")).toBe(true);
+   });
+
+   it("still blocks stdout redirects even with stderr redirect present", () => {
+   	expect(isSafeCommand("echo 'hello' > file.ts 2>/dev/null")).toBe(false);
+   	expect(isSafeCommand("cat config > backup.txt 2>/dev/null")).toBe(false);
+   });
+
+   it("allows the exact user-reported blocked commands", () => {
+   	expect(isSafeCommand("cd /Users/u/partying/pt-room && git remote -v 2>/dev/null; echo '---'; ls")).toBe(true);
+   	expect(isSafeCommand("gh pr view 1564 --repo olachat/pt-partying --json title,body,files,additions,deletions 2>/dev/null || echo 'gh failed'")).toBe(true);
+   });
+   ```
+
+2. Run tests:
+   ```bash
+   npx vitest run tests/workflow-guard.test.ts
+   ```
+   Expected: all tests pass (including new ones).
+
+3. Commit:
+   ```bash
+   git add tests/workflow-guard.test.ts
+   git commit -m "test(workflow-guard): add tests for cd, gh, git read-only subcommands, and redirect stripping"
+   ```

package/docs/plans/completed/2026-04-21-workflow-guard-safe-commands-design.md

@@ -0,0 +1,172 @@
+# Workflow Guard: Safe Commands Expansion
+
+**Date:** 2026-04-21
+**Status:** Draft
+
+## Problem
+
+The workflow guard blocks several read-only bash commands that are genuinely needed during brainstorm and plan phases. Two specific user reports:
+
+1. `cd /path && git remote -v 2>/dev/null; echo "---"; ls` — blocked due to `cd` not being allowlisted and `2>/dev/null` caught by the stdout-redirect pattern.
+2. `gh pr view 1564 --json ... 2>/dev/null || echo "gh failed"` — blocked because `gh` is not allowlisted at all.
+
+Additionally, `git status --short` is blocked because the safe regex only allows `git status` without flags.
+
+## Design
+
+### 1. Harmless redirect stripping
+
+Add a `stripHarmlessRedirects(cmd)` helper that removes `2>/dev/null` and `2>&1` before pattern matching. These are purely cosmetic (suppress stderr noise) and have no side effects.
+
+```ts
+function stripHarmlessRedirects(cmd: string): string {
+  return cmd.replace(/\s*2\s*>\s*(\/dev\/null|&1)\b/g, "");
+}
+```
+
+Apply it inside `isSafeCommand` on each sub-command before checking DESTRUCTIVE and SAFE patterns. This fixes `2>/dev/null` without loosening the redirect catch (which still blocks real writes).
+
+### 2. New SAFE_PATTERNS entries
+
+| Pattern | Rationale |
+|---------|-----------|
+| `/^\s*cd\b/` | Directory navigation — zero side effects |
+| `/^\s*gh\s+pr\s+(view\|list\|diff\|checks\|status)\b/i` | Read-only PR inspection |
+| `/^\s*gh\s+issue\s+(view\|list)\b/i` | Read-only issue inspection |
+| `/^\s*gh\s+repo\s+(view\|fork\|list)\b/i` | Read-only repo metadata |
+| `/^\s*gh\s+release\s+(view\|list\|download)\b/i` | Read-only release inspection |
+| `/^\s*gh\s+run\s+(view\|list)\b/i` | Read-only CI run inspection |
+| `/^\s*git\s+blame\b/` | Read-only file annotation |
+| `/^\s*git\s+shortlog\b/` | Read-only commit summary |
+| `/^\s*git\s+stash\s+list\b/i` | Read-only stash listing |
+| `/^\s*git\s+tag\s+(-l\|--list)\b/i` | Read-only tag listing |
+| `/^\s*git\s+describe\b/` | Read-only version info |
+
+### 3. Fix: `git status` flag handling
+
+Current regex `/^\s*git\s+(status|log|...)/i` doesn't allow common flags like `--short`, `--oneline`, `--format=...`. Refine all git safe patterns to optionally accept trailing flags and args:
+
+```ts
+/^\s*git\s+status\b/i,
+/^\s*git\s+log\b/i,
+/^\s*git\s+diff\b/i,
+/^\s*git\s+show\b/i,
+/^\s*git\s+blame\b/i,
+// etc.
+```
+
+The existing patterns already anchor to `^\s*git\s+<subcommand>` — the issue was that `git status --short` didn't match because some patterns had more restrictive anchoring. Reviewing the code: the patterns use `\b` word boundaries which should allow flags. The actual issue with `git status --short && git log --oneline -5` is that the `git log --oneline -5` part is safe, but `git status --short` — let me verify: `/^\s*git\s+(status|log|diff|show|branch|remote|config\s+--get)/i` — `git status` has a `\b` after the group? No, there's no trailing `\b`. So `git status --short` **should** match since the pattern doesn't require end-of-string. The real blocker for that compound command was the `&&` splitting — `git log --oneline -5` — `-5` shouldn't be an issue either.
+
+**Conclusion on item 3:** The `git status --short` case was a false alarm caused by compound command parsing combined with the `2>/dev/null` redirect in the user's actual commands, not a pattern bug. No change needed here beyond the redirect fix.
+
+### 4. What we're NOT adding (YAGNI)
+
+- `sed -i` (in-place editing) — correctly destructive
+- `gh pr create/merge/close` — write operations
+- `curl -o file` (output to file) — the redirect catch blocks this
+- `cut`, `tr`, `column`, `base64` — rarely needed; can add later on demand
+- `gh api` — too broad; can be used for mutations. Require specific subcommands.
+
+## Data flow
+
+No new data flow. The changes are purely additive to the pattern-matching logic in `isSafeCommand`.
+
+## Error handling
+
+No new error paths. The existing block-and-warn behavior remains unchanged.
+
+## Testing
+
+Manual verification with the exact commands that were blocked:
+
+1. `cd /some/path && git remote -v 2>/dev/null; echo "---"; ls` → allowed
+2. `gh pr view 1564 --repo owner/repo --json title,body,files 2>/dev/null || echo "gh failed"` → allowed
+3. `git stash list` → allowed
+4. `git tag -l` → allowed
+5. `rm -rf /` → still blocked ✓
+6. `git push origin main` → still blocked ✓
+
+## Tests
+
+Add the following test cases to the existing `tests/workflow-guard.test.ts` `isSafeCommand` describe block:
+
+### New: `cd` navigation
+```ts
+it("allows cd", () => {
+	expect(isSafeCommand("cd /some/path")).toBe(true);
+	expect(isSafeCommand("cd src && ls")).toBe(true);
+});
+```
+
+### New: GitHub CLI read-only subcommands
+```ts
+it("allows gh read-only subcommands", () => {
+	expect(isSafeCommand("gh pr view 1564 --json title,body")).toBe(true);
+	expect(isSafeCommand("gh pr list --repo owner/repo")).toBe(true);
+	expect(isSafeCommand("gh pr diff 1564")).toBe(true);
+	expect(isSafeCommand("gh issue view 42")).toBe(true);
+	expect(isSafeCommand("gh issue list --label bug")).toBe(true);
+	expect(isSafeCommand("gh repo view owner/repo")).toBe(true);
+	expect(isSafeCommand("gh run view 12345")).toBe(true);
+});
+
+it("blocks gh write subcommands", () => {
+	expect(isSafeCommand("gh pr create --title 'fix'")).toBe(false);
+	expect(isSafeCommand("gh pr merge 1564")).toBe(false);
+	expect(isSafeCommand("gh issue close 42")).toBe(false);
+	expect(isSafeCommand("gh release create v1.0")).toBe(false);
+});
+```
+
+### New: Git read-only subcommands
+```ts
+it("allows git read-only subcommands (new additions)", () => {
+	expect(isSafeCommand("git blame src/index.ts")).toBe(true);
+	expect(isSafeCommand("git shortlog -sn")).toBe(true);
+	expect(isSafeCommand("git stash list")).toBe(true);
+	expect(isSafeCommand("git tag -l")).toBe(true);
+	expect(isSafeCommand("git tag --list 'v*'")).toBe(true);
+	expect(isSafeCommand("git describe --tags")).toBe(true);
+});
+
+it("still blocks git stash mutations", () => {
+	expect(isSafeCommand("git stash push -m 'wip'")).toBe(false);
+	expect(isSafeCommand("git stash pop")).toBe(false);
+});
+```
+
+### New: Harmless stderr redirect stripping
+```ts
+it("allows 2>/dev/null on safe commands", () => {
+	expect(isSafeCommand("git remote -v 2>/dev/null")).toBe(true);
+	expect(isSafeCommand("gh pr view 1564 2>/dev/null")).toBe(true);
+	expect(isSafeCommand("npm list 2>/dev/null")).toBe(true);
+});
+
+it("allows 2>&1 on safe commands", () => {
+	expect(isSafeCommand("git log 2>&1")).toBe(true);
+});
+
+it("still blocks stdout redirects even with stderr redirect present", () => {
+	expect(isSafeCommand("echo 'hello' > file.ts 2>/dev/null")).toBe(false);
+	expect(isSafeCommand("cat config > backup.txt 2>/dev/null")).toBe(false);
+});
+```
+
+### New: Compound commands from real user scenarios
+```ts
+it("allows the exact user-reported blocked commands", () => {
+	// Scenario 1: directory navigation + git remote + ls
+	expect(isSafeCommand("cd /Users/u/partying/pt-room && git remote -v 2>/dev/null; echo '---'; ls")).toBe(true);
+	// Scenario 2: gh pr view with fallback
+	expect(isSafeCommand("gh pr view 1564 --repo olachat/pt-partying --json title,body,files,additions,deletions 2>/dev/null || echo 'gh failed'")).toBe(true);
+});
+```
+
+## Summary
+
+| Change | Location | Size |
+|--------|----------|------|
+| Add `stripHarmlessRedirects()` | Above `isSafeCommand` | ~3 lines |
+| Call it in `isSafeCommand` loop body | Inside `isSafeCommand` | 1 line changed |
+| Add 10 new SAFE_PATTERNS entries | `SAFE_PATTERNS` array | ~10 lines |

package/docs/plans/completed/2026-04-21-workflow-guard-safe-commands-implementation.md

@@ -0,0 +1,168 @@
+# Workflow Guard: Safe Commands Expansion — Implementation Plan
+
+**Design:** `docs/plans/2026-04-21-workflow-guard-safe-commands-design.md`
+**Date:** 2026-04-21
+
+---
+
+## Task 1: Add `stripHarmlessRedirects` helper and wire it into `isSafeCommand`
+
+**Scenario:** Modifying tested code
+**File:** `extensions/workflow-guard.ts`
+
+1. Run existing tests to confirm baseline:
+   ```bash
+   npx vitest run tests/workflow-guard.test.ts
+   ```
+   Expected: all pass.
+
+2. Add `stripHarmlessRedirects` function above `isSafeCommand`:
+   ```ts
+   /** Strip stderr redirects that are purely cosmetic (no side effects). */
+   function stripHarmlessRedirects(cmd: string): string {
+   	return cmd.replace(/\s*2\s*>\s*(\/dev\/null|&1)\b/g, "");
+   }
+   ```
+
+3. Wire it into `isSafeCommand` — apply `stripHarmlessRedirects` to each part before pattern matching:
+   ```ts
+   export function isSafeCommand(command: string): boolean {
+   	const parts = splitCompoundCommand(command);
+   	return parts.every((part) => {
+   		const cleaned = stripHarmlessRedirects(part);
+   		const isDestructive = DESTRUCTIVE_PATTERNS.some((p) => p.test(cleaned));
+   		const isSafe = SAFE_PATTERNS.some((p) => p.test(cleaned));
+   		return !isDestructive && isSafe;
+   	});
+   }
+   ```
+
+4. Run tests:
+   ```bash
+   npx vitest run tests/workflow-guard.test.ts
+   ```
+   Expected: all existing tests still pass (no behavior change yet since no new SAFE_PATTERNS).
+
+5. Commit:
+   ```bash
+   git add extensions/workflow-guard.ts
+   git commit -m "feat(workflow-guard): add stripHarmlessRedirects helper"
+   ```
+
+---
+
+## Task 2: Add new SAFE_PATTERNS entries
+
+**Scenario:** Modifying tested code
+**File:** `extensions/workflow-guard.ts`
+
+1. Add the following entries to the `SAFE_PATTERNS` array (after the existing `gh`-related area or at end):
+
+   ```ts
+   /^\s*cd\b/,
+   /^\s*gh\s+pr\s+(view|list|diff|checks|status)\b/i,
+   /^\s*gh\s+issue\s+(view|list)\b/i,
+   /^\s*gh\s+repo\s+(view|fork|list)\b/i,
+   /^\s*gh\s+release\s+(view|list|download)\b/i,
+   /^\s*gh\s+run\s+(view|list)\b/i,
+   /^\s*git\s+blame\b/,
+   /^\s*git\s+shortlog\b/,
+   /^\s*git\s+stash\s+list\b/i,
+   /^\s*git\s+tag\s+(-l|--list)\b/i,
+   /^\s*git\s+describe\b/,
+   ```
+
+2. Run tests:
+   ```bash
+   npx vitest run tests/workflow-guard.test.ts
+   ```
+   Expected: all existing tests pass.
+
+3. Commit:
+   ```bash
+   git add extensions/workflow-guard.ts
+   git commit -m "feat(workflow-guard): add safe patterns for cd, gh, and git read-only subcommands"
+   ```
+
+---
+
+## Task 3: Add tests for `cd`, `gh`, git new subcommands, and redirect stripping
+
+**Scenario:** New feature (test-first)
+**File:** `tests/workflow-guard.test.ts`
+
+**checkpoint: test** — pause after writing failing tests, before implementation.
+
+> Note: Implementation was already done in Tasks 1–2. These tests should all pass immediately. The checkpoint label is kept for review purposes in case the user wants to verify test design.
+
+1. Add the following test blocks inside the `describe("isSafeCommand", ...)` block, after the existing tests:
+
+   ```ts
+   it("allows cd", () => {
+   	expect(isSafeCommand("cd /some/path")).toBe(true);
+   	expect(isSafeCommand("cd src && ls")).toBe(true);
+   });
+
+   it("allows gh read-only subcommands", () => {
+   	expect(isSafeCommand("gh pr view 1564 --json title,body")).toBe(true);
+   	expect(isSafeCommand("gh pr list --repo owner/repo")).toBe(true);
+   	expect(isSafeCommand("gh pr diff 1564")).toBe(true);
+   	expect(isSafeCommand("gh issue view 42")).toBe(true);
+   	expect(isSafeCommand("gh issue list --label bug")).toBe(true);
+   	expect(isSafeCommand("gh repo view owner/repo")).toBe(true);
+   	expect(isSafeCommand("gh run view 12345")).toBe(true);
+   });
+
+   it("blocks gh write subcommands", () => {
+   	expect(isSafeCommand("gh pr create --title 'fix'")).toBe(false);
+   	expect(isSafeCommand("gh pr merge 1564")).toBe(false);
+   	expect(isSafeCommand("gh issue close 42")).toBe(false);
+   	expect(isSafeCommand("gh release create v1.0")).toBe(false);
+   });
+
+   it("allows git read-only subcommands (new additions)", () => {
+   	expect(isSafeCommand("git blame src/index.ts")).toBe(true);
+   	expect(isSafeCommand("git shortlog -sn")).toBe(true);
+   	expect(isSafeCommand("git stash list")).toBe(true);
+   	expect(isSafeCommand("git tag -l")).toBe(true);
+   	expect(isSafeCommand("git tag --list 'v*'")).toBe(true);
+   	expect(isSafeCommand("git describe --tags")).toBe(true);
+   });
+
+   it("still blocks git stash mutations", () => {
+   	expect(isSafeCommand("git stash push -m 'wip'")).toBe(false);
+   	expect(isSafeCommand("git stash pop")).toBe(false);
+   });
+
+   it("allows 2>/dev/null on safe commands", () => {
+   	expect(isSafeCommand("git remote -v 2>/dev/null")).toBe(true);
+   	expect(isSafeCommand("gh pr view 1564 2>/dev/null")).toBe(true);
+   	expect(isSafeCommand("npm list 2>/dev/null")).toBe(true);
+   });
+
+   it("allows 2>&1 on safe commands", () => {
+   	expect(isSafeCommand("git log 2>&1")).toBe(true);
+   });
+
+   it("still blocks stdout redirects even with stderr redirect present", () => {
+   	expect(isSafeCommand("echo 'hello' > file.ts 2>/dev/null")).toBe(false);
+   	expect(isSafeCommand("cat config > backup.txt 2>/dev/null")).toBe(false);
+   });
+
+   it("allows the exact user-reported blocked commands", () => {
+   	expect(isSafeCommand("cd /Users/u/partying/pt-room && git remote -v 2>/dev/null; echo '---'; ls")).toBe(true);
+   	expect(isSafeCommand("gh pr view 1564 --repo olachat/pt-partying --json title,body,files,additions,deletions 2>/dev/null || echo 'gh failed'")).toBe(true);
+   });
+   ```
+
+2. Run tests:
+   ```bash
+   npx vitest run tests/workflow-guard.test.ts
+   ```
+   Expected: all tests pass (including new ones).
+
+3. Commit:
+   ```bash
+   git add tests/workflow-guard.test.ts
+   git commit -m "test(workflow-guard): add tests for cd, gh, git read-only subcommands, and redirect stripping"
+   ```

package/extensions/workflow-guard.ts

@@ -35,7 +35,7 @@ const DESTRUCTIVE_PATTERNS = [
 	/\bpip\s+(install|uninstall)/i,
 	/\bapt(-get)?\s+(install|remove|purge|update|upgrade)/i,
 	/\bbrew\s+(install|uninstall|upgrade)/i,
-	/\bgit\s+(add|commit|push|pull|merge|rebase|reset|checkout|branch\s+-[dD]|stash|cherry-pick|revert|tag|init|clone)/i,
+	/\bgit\s+(add|commit|push|pull|merge|rebase|reset|checkout|branch\s+-[dD]|stash(?!\s+list)|cherry-pick|revert|tag(?!\s+(-l|--list))|init|clone)/i,
 	/\bsudo\b/i,
 	/\bsu\b/i,
 	/\bkill\b/i,
@@ -99,12 +99,46 @@ const SAFE_PATTERNS = [
 	/^\s*fd\b/,
 	/^\s*bat\b/,
 	/^\s*eza\b/,
+	/^\s*cd\b/,
+	/^\s*gh\s+pr\s+(view|list|diff|checks|status)\b/i,
+	/^\s*gh\s+issue\s+(view|list)\b/i,
+	/^\s*gh\s+repo\s+(view|fork|list)\b/i,
+	/^\s*gh\s+release\s+(view|list|download)\b/i,
+	/^\s*gh\s+run\s+(view|list)\b/i,
+	/^\s*git\s+blame\b/,
+	/^\s*git\s+shortlog\b/,
+	/^\s*git\s+stash\s+list\b/i,
+	/^\s*git\s+tag\s+(-l|--list)\b/i,
+	/^\s*git\s+describe\b/,
 ];
 
+/** Split a compound command into individual sub-commands.
+ * Handles &&, ||, ;, and | (pipe) operators, ignoring leading whitespace.
+ */
+function splitCompoundCommand(command: string): string[] {
+	// Match sub-commands separated by &&, ||, ; (with optional whitespace)
+	// We don't split on | to allow piping (e.g. `git log | head`)
+	return command
+		.split(/&&|\|\||;/)
+		.map((s) => s.trim())
+		.filter((s) => s.length > 0);
+}
+
+/** Strip stderr redirects that are purely cosmetic (no side effects). */
+function stripHarmlessRedirects(cmd: string): string {
+	return cmd.replace(/\s*2\s*>\s*(\/dev\/null|&1)\b/g, "");
+}
+
 export function isSafeCommand(command: string): boolean {
-	const isDestructive = DESTRUCTIVE_PATTERNS.some((p) => p.test(command));
-	const isSafe = SAFE_PATTERNS.some((p) => p.test(command));
-	return !isDestructive && isSafe;
+	const parts = splitCompoundCommand(command);
+	return parts.every(
+		(part) => {
+			const cleaned = stripHarmlessRedirects(part);
+			const isDestructive = DESTRUCTIVE_PATTERNS.some((p) => p.test(cleaned));
+			const isSafe = SAFE_PATTERNS.some((p) => p.test(cleaned));
+			return !isDestructive && isSafe;
+		},
+	);
 }
 
 const SKILL_TO_PHASE: Record<string, Phase> = {
@@ -112,6 +146,18 @@ const SKILL_TO_PHASE: Record<string, Phase> = {
 	"writing-plans": "plan",
 };
 
+/** Determine if a write/edit to filePath should be blocked during the given phase.
+ *  Only writes under docs/plans/ are allowed during brainstorm and plan phases.
+ */
+export function shouldBlockFilePath(
+	filePath: string,
+	cwd: string,
+): boolean {
+	const absolute = resolve(cwd, filePath);
+	const plansDir = resolve(cwd, "docs/plans");
+	return !absolute.startsWith(plansDir + "/");
+}
+
 export function getCurrentPhase(): Phase {
 	return phase;
 }
@@ -166,9 +212,7 @@ export default function (pi: ExtensionAPI) {
 		const filePath = (event.input as { path?: string }).path ?? "";
 		if (!filePath) return;
 
-		const absolute = resolve(ctx.cwd, filePath);
-		const plansDir = resolve(ctx.cwd, "docs/plans");
-		if (absolute.startsWith(plansDir + "/")) return;
+		if (!shouldBlockFilePath(filePath, ctx.cwd)) return;
 
 		if (ctx.hasUI) {
 			ctx.ui.notify(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tianhai/pi-workflow-kit",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "description": "Workflow skills and enforcement extensions for pi",
   "keywords": [
     "pi-package"

package/skills/brainstorming/SKILL.md

@@ -13,11 +13,7 @@ Read-only exploration. You may **not** edit or create any files except under `do
 2. **Understand the idea** — read existing code, docs, and recent commits. Ask questions one at a time to refine the idea. Prefer multiple choice when possible.
 3. **Explore approaches** — propose 2-3 approaches with trade-offs. Lead with your recommendation.
 4. **Present the design** — break it into sections of 200-300 words. Check after each section whether it looks right. Cover: architecture, components, data flow, error handling, testing.
-5. **Set up workspace & write the design doc** — create a branch for this work. For larger features, use a git worktree for isolation:
-   ```
-   git worktree add ../<repo>-<feature-name> -b <feature-name>
-   ```
-   Save the design doc to `docs/plans/YYYY-MM-DD-<topic>-design.md` and commit on the new branch.
+5. **Write the design doc** — save it to `docs/plans/YYYY-MM-DD-<topic>-design.md`. Ask the user to commit it. Branch creation and worktree setup should be deferred to the execution phase (`/skill:executing-tasks`).
 
 ## Principles
 

package/skills/executing-tasks/SKILL.md

@@ -7,6 +7,27 @@ description: "Use this to implement an approved plan task-by-task. Run after wri
 
 Implement the plan from `docs/plans/*-implementation.md` task by task.
 
+## Before you start
+
+1. **Check git state** — run `git status` and `git log --oneline -5`. Note any uncommitted changes.
+2. **Suggest workspace isolation** — if the user isn't already on a feature branch or worktree, present the options:
+
+   - **Branch** (smaller changes):
+     ```
+     git checkout -b <feature-name>
+     ```
+   - **Worktree** (larger features, keeps main clean):
+     ```
+     git worktree add ../<repo>-<feature-name> -b <feature-name>
+     ```
+
+   Derive `<feature-name>` from the plan doc (e.g. `docs/plans/2026-04-16-auth-design.md` → `auth`). Ask the user which they prefer, then wait for confirmation before proceeding.
+
+3. **Commit the plan docs** — if `docs/plans/` has uncommitted files, commit them on the new branch:
+   ```
+   git add docs/plans/ && git commit -m "docs: add design and implementation plan"
+   ```
+
 ## Per-task lifecycle
 
 Check each task for a `checkpoint` label and follow the appropriate flow:

package/skills/writing-plans/SKILL.md

@@ -9,7 +9,7 @@ Read-only exploration. You may **not** edit or create any files except under `do
 
 ## Process
 
-1. **Check for a design doc & workspace** — look for `docs/plans/*-design.md`. If one exists, use it as the basis for the plan. Verify you're on the feature branch (or in its worktree) created during brainstorming. If no design doc exists, ask the user to describe what they want to build, read relevant code, create a branch, and create the plan directly.
+1. **Check for a design doc** — look for `docs/plans/*-design.md`. If one exists, use it as the basis for the plan. If no design doc exists, ask the user to describe what they want to build and read relevant code.
 2. **Write the implementation plan** — break the design into tasks. Save to `docs/plans/YYYY-MM-DD-<topic>-implementation.md`.
 
 ## Task format