pi-crew 0.2.3 → 0.2.5

package/docs/FEATURE_INTAKE.md

@@ -0,0 +1,126 @@
+# Feature Intake
+
+Mọi implementation prompt phải đi qua intake gate trước khi code changes.
+
+## Intake Flow
+
+```text
+User prompt / issue
+        │
+        ▼
+Classify input type
+        │
+        ▼
+Identify affected modules
+(src/runtime, src/state, src/extension, src/ui, src/utils)
+        │
+        ▼
+Run risk checklist
+        │
+        ▼
+Choose lane: tiny, normal, or high-risk
+        │
+        ▼
+Create/update story packet (normal+)
+or patch directly (tiny)
+```
+
+## Input Types
+
+| Type | Use when | Artifact |
+|------|----------|----------|
+| Bug fix | Fix crash, wrong behavior, test failure | Direct patch or story |
+| Feature | New capability (new tool action, new runtime mode) | Story packet |
+| Refactor | Internal restructure without behavior change | Direct patch |
+| Performance | Improve speed/memory/concurrency | Story packet |
+| Security | Fix vulnerability, harden boundary | High-risk story |
+| Docs | README, comments, harness files | Direct patch |
+| Dependency | Update/add/remove dependencies | Story packet |
+| Harness improvement | Improve this operating model | Direct docs update |
+
+## Lanes
+
+### Tiny
+Low-risk: docs, names, narrow edits, comment fixes.
+
+Requirements:
+- Patch directly
+- Run `npm run typecheck`
+- Update harness only if friction found
+
+### Normal
+Story-sized behavior with bounded blast radius.
+
+Requirements:
+- Create/update story in `docs/stories/`
+- Link affected product docs
+- Add/update test matrix entries
+- Run `npm test` + `npm run typecheck`
+- Update `docs/TEST_MATRIX.md`
+
+### High-Risk
+Affects security, data integrity, state mutation, concurrency, or multiple modules.
+
+Requirements:
+- Create high-risk story folder in `docs/stories/`
+- Fill overview, design, exec plan, validation
+- Ask human confirmation before implementation
+- Record decision in `docs/decisions/`
+
+## Risk Checklist
+
+| Risk flag | Applies when work touches |
+|-----------|---------------------------|
+| State mutation | manifest.json, tasks.json, events.jsonl writes |
+| Concurrency | shared mutable state, race conditions, locks |
+| Child process | spawning Pi workers, worktree isolation |
+| Error handling | catch blocks, error propagation, crash recovery |
+| External tools | `gh` CLI, `git` commands, shell execution |
+| API contract | team tool API shape, tool parameters |
+| Platform | Windows vs Unix path handling, EBUSY/EPERM |
+| Backward compat | state format changes, config migration |
+| Dependencies | new npm packages, native modules |
+| Security | command injection, path traversal, trust boundaries |
+
+## Classification
+
+```text
+0-1 flags:
+  tiny or normal, based on code impact
+
+2-3 flags:
+  normal with stronger validation
+
+4+ flags:
+  high-risk
+
+Hard gates (always high-risk):
+  - State mutation + concurrency
+  - Child process spawning
+  - External tool execution (command injection surface)
+  - Removing or weakening error handling
+  - Changing state file format without migration
+```
+
+## Affected Modules
+
+| Module | Path | Blast radius |
+|--------|------|-------------|
+| Extension | `src/extension/` | Tool API, registration, hooks |
+| Runtime | `src/runtime/` | Team runner, task runner, child process, async |
+| State | `src/state/` | Durable state, events, locks, artifacts |
+| UI | `src/ui/` | TUI dashboard, overlay, widgets |
+| Utils | `src/utils/` | Shared utilities, conflict detection, git |
+| Worktree | `src/worktree/` | Git worktree management |
+| Config | `src/config/` | Runtime config, resource discovery |
+| Tests | `test/` | Unit tests, integration |
+
+## Output Example
+
+```text
+Lane: normal
+Reason: touches state mutation and concurrency in team-runner.ts
+Modules: src/runtime/team-runner.ts, src/state/state-store.ts
+Story: docs/stories/US-015-durable-state-locking.md
+Validation: npm test, npm run typecheck, CI 3/3
+```

package/docs/HARNESS.md

@@ -0,0 +1,86 @@
+# Harness
+
+pi-crew là một Pi extension cho multi-agent orchestration. Harness này giúp
+agents và humans phối hợp phát triển pi-crew một cách reliable, inspectable,
+và dễ steer.
+
+Product là pi-crew chính nó. Harness là môi trường operating để agents hiểu
+product, classify work, track decisions, và validate changes.
+
+## Mental Model
+
+```text
+Human intent (issue, prompt, request)
+         │
+         ▼
+  Feature intake
+  (classify → risk lane)
+         │
+         ▼
+  Story packet or direct patch
+         │
+         ▼
+  Agent work loop
+  (explore → plan → execute → verify)
+         │
+         ▼
+  Product delta (code, tests, docs)
+         │
+         ▼
+  Validation proof (tests, typecheck, CI)
+         │
+         ▼
+  Harness delta (decisions, test matrix, backlog)
+         │
+         ▼
+  Next intent
+```
+
+Mỗi task có 2 outputs:
+1. **Product delta**: code changes, test changes, API shape, config changes
+2. **Harness delta**: docs, decisions, test matrix updates, backlog items
+
+## Source Hierarchy
+
+Agents đọc theo thứ tự:
+
+1. `AGENTS.md` — operating rules và important paths
+2. `docs/HARNESS.md` — file này, collaboration model
+3. `docs/FEATURE_INTAKE.md` — trước khi biến request thành work
+4. `docs/product/` — current product contract
+5. `docs/ARCHITECTURE.md` — implementation shape
+6. `docs/stories/` — active và completed stories
+7. `docs/TEST_MATRIX.md` — proof status
+8. `docs/decisions/` — why important choices were made
+
+## Validation Ladder
+
+pi-crew đã có validation commands:
+
+| Level | Command | What it proves |
+|-------|---------|----------------|
+| quick | `npm run typecheck` | TypeScript correctness + strip-types import |
+| unit | `npm test` | 1600+ unit tests, all pass |
+| lint | `npm run check` | Biome lint + format |
+| CI | GitHub Actions | Cross-platform (ubuntu, windows, macos) |
+
+Agents **must not** claim validation passes without running the actual command.
+
+## Growth Rule
+
+Harness grows từ friction. Khi agent:
+- Bị confused về expected behavior
+- Phải repeat manual reasoning
+- Thiếu validation command
+- Discover missing rule
+- Thấy recurring failure pattern
+
+→ Agent must improve harness directly hoặc propose trong `docs/HARNESS_BACKLOG.md`.
+
+## Working Conventions
+
+- Vietnamese for communication, English for code/comments
+- Commit message format: `fix:`, `feat:`, `docs:` — conventional commits
+- Every code change must pass `npm test` + `npm run typecheck`
+- MEDIUM+ bugs found during review must be fixed before claiming done
+- LOW issues documented in `docs/HARNESS_BACKLOG.md` if recurring

package/docs/HARNESS_BACKLOG.md

@@ -0,0 +1,41 @@
+# Harness Backlog
+
+Use when an agent discovers a missing harness capability but should not change the operating model immediately.
+
+## Items
+
+### HB-001: Integration test harness
+
+**Discovered while**: Review round 9 — all tests are unit tests, no multi-module integration tests exist.
+
+**Current pain**: Cannot verify team-runner → state-store → child-process integration end-to-end without manual testing.
+
+**Suggested improvement**: Add `test/integration/` with real file-system state, real child processes (with timeout).
+
+**Risk**: normal
+
+**Status**: proposed
+
+### HB-002: Windows-specific test coverage
+
+**Discovered while**: RR-002 Windows EBUSY fix — only tested manually, no automated Windows-specific tests.
+
+**Current pain**: Windows bugs only caught in CI, not locally.
+
+**Suggested improvement**: Add `test/platform/` with Windows-specific tests (EBUSY retry, path handling).
+
+**Risk**: normal
+
+**Status**: proposed
+
+### HB-003: Performance regression baseline
+
+**Discovered while**: Review noted `sleepSync` busy-wait on Windows — no perf benchmarks exist.
+
+**Current pain**: Cannot detect performance regressions.
+
+**Suggested improvement**: Add benchmark suite for critical paths (state writes, event append, task dispatch).
+
+**Risk**: tiny
+
+**Status**: proposed

package/docs/TEST_MATRIX.md

@@ -0,0 +1,49 @@
+# Test Matrix
+
+Maps pi-crew behavior to proof. Every row must have real validation evidence.
+
+## Status Values
+
+| Status | Meaning |
+|--------|---------|
+| planned | Accepted behavior, not implemented |
+| in_progress | Actively being built |
+| implemented | Implemented and proof exists |
+| changed | Contract changed after implementation |
+| retired | No longer part of product |
+
+## Matrix
+
+| Story | Contract | Unit | Integration | CI | Status | Evidence |
+|-------|----------|------|-------------|-----|--------|----------|
+| Core team run | `docs/product/team-run.md` | yes | yes | yes 3/3 | implemented | 1621 tests pass |
+| Child process runner | `docs/product/child-process.md` | yes | no | yes 3/3 | implemented | child-pi.ts tests |
+| Async runner | `docs/product/async-runner.md` | yes | no | yes 3/3 | implemented | async-runner tests |
+| Live session | `docs/product/live-session.md` | yes | no | yes 3/3 | implemented | live-session tests |
+| State durability | `docs/product/state.md` | yes | no | yes 3/3 | implemented | state-store tests |
+| Worktree isolation | `docs/product/worktree.md` | yes | no | yes 3/3 | implemented | worktree tests |
+| Team tool API | `docs/product/team-tool.md` | yes | no | yes 3/3 | implemented | api tests |
+| Group join | `docs/product/group-join.md` | yes | no | yes 3/3 | implemented | group-join tests |
+| Model fallback | `docs/product/model-fallback.md` | yes | no | yes 3/3 | implemented | model-fallback tests |
+| Conflict detection | `docs/product/conflict-detect.md` | yes | no | yes 3/3 | implemented | conflict-detect tests |
+| Crash recovery | `docs/product/crash-recovery.md` | yes | no | yes 3/3 | implemented | crash-recovery tests |
+| Effectiveness guard | `docs/product/effectiveness.md` | yes | no | yes 3/3 | implemented | effectiveness tests |
+| Windows EBUSY | `docs/product/platform.md` | yes | no | yes 3/3 | implemented | rmSyncRetry tests |
+| Depth guard | `docs/product/runtime-safety.md` | yes | no | yes 3/3 | implemented | depth-guard tests |
+
+## Evidence Rules
+
+- **Unit proof**: Pure logic, state transitions, config parsing
+- **Integration proof**: Multi-module interaction (team runner → state → child process)
+- **CI proof**: Cross-platform (ubuntu, windows, macos) green on GitHub Actions
+- A story can be implemented without every proof column if the story explains why
+- Agents must run `npm test` and `npm run typecheck` before claiming done
+
+## Validation Commands
+
+```bash
+npm test                    # Run all unit tests (1600+)
+npm run typecheck           # TypeScript check + strip-types import
+npm run check               # Biome lint + format
+gh run list --limit 1       # Check latest CI status
+```