@coralai/sps-cli 0.65.17 → 0.65.19

package/skills/sps/references/diagnostic-sequence.md

@@ -0,0 +1,106 @@
+# SPS Diagnostic Sequence (v0.16+)
+
+## Pre-requisite check
+
+Before diagnosing workflow issues, verify the environment:
+
+```bash
+sps --version                              # Must be 0.16+
+source ~/.coral/env                       # Credentials loaded?
+sps doctor <project> --json                # Full health report
+```
+
+## Step 1: Global health assessment
+
+```bash
+sps doctor <project> --json                # Config and infrastructure health
+sps monitor tick <project> --json          # Anomaly detection (orphans, timeouts, misalignment)
+sps worker dashboard <project>             # Worker live status
+```
+
+## Step 2: Narrow down by pipeline stage
+
+```bash
+sps scheduler tick <project> --json        # Card selection issues (Planning → Backlog)
+sps pipeline tick <project> --json         # Execution issues (Backlog → Todo → Inprogress → Done)
+sps qa tick <project> --json               # Closeout issues (QA → merge → Done)
+```
+
+## Step 3: Check ground truth
+
+```bash
+sps pm scan <project>                      # PM backend state (business truth)
+sps pm scan <project> Inprogress           # Filter by state
+sps worker dashboard <project> --json      # Worker slot + PID status
+cat ~/.coral/projects/<project>/runtime/state.json   # Runtime state (execution truth)
+cat ~/.coral/projects/<project>/pipeline_order.json  # Execution queue
+```
+
+## Step 4: Process-level inspection (v0.16+)
+
+```bash
+# Check if worker process is alive
+cat ~/.coral/projects/<project>/runtime/state.json | jq '.workers[] | select(.status=="active") | {slot: .slot, pid, seq}'
+kill -0 <pid> 2>/dev/null && echo "ALIVE" || echo "DEAD"
+
+# Check worker output file
+cat ~/.coral/projects/<project>/logs/worker-<slot>.jsonl | tail -20
+
+# Check worktree state
+ls ~/.coral/worktrees/card-<seq>/
+cd ~/.coral/worktrees/card-<seq> && git log --oneline -5
+cd ~/.coral/worktrees/card-<seq> && git status
+
+# Check tick lock
+cat ~/.coral/projects/<project>/runtime/tick.lock
+```
+
+## Step 5: Recovery actions
+
+```bash
+# Let monitor auto-fix orphans and timeouts
+sps monitor tick <project> --json
+
+# Force state transition
+sps pm move <project> <seq> <target-state>
+sps pm comment <project> <seq> "Manual fix: <reason>"
+
+# Re-trigger completion judge
+sps pipeline tick <project> --json
+
+# Remove stale tick lock (only if owning process is dead)
+rm ~/.coral/projects/<project>/runtime/tick.lock
+
+# Restart tick to trigger Recovery module
+sps tick <project>
+```
+
+## Decision rules
+
+1. Always use read-only diagnostic commands first, then targeted fixes
+2. PM state is business truth, runtime state is execution truth — understand the gap before aligning
+3. Prefer single corrective move + re-inspect over multi-layer batch fixes
+4. Record recovery actions with `sps pm comment`
+5. After any manual intervention, run `sps monitor tick --json` to verify alignment
+6. If worker PID is dead but slot is active → next `sps tick` or `sps monitor tick` auto-recovers
+7. If tick lock is stale (owning PID dead) → safe to remove lock file
+
+## Quick decision tree
+
+```
+Problem detected
+├── sps doctor --json → config/infra issue?
+│   ├── Yes → sps doctor --fix
+│   └── No ↓
+├── sps monitor tick --json → anomaly detected?
+│   ├── Orphan worker → monitor auto-cleans, or restart tick
+│   ├── Timeout → check INPROGRESS_TIMEOUT_HOURS setting
+│   ├── State mismatch → sps pm move to align
+│   └── No ↓
+├── Which stage is stuck?
+│   ├── Planning → scheduler tick (check labels, pipeline_order, slot availability)
+│   ├── Backlog/Todo → pipeline tick (check MAX_ACTIONS_PER_TICK, worktree, branch)
+│   ├── Inprogress → worker dashboard (check PID alive, output, git push)
+│   └── QA → qa tick (check MR status, CI, merge conflicts)
+└── Still stuck → check ground truth (PM scan vs state.json) → manual recovery
+```

package/skills/sps/references/failure-patterns.md

@@ -0,0 +1,375 @@
+# SPS Common Failure Patterns (v0.16+)
+
+## Environment and setup failures
+
+### SPS CLI not found or outdated
+
+**Symptoms**: `sps: command not found` or missing v0.16+ features.
+
+**Fix**:
+```bash
+npm install -g @coralai/sps-cli
+sps --version   # Verify 0.18.0+
+```
+
+**If installed but not in PATH**:
+```bash
+npm config get prefix
+# Add <prefix>/bin to PATH in ~/.bashrc
+export PATH="$(npm config get prefix)/bin:$PATH"
+```
+
+### Global credentials missing
+
+**Symptoms**: `sps doctor` reports GitLab/Plane connection failures.
+
+**Fix**:
+```bash
+test -f ~/.coral/env && echo "exists" || sps setup
+source ~/.coral/env
+# Verify:
+echo "GITLAB_TOKEN=${GITLAB_TOKEN:+SET}"
+echo "PLANE_API_KEY=${PLANE_API_KEY:+SET}"
+```
+
+### Project not initialized
+
+**Symptoms**: `sps doctor <project>` fails with "project directory not found".
+
+**Fix**:
+```bash
+sps project init <project>
+vim ~/.coral/projects/<project>/conf    # Fill required fields
+sps doctor <project> --fix
+```
+
+---
+
+## Card lifecycle failures
+
+### Worker completed but card didn't advance
+
+**Symptoms**: Worker output shows "done" but card stays in Inprogress.
+
+**Diagnosis**:
+```bash
+sps pipeline tick <project> --json      # CompletionJudge result?
+sps worker dashboard <project>          # Worker slot status?
+```
+
+**Possible causes**:
+- Worker said "done" but didn't push code → CompletionJudge can't verify
+- Branch pushed but merge conflict → slot in "merging" state, PostActions retrying
+- Slot in "resolving" → AI Worker is resolving merge conflict (wait for it)
+- Worker slot not released → state.json still shows active/merging
+- exitCode non-zero → retry logic kicked in
+- CONFLICT label → merge failed after all retries, needs human
+
+**Fix**:
+```bash
+# Check if code was pushed:
+cd ~/.coral/worktrees/card-<seq> && git log --oneline -3
+
+# Check if branch is merged:
+git merge-base --is-ancestor HEAD origin/<target-branch> && echo "MERGED" || echo "NOT MERGED"
+
+# Re-trigger completion detection:
+sps pipeline tick <project> --json
+
+# If still stuck, manual recovery:
+sps pm move <project> <seq> Done
+sps pm comment <project> <seq> "Manual close: code verified merged"
+```
+
+### New card not entering pipeline
+
+**Symptoms**: Card created but stays in Planning, never promotes to Backlog.
+
+**Diagnosis**:
+```bash
+sps pm scan <project> Planning           # Card exists?
+sps scheduler tick <project> --json      # Promotion blocked?
+sps worker dashboard <project> --json    # Idle slots available?
+cat ~/.coral/projects/<project>/pipeline_order.json  # Card in queue?
+```
+
+**Possible causes**:
+- Missing `AI-PIPELINE` label
+- Card seq not in `pipeline_order.json`
+- `CONFLICT_DEFAULT=serial` and another card is active in same domain
+- No idle worker slots
+- Card has `BLOCKED` or `NEEDS-FIX` label
+
+**Fix**:
+```bash
+# Verify card is in queue:
+cat ~/.coral/projects/<project>/pipeline_order.json
+# If missing, re-add card or edit queue manually
+
+# Check for blocking labels in PM tool and remove if inappropriate
+
+# Check slot availability:
+sps worker dashboard <project> --json
+```
+
+### Card stuck in Backlog/Todo
+
+**Symptoms**: Card promoted to Backlog but never moves to Inprogress.
+
+**Diagnosis**:
+```bash
+sps pipeline tick <project> --json       # What happened?
+```
+
+**Possible causes**:
+- `MAX_ACTIONS_PER_TICK=1` — only one action per cycle, may need next cycle
+- `MAX_CONCURRENT_WORKERS` was increased, but the launch budget was not
+- Worktree creation failed (disk space, git permissions)
+- Worker tool (claude/codex) not found in PATH
+- All worker slots occupied
+
+**Fix**:
+```bash
+# Check configured concurrency and launch budget:
+grep -E '^(MAX_CONCURRENT_WORKERS|MAX_ACTIONS_PER_TICK)=' ~/.coral/projects/<project>/conf
+
+# Check worker availability:
+sps worker dashboard <project> --json
+
+# Check runtime slot count:
+cat ~/.coral/projects/<project>/runtime/state.json | jq '.workers | keys'
+
+# Manually trigger pipeline:
+sps pipeline tick <project> --json
+
+# Check worktree:
+ls ~/.coral/worktrees/card-<seq>/
+```
+
+Notes:
+- `MAX_CONCURRENT_WORKERS` = total simultaneous workers allowed
+- `MAX_ACTIONS_PER_TICK` = launches allowed per tick cycle
+- On SPS CLI `0.18.12+`, increasing `MAX_CONCURRENT_WORKERS` auto-expands legacy worker slots in `state.json`
+
+---
+
+## Worker process failures (v0.16+)
+
+### Worker process crashed
+
+**Symptoms**: Worker PID dead, card still in Inprogress.
+
+**Diagnosis**:
+```bash
+sps worker dashboard <project>           # Shows dead worker
+sps monitor tick <project> --json        # Detects orphan
+```
+
+**Auto-recovery**:
+- PostActions auto-retry (up to `WORKER_RESTART_LIMIT`, default 2)
+- If retry exhausted → card gets `NEEDS-FIX` label
+- On next `sps tick` startup → Recovery module detects and processes
+
+**Manual fix**:
+```bash
+# Restart tick to trigger Recovery:
+sps tick <project>
+
+# Or manually re-process:
+sps pm move <project> <seq> Todo
+sps pm comment <project> <seq> "Manual retry: worker crashed"
+```
+
+### Worker timeout
+
+**Symptoms**: Worker running longer than `INPROGRESS_TIMEOUT_HOURS` (default 8).
+
+**Diagnosis**:
+```bash
+sps monitor tick <project> --json        # Shows timeout detection
+```
+
+**Auto-recovery**: Monitor marks card with `STALE-RUNTIME` label.
+
+**Manual fix**:
+```bash
+# Check if worker is actually making progress:
+sps logs <project> --lines 50
+
+# If genuinely stuck, kill and retry:
+kill <pid>
+sps pm move <project> <seq> Todo
+sps pm comment <project> <seq> "Manual retry: worker timed out"
+```
+
+### Orphan worker (tick exited, worker still running)
+
+**Symptoms**: Worker process alive but tick process stopped.
+
+**Auto-recovery**: Next `sps tick` startup → Recovery scans state.json → detects PID → resumes monitoring or processes completion.
+
+**Manual check**:
+```bash
+cat ~/.coral/projects/<project>/runtime/state.json | jq '.workers'
+# Check each active worker PID:
+kill -0 <pid> 2>/dev/null && echo "ALIVE" || echo "DEAD"
+```
+
+---
+
+## State consistency failures
+
+### PM state vs Runtime state mismatch
+
+**Symptoms**: PM shows card in state X, but state.json shows different.
+
+**Principle**: PM is business truth, runtime is execution truth.
+
+**Diagnosis**:
+```bash
+sps pm scan <project>                     # PM truth
+cat ~/.coral/projects/<project>/runtime/state.json  # Runtime truth
+sps monitor tick <project> --json         # Detects misalignment
+```
+
+**Fix**: Use PM as source of truth:
+```bash
+sps pm move <project> <seq> <correct-state>
+sps pm comment <project> <seq> "State realignment: <reason>"
+```
+
+### Tick lock stuck
+
+**Symptoms**: `sps tick` refuses to start — "another tick process is running".
+
+**Diagnosis**:
+```bash
+cat ~/.coral/projects/<project>/runtime/tick.lock
+# Shows: PID and timestamp
+kill -0 <pid> 2>/dev/null && echo "ALIVE" || echo "DEAD"
+```
+
+**Fix** (only if owning process is dead):
+```bash
+rm ~/.coral/projects/<project>/runtime/tick.lock
+sps tick <project>
+```
+
+Or wait for `TICK_LOCK_TIMEOUT_MINUTES` (default 30) — lock auto-expires.
+
+### Pipeline order queue stale
+
+**Symptoms**: Cards exist in PM but pipeline doesn't process them.
+
+**Diagnosis**:
+```bash
+cat ~/.coral/projects/<project>/pipeline_order.json
+sps pm scan <project> Planning
+```
+
+**Fix**:
+```bash
+# Re-create cards to add to queue:
+sps card add <project> "..." "..."
+
+# Or manually edit pipeline_order.json:
+# Add missing seq numbers to the array
+```
+
+---
+
+## Skill injection failures
+
+### Worker not using expected skill profile
+
+**Symptoms**: Worker output doesn't follow expected coding patterns.
+
+**Diagnosis**:
+```bash
+# Check card labels:
+sps pm scan <project>
+# Verify: skill:<name> label exists on the card
+
+# Check profile file exists:
+ls ~/.coral/profiles/<name>.md
+
+# Check DEFAULT_WORKER_SKILLS:
+grep DEFAULT_WORKER_SKILLS ~/.coral/projects/<project>/conf
+
+# Check assembled prompt:
+cat ~/.coral/worktrees/card-<seq>/.sps/task_prompt.txt | head -50
+```
+
+**Possible causes**:
+- Label typo (e.g., `skills:react` instead of `skill:react`)
+- Profile file missing or wrong name
+- `~/.coral/profiles/` directory missing (run `sps setup`)
+- DEFAULT_WORKER_SKILLS not set and no card labels
+
+**Fix**:
+```bash
+# Check profiles directory:
+ls ~/.coral/profiles/
+
+# If missing, re-install profiles:
+sps setup --force
+
+# Create custom profile:
+cp ~/.coral/profiles/_template.md ~/.coral/profiles/<name>.md
+# Edit with domain-specific content
+```
+
+---
+
+## CLAUDE.md / AGENTS.md issues
+
+### Worker not following project rules
+
+**Symptoms**: Worker produces code that doesn't follow project standards.
+
+**Cause**: Missing or outdated CLAUDE.md in the business repo.
+
+**Fix**:
+```bash
+sps doctor <project> --fix                 # Generates CLAUDE.md if missing
+vim ~/projects/<project>/CLAUDE.md         # Customize with project standards
+cd ~/projects/<project> && git add CLAUDE.md && git commit -m "chore: update worker rules"
+```
+
+### Worktree missing CLAUDE.md
+
+**Cause**: CLAUDE.md was added after worktree was created.
+
+**Fix**: Worktrees inherit from the parent repo. If CLAUDE.md was committed to the target branch, new worktrees will have it. For existing worktrees:
+```bash
+cd ~/.coral/worktrees/card-<seq>
+git checkout origin/<target-branch> -- CLAUDE.md
+```
+
+---
+
+## Multi-project failures
+
+### One project failing, others OK
+
+Each project has fully isolated context. One project's failure does not affect others.
+
+**Diagnosis**:
+```bash
+sps worker dashboard                       # All projects overview
+sps doctor <failing-project> --json        # Check specific project
+```
+
+### Global worker limit reached
+
+**Symptoms**: New cards not launching even though project has idle slots.
+
+**Cause**: `SPS_MANAGER_MAX_WORKERS` (default 30) reached across all projects.
+
+**Fix**:
+```bash
+sps worker dashboard --json | jq '.summary'
+# Check total active workers
+# Either wait for workers to complete or increase limit:
+export SPS_MANAGER_MAX_WORKERS=50
+```

package/skills/sps/references/labels.md

@@ -0,0 +1,78 @@
+# Label system
+
+任务卡的标签体系:自动标签、Skills(--skill)、conflict 域标签、系统托管的辅助状态标签。
+
+### 2.3 Label system
+
+Labels control pipeline behavior. Some are automatic, some must be added manually.
+
+### Automatic labels (do not add manually)
+
+| Label | Added by | Purpose |
+|-------|----------|---------|
+| `AI-PIPELINE` | `sps card add` | Marks card as pipeline-eligible. Only cards with this label enter automation |
+
+### Skills (set at card-add time via `--skill`)
+
+Set skills with `sps card add … --skill <type>` — this writes the skill into the card frontmatter. Recommended: one skill per card. Agent 在建卡时根据任务类型自动判定。
+
+**Task type → skill mapping:**
+
+| Task type | `--skill` | Worker role | Deliverables |
+|-----------|-------|-------------|-------------|
+| 架构设计、技术方案 | `architect` | Software Architect | ADR、设计文档、目录结构、技术选型 |
+| 前端开发 | `frontend` | Frontend Developer | 组件、页面、样式、前端测试 |
+| 后端开发 | `backend` | Backend Developer | API、DB migration、服务端逻辑、后端测试 |
+| 全栈开发（含前后端） | `fullstack` | Full-stack Developer | 前后端 + DB 一体化实现 |
+| 快速原型 / MVP | `prototyper` | Rapid Prototyper | 可运行的最小可用产品 |
+| 代码审查 / 优化 | `reviewer` | Code Reviewer | Review 报告 + 修复 commit |
+| 安全加固 / 审计 | `security` | Security Engineer | 审计报告 + 漏洞修复 |
+| 技术文档 / PRD | `writer` | Technical Writer | README、API 文档、PRD、CHANGELOG |
+| 性能 / 成本优化 | `optimizer` | Performance Optimizer | Benchmark 报告 + 优化 commit |
+| 通用 / 不确定 | `senior` | Senior Developer | 高质量通用实现（兜底） |
+
+**Special skills** (语言/框架特化):
+
+| `--skill` | Purpose |
+|-------|---------|
+| `typescript` | TypeScript 语言严格模式规范 |
+| `phaser` | Phaser 3 游戏开发 |
+
+**Rules:**
+- 推荐一张卡片一个技能 — 避免多个 skill 之间指令冲突（`--skill a,b` 支持多个,逗号分隔)
+- Agent 建卡时应根据任务描述自动判定
+- 如果卡片没有指定技能，fallback 到 `DEFAULT_WORKER_SKILLS` 配置
+- Skill 文件位于 `~/.coral/skills/<name>/SKILL.md`
+
+**Project-wide default (当卡片没有 skill 标签时的 fallback):**
+```bash
+# In ~/.coral/projects/<project>/conf:
+export DEFAULT_WORKER_SKILLS="senior"
+```
+
+### Conflict domain labels (manual, optional)
+
+Format: `conflict:<domain>`
+
+```
+conflict:auth       → cards touching auth module run serially
+conflict:database   → cards touching DB schema run serially
+conflict:api        → cards touching API routes run serially
+```
+
+- Same-domain cards never run in parallel (prevents merge conflicts)
+- Cards without conflict labels follow `CONFLICT_DEFAULT` config:
+  - `serial` (default): all unlabeled cards share a global domain (true serial)
+  - `parallel`: unlabeled cards can run in parallel (use when tasks are independent)
+
+### Auxiliary state labels (system-managed, do not add manually)
+
+| Label | Set by | Meaning | Effect |
+|-------|--------|---------|--------|
+| `BLOCKED` | Manual or Monitor | External dependency blocks progress | Card skipped in pipeline |
+| `NEEDS-FIX` | Closeout/PostActions | Worker or CI failed | Card skipped, needs manual fix |
+| `WAITING-CONFIRMATION` | Worker output | Awaiting user approval | Card skipped until resolved |
+| `CONFLICT` | Closeout | Git merge conflict detected | Card skipped, needs resolution |
+| `STALE-RUNTIME` | Monitor | Worker process anomaly | Card skipped, auto-cleanup |
+
+Cards with any auxiliary state label are **never launched** — they must be resolved first.

package/skills/sps/references/monitoring.md

@@ -0,0 +1,61 @@
+# Monitor workers
+
+监控 worker 的命令:项目状态、worker dashboard、确认应答、日志、PM 状态。
+
+## 4. Monitor workers
+
+### Project status overview
+
+```bash
+sps status                             # List all projects with tick/worker status
+sps status --json                      # JSON output
+```
+
+### Worker dashboard
+
+```bash
+sps worker dashboard                   # Real-time TUI (all projects)
+sps worker dashboard <project>         # Filter to specific project
+sps worker dashboard --once            # Single snapshot
+sps worker dashboard --json            # JSON output for scripts
+```
+
+**Dashboard keyboard shortcuts:**
+- `q` — quit
+- `r` — force refresh
+- `:` — enter respond mode (when Workers have pending confirmations)
+
+**Responding to Worker confirmations in dashboard:**
+```
+When a Worker needs confirmation, bottom bar shows numbered pending list:
+  Pending confirmations:
+  1. brick/worker-1 DANGEROUS: Execute rm -rf node_modules [1=Yes, 2=No, 3=Always]
+
+Press `:` then type: <number> <option>
+  1 3     → send option 3 to pending #1
+  1 1     → send option 1 (default) to pending #1
+  Enter to send, Escape to cancel
+```
+
+### Worker confirmations (CLI)
+
+```bash
+sps acp pending <project>                    # List pending confirmations
+sps acp respond <project> <slot> "<reply>"   # Send response
+```
+
+### View logs
+
+```bash
+sps logs <project>                     # Real-time log viewer (pm2-style)
+sps logs <project> --err               # Error logs only
+sps logs <project> --lines 50          # Last 50 lines
+```
+
+### Inspect PM state
+
+```bash
+sps pm scan <project>                  # All cards
+sps pm scan <project> Inprogress       # Filter by state
+sps pm scan <project> Todo             # Filter by state
+```

package/skills/sps/references/mr-and-recovery.md

@@ -0,0 +1,74 @@
+# MR mode, recovery & extras
+
+MR 合并流、恢复原则、worker rules 文件、项目知识传递,以及附加接口(console/graph/memory 等)。
+
+## 6. MR mode and merge flow (v0.19+)
+
+| MR_MODE | Worker does | PostActions does | Use case |
+|---------|------------|------------------|----------|
+| `none` (default) | code → push → say "done" | Serial merge queue (rebase + merge) | Fully automated |
+| `create` | code → push → say "done" | Create GitLab MR | Requires human review |
+
+**Worker does NOT run merge.** Merge is handled by PostActions (serial via MergeMutex):
+
+```
+Worker A/B/C code in parallel → push → exit
+  ↓
+PostActions serial merge queue (one at a time):
+  L0: fetch + rebase + merge (pure git) → success → Done
+  L1: rebase conflict → abort
+  L2: spawn --resume Worker to resolve conflict → retry L0
+  L3: all retries exhausted → CONFLICT label → human
+```
+
+Slot status during merge: `merging` (waiting/executing) or `resolving` (AI fixing conflict). New cards are NOT assigned to these slots.
+
+---
+
+## 8. Recovery principles
+
+- Respect SPS as the state authority
+- Do not mutate multiple layers blindly at once
+- Prefer one corrective move, then re-inspect
+- Record meaningful interventions using PM comments
+- Do not reintroduce legacy shell entrypoints as the main interface
+- Do not treat worker completion as sufficient without SPS confirmation
+- On tick restart, Recovery automatically detects orphan workers (PID scan + state.json), judges completion, and executes post-actions
+- Worker processes survive tick restart (detached mode with fd redirect) — next tick picks up where the previous left off
+- CompletionJudge checks: marker file → branch pushed → already merged (merge-base) → auto-push → keywords
+
+---
+
+## 9. Worker rules files
+
+`sps doctor --fix` generates and commits these files to the business repo:
+
+| File | Purpose | In git |
+|------|---------|--------|
+| `CLAUDE.md` | Project rules for Claude Code workers | Yes |
+| `.sps/task_prompt.txt` | Per-task prompt (auto-generated per worktree) | No (.gitignore) |
+| `.sps/merge.sh` | Merge/MR script (auto-generated, manual fallback only) | No (.gitignore) |
+| `docs/DECISIONS.md` | Architecture decisions from previous workers | Yes (auto-maintained) |
+| `docs/CHANGELOG.md` | Change log from previous workers | Yes (auto-maintained) |
+
+These files are inherited by all git worktrees. SPS will not overwrite an existing CLAUDE.md.
+
+---
+
+## 10. Project knowledge transfer
+
+Each worker is instructed to:
+- **Before coding**: read `docs/DECISIONS.md` and `docs/CHANGELOG.md` for context
+- **After coding**: append architecture decisions and change summaries
+
+Files are merged to the target branch with the code, so the next worker inherits all accumulated knowledge.
+
+---
+
+## 11. Additional interfaces
+
+- **Web console** — `sps console [--port N] [--no-open] [--kill]` launches the local SPS Console UI (board, chat, logs) in the browser.
+- **Code graph** — `sps graph build|sync|status|explore|impact <...>` builds a project-level code graph (codegraph). `sps graph explore <keyword>` is the token-cheap way for a worker to pull an entry point + related symbols + call chains.
+- **Project memory** — `sps memory list|search|add|ingest|context <project>` manages per-project memory (agentmemory-backed); memory is auto-injected into worker prompts.
+- **Skills** — `sps skill list|add|remove|sync` manages worker skills (see section 5).
+- **Reset / re-run** — `sps reset <project> [--all] [--card N,N]` resets card state and cleans its worktree + branch for a fresh run.