aiwcli 0.9.1 → 0.9.2

package/dist/templates/cc-native/_cc-native/lib/CLAUDE.md

@@ -0,0 +1,240 @@
+# CC-Native Library Development Guide
+
+> **Keep this document updated.** When you solve an issue related to library code, add the solution to the relevant section and log it in the Changelog. This document should grow with discovered patterns and fixes—don't wait to be asked.
+
+---
+
+## Module Overview
+
+| Module | Purpose |
+|--------|---------|
+| `utils.py` | Core utilities: eprint, sanitize, JSON parsing, artifact writing |
+| `state.py` | Plan state file management and iteration tracking |
+| `orchestrator.py` | Plan complexity analysis and agent selection |
+| `reviewers.py` | CLI and agent-based plan review implementations |
+| `atomic_write.py` | Atomic file writes for crash safety |
+| `constants.py` | Shared constants and configuration |
+| `async_archive.py` | Async plan archival operations |
+| `__init__.py` | Package exports |
+
+---
+
+## Dependency Graph
+
+```
+Hooks (cc-native-plan-review.py, etc.)
+    │
+    ├── lib/utils.py (core utilities)
+    │       └── lib/atomic_write.py
+    │       └── lib/constants.py
+    │
+    ├── lib/state.py (state management)
+    │       └── lib/utils.py (eprint)
+    │
+    ├── lib/orchestrator.py (agent selection)
+    │       └── lib/utils.py (ReviewerResult, etc.)
+    │
+    └── _shared/lib/ (shared across all methods)
+            ├── lib/base/subprocess_utils.py
+            ├── lib/base/constants.py
+            └── lib/context/context_manager.py
+```
+
+**Import direction:** Hooks → cc-native lib → shared lib. Never the reverse.
+
+---
+
+## Key Data Classes
+
+### ReviewerResult
+
+```python
+@dataclass
+class ReviewerResult:
+    name: str           # Reviewer name (e.g., "codex", "architect-reviewer")
+    ok: bool            # True if review completed successfully
+    verdict: str        # "pass" | "warn" | "fail" | "error" | "skip"
+    data: Dict[str, Any]  # Structured review data (summary, issues, etc.)
+    raw: str            # Raw response text
+    err: str            # Error message if any
+```
+
+### OrchestratorResult
+
+```python
+@dataclass
+class OrchestratorResult:
+    complexity: str         # "simple" | "medium" | "high"
+    category: str           # "code" | "infrastructure" | "documentation" | etc.
+    selected_agents: List[str]  # Agent names to run
+    reasoning: str          # Why these agents were selected
+    skip_reason: Optional[str]  # Why review was skipped (if applicable)
+    error: Optional[str]    # Error message if orchestrator failed
+```
+
+### CombinedReviewResult
+
+```python
+@dataclass
+class CombinedReviewResult:
+    plan_hash: str                          # SHA256 hash (first 16 chars)
+    overall_verdict: str                    # Worst verdict across all reviewers
+    cli_reviewers: Dict[str, ReviewerResult]  # Codex, Gemini results
+    orchestration: Optional[OrchestratorResult]
+    agents: Dict[str, ReviewerResult]       # Agent review results
+    timestamp: str                          # ISO format
+```
+
+---
+
+## Windows Path Handling
+
+Windows uses backslashes in paths. Always normalize when comparing:
+
+```python
+# CORRECT - works on Windows and Unix
+if ".claude/plans/" in file_path.replace("\\", "/"):
+    # Found a plan file
+
+# Also correct - use Path for comparisons
+from pathlib import Path
+if Path(".claude/plans") in Path(file_path).parents:
+    # Found a plan file
+```
+
+```python
+# WRONG - fails on Windows
+if ".claude/plans/" in file_path:  # Windows path: ".claude\\plans\\"
+    # Never matches on Windows!
+```
+
+This is a recurring issue. Any path string comparison must handle both separators.
+
+---
+
+## Atomic Writes
+
+For critical files (state, reviews), use atomic writes to prevent corruption on crash:
+
+```python
+from atomic_write import atomic_write
+
+# CORRECT - atomic write
+success, error = atomic_write(path, content)
+if not success:
+    eprint(f"[module] Write failed: {error}")
+```
+
+```python
+# RISKY - can leave partial file on crash
+path.write_text(content, encoding="utf-8")
+```
+
+Atomic writes use a temp file + rename pattern. Check `constants.ENABLE_ROBUST_PLAN_WRITES` for the feature flag.
+
+---
+
+## Adding New Reviewers
+
+1. **Create reviewer function** in `reviewers.py`:
+   ```python
+   def run_myreviewer_review(
+       plan: str,
+       schema: Dict[str, Any],
+       settings: Dict[str, Any],
+   ) -> ReviewerResult:
+       # Implementation
+       return ReviewerResult(
+           name="myreviewer",
+           ok=True,
+           verdict="pass",
+           data=parsed_data,
+           raw=raw_response,
+           err="",
+       )
+   ```
+
+2. **Export in `__init__.py`** (if needed for external use)
+
+3. **Add config** in `plan-review.config.json`:
+   ```json
+   {
+     "planReview": {
+       "reviewers": {
+         "myreviewer": {"enabled": true, "timeout": 120}
+       }
+     }
+   }
+   ```
+
+4. **Wire in hook** (`cc-native-plan-review.py`):
+   ```python
+   from reviewers import run_myreviewer_review
+
+   if myreviewer_enabled:
+       phase1_tasks.append(("myreviewer", lambda: run_myreviewer_review(...)))
+   ```
+
+---
+
+## JSON Parsing
+
+Use `parse_json_maybe` for LLM responses - it handles markdown code blocks and extraction:
+
+```python
+from utils import parse_json_maybe, coerce_to_review
+
+# Parse with field validation
+obj = parse_json_maybe(raw_response, require_fields=["verdict", "summary"])
+
+# Normalize to expected structure
+ok, verdict, data = coerce_to_review(obj)
+```
+
+The parser tries:
+1. Strict JSON parse
+2. Extract `{...}` block from text (handles ```json blocks)
+
+---
+
+## Encoding
+
+Always specify encoding on file operations:
+
+```python
+# CORRECT
+content = path.read_text(encoding="utf-8")
+path.write_text(content, encoding="utf-8")
+
+with open(path, "r", encoding="utf-8") as f:
+    data = json.load(f)
+```
+
+```python
+# WRONG - uses system default (can fail on Windows)
+content = path.read_text()  # May use cp1252 on Windows
+```
+
+---
+
+## DO NOT
+
+These are reminders based on past issues. Not enforcement rules.
+
+- **Don't import from `_cc-native/lib/` in `_shared/lib/`** - wrong direction, creates circular deps
+- **Don't use `print()` for debugging** - use `eprint()` to avoid corrupting stdout
+- **Don't modify data class fields** without updating all consumers (hooks, formatters, tests)
+- **Don't hardcode paths** - use `Path(__file__)`, env vars, or config
+- **Don't forget `encoding="utf-8"`** on file operations - Windows defaults are unsafe
+- **Don't assume forward slashes** in file paths - Windows uses backslashes
+- **Don't skip atomic writes** for critical state files - use `atomic_write` function
+
+---
+
+## Changelog
+
+<!-- Add dated entries as new issues are discovered -->
+
+| Date | Change |
+|------|--------|
+| 2026-02-03 | Initial creation |

package/dist/templates/cc-native/_cc-native/lib/orchestrator.py

@@ -193,6 +193,7 @@ PLAN:
 
     cmd_args = [
         claude_path,
+        "-p",  # Enable print mode to read prompt from stdin
         "--agent", "plan-orchestrator",
         "--model", config.model,
         "--permission-mode", "bypassPermissions",

package/dist/templates/cc-native/_cc-native/lib/reviewers/agent.py

@@ -119,6 +119,7 @@ PLAN:
     schema_json = json.dumps(schema, ensure_ascii=False)
     cmd_args = [
         claude_path,
+        "-p",  # Enable print mode to read prompt from stdin
         "--agent", agent.name,
         "--model", agent.model,
         "--permission-mode", "bypassPermissions",

package/dist/templates/cc-native/_cc-native/plan-review.config.json

@@ -32,6 +32,12 @@
       "maxTurns": 6
     },
     "legacyMode": false,
+    "mandatoryAgents": ["handoff-readiness", "clarity-auditor", "skeptic"],
+    "fallbackByComplexity": {
+      "simple": 0,
+      "medium": 5,
+      "high": 9
+    },
     "reviewIterations": {
       "simple": 1,
       "medium": 1,

package/oclif.manifest.json

@@ -401,5 +401,5 @@
       ]
     }
   },
-  "version": "0.9.1"
+  "version": "0.9.2"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "aiwcli",
   "description": "AI Workflow CLI - Command-line interface for AI-powered workflows",
-  "version": "0.9.1",
+  "version": "0.9.2",
   "author": "jofu-tofu",
   "bin": {
     "aiw": "./bin/run.js"

package/dist/templates/cc-native/_cc-native/docs/PERMISSION_REQUEST_VERIFICATION.md

@@ -1,147 +0,0 @@
-# PermissionRequest Hook Verification Plan
-
-## Objective
-
-Verify that `PermissionRequest` event can be used for plan archiving instead of the current `PreToolUse` + state file approach.
-
-## Current Implementation (v1.5.0+)
-
-```
-PreToolUse: ExitPlanMode
-└── cc-native-plan-review.py (runs agent reviews, saves to context reviews folder)
-
-PostToolUse: ExitPlanMode
-└── archive_plan.py       (archives plan to context plans folder)
-```
-
-**Note:** As of v1.5.0, `set_plan_state.py` has been removed. Plan review now integrates with the shared context system, storing reviews in `_output/contexts/{context_id}/reviews/`.
-
-## Original Proposed Simplification (Historical)
-
-```
-PreToolUse: ExitPlanMode
-└── cc-native-plan-review.py (runs reviews, saves to context folder)
-
-PermissionRequest: ExitPlanMode   ← Tested approach
-└── archive_plan.py       (archives immediately after reviews complete)
-```
-
-## Verification Steps
-
-### Step 1: Deploy Test Hook
-
-The test hook has been added:
-- **Hook:** `_cc-native/hooks/test_permission_request.py`
-- **Config:** `PermissionRequest` entry in `.claude/settings.json`
-- **Output:** `~/.claude/permission_request_payload.json`
-
-### Step 2: Trigger Plan Mode
-
-1. Start Claude Code with cc-native template:
-   ```bash
-   cd /path/to/project-with-cc-native
-   claude --plan
-   ```
-
-2. Create a simple plan (any task works)
-
-3. When plan is ready, Claude calls `ExitPlanMode`
-
-### Step 3: Check Results
-
-After Claude calls `ExitPlanMode`, check:
-
-```bash
-# Check if payload was logged
-cat ~/.claude/permission_request_payload.json
-```
-
-Expected output:
-```json
-{
-  "received_at": "2026-01-20T...",
-  "payload": {
-    "tool_name": "ExitPlanMode",
-    "session_id": "...",
-    "cwd": "...",
-    "tool_input": {...}
-  },
-  "analysis": {
-    "has_tool_name": true,
-    "has_session_id": true,
-    "has_cwd": true,
-    "has_tool_input": true,
-    "tool_name": "ExitPlanMode",
-    "payload_keys": ["tool_name", "session_id", "cwd", "tool_input", ...]
-  }
-}
-```
-
-### Step 4: Verify Timing
-
-Check stderr logs during plan mode exit:
-
-```
-[cc-native-plan-review] Unified hook started (PreToolUse)
-[cc-native-plan-review] Using context reviews dir: ...
-[cc-native-plan-review] Review complete...
-[test_permission_request] Hook started (PermissionRequest)  ← Should appear AFTER reviews
-[test_permission_request] SUCCESS: All required fields present
-```
-
-**Critical timing requirement:** PermissionRequest must fire:
-1. AFTER PreToolUse hooks complete (reviews done)
-2. BEFORE user sees the approval prompt
-
-## Decision Checklist
-
-After verification, update this checklist:
-
-- [ ] PermissionRequest fires for ExitPlanMode
-- [ ] Payload contains `tool_name`
-- [ ] Payload contains `session_id`
-- [ ] Payload contains `cwd`
-- [ ] Timing: fires AFTER PreToolUse
-- [ ] Timing: fires BEFORE user prompt shown
-- [ ] `archive_plan.py` works with PermissionRequest payload (or minimal changes needed)
-
-## Phase 2: Migration (if verified)
-
-If all checks pass:
-
-1. Modify `archive_plan.py` if needed for PermissionRequest payload
-2. Add production PermissionRequest entry for archive_plan.py
-3. Remove `Edit|Write|Bash` PreToolUse entry for archive_plan.py
-4. Remove `Stop` entry for archive_plan.py
-5. Remove test_permission_request.py hook
-6. Test full flow end-to-end
-
-## Potential Issues
-
-### Issue 1: PermissionRequest may not fire for ExitPlanMode
-
-ExitPlanMode is a special tool that shows the plan approval prompt. It's possible that:
-- PermissionRequest only fires for dangerous tools (Bash, Write, etc.)
-- ExitPlanMode uses a different permission flow
-
-**Mitigation:** The test hook will confirm whether it fires or not.
-
-### Issue 2: Different payload structure
-
-PermissionRequest may have different fields than PreToolUse.
-
-**Mitigation:** The test hook logs all payload keys for analysis.
-
-### Issue 3: Timing may be wrong
-
-PermissionRequest might fire BEFORE PreToolUse hooks complete (before reviews).
-
-**Mitigation:** Check stderr log ordering during test.
-
-## Cleanup
-
-After verification:
-1. Remove `test_permission_request.py` hook
-2. Remove PermissionRequest test entry from settings.json
-3. Delete `~/.claude/permission_request_payload.json`
-4. Document findings in this file