@tianhai/pi-workflow-kit 0.8.1 → 0.8.3

package/README.md

@@ -13,7 +13,7 @@ brainstorm → plan → execute → finalize
 **1 extension** that enforces the rules:
 
 - During brainstorming and planning, `write` and `edit` are **hard-blocked** outside `docs/plans/`. The agent can only read code and discuss the design with you — it literally cannot modify source files.
-- `bash` is **restricted to read-only commands** — file writes, installs, git mutations, and editors are blocked. Safe commands like `grep`, `find`, `git status`, `cat`, `curl` remain available.
+- `bash` is **restricted to read-only commands** — file writes, installs, git mutations, and editors are blocked. Safe commands like `grep`, `find`, `git status`, `cat`, `curl`, `go doc`, `go list` remain available.
 
 No configuration required. Skills and extensions activate automatically after install.
 

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/docs/plans/completed/2026-04-22-go-readonly-safe-commands-implementation.md

@@ -0,0 +1,54 @@
+# Add Go read-only commands to workflow-guard safe list
+
+## Context
+
+Go toolchain read-only commands (`go doc`, `go list`, `go version`, `go env`) are blocked during brainstorm/plan phases because they're not in `SAFE_PATTERNS`. These are purely read-only with no side effects and are commonly needed during code exploration.
+
+## Tasks
+
+### 1 — Add Go safe patterns [Modifying tested code]
+
+**File:** `extensions/workflow-guard.ts`
+
+Add four entries to `SAFE_PATTERNS`, after the `git describe` entry:
+
+```ts
+/^\s*go\s+doc\b/,
+/^\s*go\s+list\b/,
+/^\s*go\s+version\b/,
+/^\s*go\s+env\b/,
+```
+
+**Verify:** run `npx vitest run tests/workflow-guard.test.ts` — all existing tests should pass.
+
+**Commit:** `feat(workflow-guard): add Go read-only commands to safe list`
+
+### 2 — Add tests for Go safe commands [New feature]
+
+**File:** `tests/workflow-guard.test.ts`
+
+Add a new `it` block inside the `describe("isSafeCommand", ...)` suite:
+
+```ts
+it("allows go read-only subcommands", () => {
+	expect(isSafeCommand("go doc go.opentelemetry.io/otel/label")).toBe(true);
+	expect(isSafeCommand("go doc go.opentelemetry.io/otel/codes 2>&1 | head -20")).toBe(true);
+	expect(isSafeCommand("go list -m -versions go.opentelemetry.io/otel 2>&1 | tr ' ' '\\n' | grep -E '^v1\\\\.(2[89]|[3-9][0-9])' | head -20")).toBe(true);
+	expect(isSafeCommand("go version")).toBe(true);
+	expect(isSafeCommand("go env GOOS GOARCH")).toBe(true);
+});
+```
+
+Also add a `go build` block test to ensure write-oriented Go commands stay blocked:
+
+```ts
+it("blocks go write subcommands", () => {
+	expect(isSafeCommand("go build ./...")).toBe(false);
+	expect(isSafeCommand("go install golang.org/x/tools/gopls@latest")).toBe(false);
+	expect(isSafeCommand("go mod tidy")).toBe(false);
+});
+```
+
+**Verify:** run `npx vitest run tests/workflow-guard.test.ts` — all tests pass.
+
+**Commit:** `test(workflow-guard): add tests for Go read-only safe commands`

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,6 +99,21 @@ 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/,
+	/^\s*go\s+doc\b/,
+	/^\s*go\s+list\b/,
+	/^\s*go\s+version\b/,
+	/^\s*go\s+env\b/,
 ];
 
 /** Split a compound command into individual sub-commands.
@@ -113,12 +128,18 @@ function splitCompoundCommand(command: string): string[] {
 		.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 parts = splitCompoundCommand(command);
 	return parts.every(
 		(part) => {
-			const isDestructive = DESTRUCTIVE_PATTERNS.some((p) => p.test(part));
-			const isSafe = SAFE_PATTERNS.some((p) => p.test(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;
 		},
 	);
@@ -129,6 +150,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;
 }
@@ -183,9 +216,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.1",
+  "version": "0.8.3",
   "description": "Workflow skills and enforcement extensions for pi",
   "keywords": [
     "pi-package"
@@ -14,7 +14,7 @@
   "author": "yinloo-ola",
   "repository": {
     "type": "git",
-    "url": "https://github.com/yinloo-ola/pi-workflow-kit.git"
+    "url": "git+https://github.com/yinloo-ola/pi-workflow-kit.git"
   },
   "files": [
     "extensions/",