peaks-cli 1.2.7 → 1.2.9

package/skills/peaks-solo/references/workflow-gates-and-types.md

@@ -0,0 +1,177 @@
+# Peaks-Cli Workflow Order + Request Type Classification + Transition Verification Gates
+
+> **Maintenance**: This reference holds the canonical contract for (a) how Solo sequences the 11 workflow steps, (b) which `--type` to pass to `peaks request init` for which slice shape, and (c) the executable `ls` / `grep` gate commands that physically block progression. SKILL.md keeps the narrative ("what peaks-solo does"); this file keeps the contract.
+>
+> **Why extracted from SKILL.md**: this content is 165 lines of mostly-tabular + bash-block contract — reference data, not orchestration prose. Inlining it bloats SKILL.md past the 800-line cap (per `common/coding-style.md`). The numbers, gate command shapes, and type-classification rules change rarely; the SKILL.md prose around them (orchestration flow, repair-loop intent, swarm fan-out shape) changes more often.
+>
+> **How peaks-cli tooling reads this file**:
+> - `peaks skill runbook peaks-solo` (CLI) and the in-line LLM reading the SKILL.md should reference this file when the gate-machine or type-classification contract is in play.
+> - The test `tests/unit/skill-default-runbook.test.ts` does NOT check this file (it only checks the runbook). Future tests can add a similar fallback for the gates-and-types contract.
+
+## Peaks-Cli Request type classification (MANDATORY before `peaks request init`)
+
+Before initializing any role artifact, classify the request into exactly one of six types. The choice drives RD/QA gate strictness (see "Mandatory RD QA repair loop"). Pick the **primary intent** — if a request could fit two types, the higher-strictness one wins.
+
+| `--type` | Pick this when the PRD says... | Pick something else when... |
+|---|---|---|
+| `feature` | Add new capability, new page/component/route/API path, new user-facing behavior. Includes "extend X to support Y" when Y is a new code path. | The PRD is fixing an existing broken behavior → `bugfix`. The PRD is reshaping existing code without changing user-visible behavior → `refactor`. |
+| `bugfix` | Fix a specific broken behavior; PRD includes reproduction steps or a defect description; success = "the broken thing now works as it was supposed to". | The "fix" actually adds new capability (validation that didn't exist, a missing field) → `feature`. The "fix" is purely cosmetic and has zero risk → still `bugfix`; do NOT downgrade to `chore`. |
+| `refactor` | Restructure code without changing user-visible behavior. Examples: rename modules, extract shared utilities, migrate a library version with no API surface change, split a monolithic file. PRD mentions coverage targets or "no behavior change". | The refactor incidentally adds or changes user-visible behavior → split into `refactor` + `feature` or pick `feature`. The change is one-line formatting → `chore`. |
+| `config` | Modify config / infrastructure files only: `tsconfig.json`, `eslint`, CI YAML, `package.json` scripts, env defaults, CORS/CSP rules, build config, Docker, deployment manifests. No application source-code changes. | The config change is paired with code changes that consume the new config → `feature` or `refactor` (whichever the code change is). |
+| `docs` | Modify only `*.md` / docs site / inline JSDoc / README. No `.ts` / `.tsx` / `.js` / `.css` / config-file changes. | Any source code change is included → use the type matching the code change. Adding a code example to docs that requires the example to compile → still `docs` if the example is illustrative only. |
+| `chore` | Pure mechanical hygiene: formatter run, lint fix, dependency version bump with no API surface change, dead-code removal of unused files identified by tooling. | The bump changes API behavior or requires consumer migration → `refactor` (or `feature` if it adds capability). Any logic edit → `bugfix` or `refactor`. |
+
+**Self-check before locking the type**: read the PRD scope and answer "what is the smallest gate set that still protects users from regression?" — that is the right type. Picking `docs` or `chore` to skip gates when source code is actually changing is a workflow violation and the SC phase will reject it.
+
+For ambiguous cases (e.g. "improve login flow"), ask the user to clarify before initializing. The cost of one `AskUserQuestion` round is much lower than running the wrong gate matrix for the whole workflow.
+
+When Peaks-Cli Solo coordinates development in a code repository, keep this order explicit:
+
+0. **Peaks-Cli Snapshot** — `peaks doctor` + `peaks project dashboard` to capture baseline state before anything else;
+0.5. **Peaks-Cli Workspace initialization** — `.peaks/<session-id>/` created, directory structure verified;
+0.6. **Peaks-Cli Project scan** — archetype, component library, CSS framework, build tool, state management, routing, data fetching, legacy signals detected and recorded to `.peaks/<session-id>/rd/project-scan.md`;
+0.7. **Peaks-Cli Existing-system extraction** (MANDATORY when archetype ∈ {legacy-frontend, legacy-fullstack, frontend-monorepo}; SKIP for greenfield) — extract visual tokens and code conventions from the live codebase to `.peaks/<session-id>/system/existing-system.md`. The path lives under `system/` (not `ui/`) because the file also records non-UI conventions (service-layer signatures, hooks, naming) that backend-only or legacy-fullstack work consumes. See `references/existing-system-extraction.md`. UI design-draft and RD implementation MUST treat the extracted tokens and conventions as hard constraints;
+1. **Peaks-Cli Standards preflight** — `peaks standards init/update --dry-run`, must reference concrete project-scan findings (never emit generic templates);
+2. **Peaks-Cli PRD phase** — capture request as canonical artifact, extract scope and acceptance criteria:
+   - Full-auto/Swarm: auto-transition to `confirmed-by-user` once the artifact is complete;
+   - Assisted/Strict: pause with `AskUserQuestion` for explicit user confirmation before proceeding;
+3. **Peaks-Cli Swarm parallel phase** — after PRD confirmed, launch UI, RD(planning), QA(test-cases) simultaneously:
+   3a. UI design draft and visual direction (MANDATORY when request is frontend/user-visible; skipped for `--type docs|chore|config` or pure-backend requests);
+   3b. RD planning artifact — `rd/tech-doc.md` for feature/refactor, `rd/bug-analysis.md` for bugfix, skipped for docs/chore/config;
+   3c. QA test-case generation (skipped for docs/chore — no acceptance surface to validate);
+4. **Peaks-Cli RD implementation** — consumes the type-appropriate inputs: project-scan + standards + (if UI involved) UI design-draft + RD planning artifact + QA test-cases. Includes unit tests for new/changed behavior (TDD) unless `--type` is docs/chore;
+5. **Peaks-Cli Code review + security review** — CRITICAL/HIGH issues fixed before progression; marked-blocked issues only allow a blocked handoff;
+6. **Peaks-Cli QA validation** (auto-proceed from RD in full-auto) — execute test cases + API checks + Playwright MCP headed browser E2E for frontend + security/perf checks + test report;
+7. **Peaks-Cli RD↔QA repair loop** — if QA verdict is `return-to-rd`, loop back to step 4 (RD implementation) and re-run through QA; max 3 repair cycles, then emit blocked TXT regardless;
+8. **Peaks-Cli SC phase** — change-control evidence: impact, retention, validate, boundary;
+9. **Peaks-Cli OpenSpec archive** — exit gate: validate → archive only after QA verdict=pass (when `openspec/` exists);
+10. **Peaks-Cli TXT handoff capsule** — mode, validated decisions, artifact paths, standards deltas, open questions, next action;
+11. **Peaks-Cli Final snapshot** — `peaks project dashboard` + `peaks skill doctor` to confirm the workflow closed cleanly.
+
+### Peaks-Cli Transition verification gates (MANDATORY — run the command, see the output)
+
+You cannot declare a phase complete from memory. Each gate below is a `ls` command you **MUST run** and whose output you **MUST see** before proceeding. If any file shows "No such file", the phase is incomplete.
+
+**Peaks-Cli Gate A — After workspace init + project scan:**
+```bash
+ls .peaks/<id>/rd/project-scan.md
+# Expected output: .peaks/<id>/rd/project-scan.md
+# "No such file" → STOP, run project scan first
+# File present but missing `## Archetype` or `## Project mode` sections → INCOMPLETE, rerun scan
+# File present and complete → reuse (project-scan is a session-scoped singleton)
+```
+
+**Peaks-Cli Gate A.5 — Existing-system extraction (legacy projects only):**
+```bash
+# If project-scan.md `## Archetype` is greenfield → skip this gate
+# Otherwise:
+ls .peaks/<id>/system/existing-system.md
+# "No such file" → STOP, run existing-system extraction
+# (see references/existing-system-extraction.md)
+```
+
+**Peaks-Cli Gate B — After swarm convergence (UI + RD planning + QA test-cases):**
+
+Peaks-Cli Gate B has two sub-checks: a HARD gate (blocks progression) and an INFORMATIONAL check (records degradation but does not block).
+
+```bash
+# B.hard — REQUIRED before continuing to RD implementation.
+#          Missing any of these → STOP, return to the role that owns the file.
+
+# Always required (every type):
+ls .peaks/<id>/prd/requests/<rid>.md
+
+# Type-specific RD planning artifact:
+#   feature / refactor → ls .peaks/<id>/rd/tech-doc.md
+#   bugfix             → ls .peaks/<id>/rd/bug-analysis.md
+#   config / docs / chore → (no RD planning artifact required)
+
+# QA test-cases (skipped for docs/chore):
+ls .peaks/<id>/qa/test-cases/<rid>.md
+```
+
+```bash
+# B.info — NON-BLOCKING. Record degradation in TXT, then proceed.
+ls .peaks/<id>/ui/design-draft.md 2>&1
+# "No such file" + request affects user-visible UI → swarm degradation rule 1 fires:
+#   note "ui-design-missing" in TXT, RD continues with PRD visual descriptions.
+# "No such file" + pure backend / docs / chore / config → state skip reason in TXT, proceed.
+```
+
+**Peaks-Cli Gate C — After RD implementation (before QA handoff):**
+
+The CLI gate (`peaks request transition --state qa-handoff`) is the authoritative check; running this `ls` first lets you produce missing files before the CLI rejects the transition.
+
+```bash
+# Always required
+ls .peaks/<id>/rd/requests/<rid>.md
+
+# Type-specific RD evidence (must match the type recorded in the artifact body)
+#   feature / refactor → ls rd/tech-doc.md rd/code-review.md rd/security-review.md rd/perf-baseline.md qa/test-cases/<rid>.md
+#                         (qa/test-cases/<rid>.md pre-drafted by the 4th sub-agent in peaks-rd's parallel fan-out — slice 004)
+#   bugfix             → ls rd/bug-analysis.md rd/code-review.md rd/security-review.md qa/test-cases/<rid>.md
+#                         (rd/perf-baseline.md only when the bug is performance-shaped)
+#   config             → ls rd/security-review.md
+#   docs / chore       → (no extra evidence required)
+# Missing any required file → DO NOT attempt the qa-handoff transition; CLI will reject with PREREQUISITES_MISSING.
+```
+
+**Peaks-Cli Gate D — After QA validation:**
+
+The CLI gate at `qa:verdict-issued` is the authoritative check; this `ls` lets you produce missing evidence before the CLI rejects the transition.
+
+```bash
+# Always required
+ls .peaks/<id>/qa/requests/<rid>.md
+
+# Type-specific QA evidence
+#   feature / refactor → ls qa/test-cases/<rid>.md qa/test-reports/<rid>.md qa/security-findings.md qa/performance-findings.md
+#   bugfix             → ls qa/test-cases/<rid>.md qa/test-reports/<rid>.md qa/security-findings.md
+#   config             → ls qa/security-findings.md
+#   docs / chore       → (no QA evidence files required)
+# Missing required file → QA incomplete; do not transition to verdict-issued.
+```
+
+**Peaks-Cli Gate E — Before declaring workflow complete:**
+```bash
+find .peaks/<id>/ -type f | sort
+# Verify: files from gates A-D all appear in this list.
+# Any mandatory file missing → NOT complete. Do not emit TXT.
+# Peaks-Cli Gate G (CLAUDE.md + .claude/rules/**) must ALSO pass before TXT is emitted.
+```
+
+**Peaks-Cli Gate F — Root pollution check (BLOCKING before completion):**
+```bash
+# Verify no Peaks-Cli intermediate artifacts leaked to project root.
+ls feishu-doc-*.md *-snapshot.md qa-server.js 2>&1
+# Expected: "No such file or directory" for ALL patterns.
+# Any file found → ROOT POLLUTION. Move it to .peaks/<id>/prd/source/
+# (for doc snapshots) or .peaks/<id>/qa/ (for QA artifacts).
+# Note the migration in TXT handoff. Do NOT complete the workflow
+# with intermediate artifacts in the project root.
+```
+```bash
+# Extended check for common leak patterns
+find . -maxdepth 1 -name "*.png" -o -name "*.jpg" -o -name "qa-*.js" -o -name "mock-server.*" 2>&1
+# Any Peaks-Cli QA/UI intermediate files here → ROOT POLLUTION. Move and note.
+# Legitimate project files (e.g. favicon.png) are fine — only move Peaks-Cli artifacts.
+```
+
+**Peaks-Cli Gate G — Project standards present (BLOCKING before workflow completion):**
+```bash
+# After `peaks standards init/update --apply`, verify the files actually landed
+# at the project root. The CLAUDE.md and rules files are required so that
+# subsequent peaks-rd / peaks-qa / peaks-solo runs perform the project-local
+# preflight described in CLAUDE.md (read coding-style.md, code-review.md, security.md).
+ls <repo>/CLAUDE.md
+# "No such file" → BLOCKED. Run `peaks standards init --project <repo> --apply --json`
+# (first time) or `peaks standards update --project <repo> --apply --json` (existing).
+ls <repo>/.claude/rules/common/coding-style.md \
+   <repo>/.claude/rules/common/code-review.md \
+   <repo>/.claude/rules/common/security.md
+# Any "No such file" → BLOCKED. The standards apply step did not complete; re-run
+# standards init/update with --apply and re-verify.
+# Skipping Peaks-Cli Gate G (e.g. because the user did not explicitly authorize writes) is
+# only acceptable in `assisted`/`strict` modes where the user actively declined; in
+# `full-auto`/`swarm` the absence of these files is a workflow violation.
+```

package/skills/peaks-solo-resume/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: peaks-solo-resume
+description: Resume an in-flight peaks-solo slice in the current session. Use when the user says "continue the unfinished work", "继续完成", "把刚才没做完的收尾", or invokes `/peaks-solo-resume` directly. Detects the current session's deepest completed gate (via the Step 0.7 detection script at `tests/fixtures/skill-resume-mode-detect.sh`) and surfaces a resume option via `AskUserQuestion`. Triggers on `/peaks-solo-resume`, "继续完成刚才的", "resume the unfinished slice", "把刚才没做完的收尾".
+---
+
+# Peaks-Cli Solo Resume (wrapper)
+
+Peaks-Cli Solo Resume is a thin wrapper that handles the **most common high-frequency request shape**: "I was in the middle of something, continue it." It detects the current session's deepest completed gate, surfaces a resume option, then yields to the main `peaks-solo` skill (which runs the actual workflow from the matching gate onwards).
+
+**This is a transparent wrapper.** The user does not stay in this skill — once the resume option is confirmed, control hands off to `peaks-solo`. The wrapper exists only to (a) detect the in-flight slice without the LLM re-reading 3-5 artifact files, and (b) surface the resume option as a `AskUserQuestion` before the main loop skips ahead.
+
+## Skill presence (MANDATORY first action)
+
+```bash
+peaks skill presence:set peaks-solo-resume --project <repo> --mode <mode> --gate startup
+peaks project memories --project <repo> --json  # load durable memory
+```
+
+## Step 1: Detect the current session's in-flight slice
+
+Use the Step 0.7 detection script (added in slice 003) to classify the current session:
+
+```bash
+# 1. Confirm the current session id
+sid=$(cat .peaks/.session.json | python3 -c "import sys,json; print(json.load(sys.stdin)['sessionId'])")
+
+# 2. Run the detection script
+bash tests/fixtures/skill-resume-mode-detect.sh "$sid" .peaks
+# Possible outputs: fresh | complete | resume:rd-planning | resume:qa-validation
+#                  | resume:txt-handoff | in-flight:<state>
+```
+
+## Step 2: Branch on the detection
+
+**If `fresh`**: no in-flight slice. Tell the user "No in-flight slice in this session." Then hand off to `peaks-solo` for a fresh start (set presence back, then run `peaks workspace init --project <repo> --json` and continue with Step 1 of `peaks-solo`).
+
+**If `complete`**: the workflow is already done. Tell the user "This session is complete — your previous slice already shipped." Then suggest a fresh start (`peaks-solo`) or close-out.
+
+**If `resume:<gate>`**: surface a resume option via `AskUserQuestion`:
+
+| Option | What it does |
+|---|---|
+| Resume from `<gate>` (Recommended) | Hand off to `peaks-solo` with the gate already at the matching point. The main loop skips ahead; the existing artifacts are preserved as-is. |
+| Start a fresh slice | Treat the current request as a new slice (new `rid`). Existing artifacts are preserved but not auto-resumed. |
+| Abandon the in-flight slice | Mark the in-flight slice as `deferred` (`peaks request transition <rid> --role rd --state deferred --reason "user abandoned"`) and start fresh. |
+
+**If `in-flight:<state>`**: the slice is mid-implementation. Surface a CONFIRM (not a resume):
+
+> "The slice is mid-implementation (state: `<state>`). The only valid option is to resume the in-flight gate. Continue?"
+
+Use `AskUserQuestion` with a single option (Confirm and resume from `<state>`). Do NOT auto-resume mid-implementation.
+
+## Step 3: Hand off to peaks-solo
+
+After the user confirms, **re-assert `peaks-solo` presence** so the status header reads correctly for the rest of the run:
+
+```bash
+peaks skill presence:set peaks-solo --project <repo> --mode <mode> --gate <matching-gate>
+```
+
+Then tell the user: "Resuming from `<gate>`. The main peaks-solo skill will take over from there." and yield control. The user's next message will land in the `peaks-solo` main loop, which will pick up the workflow from the matching gate.
+
+## Hard rules (do NOT skip)
+
+- **Never silently auto-resume.** Always use `AskUserQuestion` first. The detection is a discovery; the user's confirmation is the gate.
+- **Never auto-resume mid-implementation.** For `in-flight:<state>`, the only valid option is "Confirm and resume from `<state>`" — never "Start a fresh slice" or "Abandon" without the user's explicit choice.
+- **Never write code or modify files in this skill.** This is a wrapper. The actual work (PRD, RD, QA, SC, TXT) is the main `peaks-solo` skill's job.
+- **Never add a new `peaks <cmd>`.** Use the existing CLI primitives: `peaks workspace init`, `peaks project dashboard`, `peaks session list`, `peaks skill runbook`, `peaks skill doctor`, `peaks scan archetype`, `peaks request transition`. The detection script (`tests/fixtures/skill-resume-mode-detect.sh`) is the only executable this skill invokes.
+
+## Anti-patterns (do NOT do)
+
+- Do NOT re-read 3-5 artifact files to determine the workflow state. The detection script does this in <1ms; re-reading is the bug Step 0.7 was added to prevent.
+- Do NOT skip the `AskUserQuestion` even if the user says "just continue". The user might have changed their mind, or there might be multiple in-flight slices.
+- Do NOT write to `.peaks/<sid>/` files. This skill is read-only on the workspace; it only reads `.peaks/.session.json` + runs the detection script.
+- Do NOT run `peaks workspace init` on a real session (would bind a new session id). Only run it on a fresh detection where no session exists.
+
+## Cross-references
+
+- The detection logic is canonical at `tests/fixtures/skill-resume-mode-detect.sh` (added in slice 003). The 8 vitest cases in `tests/unit/skill-resume-mode.test.ts` cover all classification outcomes.
+- The SKILL.md prose at `skills/peaks-solo/SKILL.md` Step 0.7 (added in slice 003) is the same logic, written for LLM consumption. This wrapper reuses the same script — there is no parallel implementation.
+- The "drives a CLI on the user's behalf" pattern (mirror of `peaks-sop`) is the closest existing precedent for this wrapper.

package/skills/peaks-solo-status/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: peaks-solo-status
+description: Show the current state of the peaks-solo orchestrator in a compact summary. Use when the user says "what's the current state", "现在到哪了", "where are we", or invokes `/peaks-solo-status` directly. Reads the existing CLI primitives (`peaks skill presence`, `peaks session list`, `peaks project dashboard`, `peaks request show`) and renders a 1-screen status table. Triggers on `/peaks-solo-status`, "现在到哪了", "what is the current state", "show me the dashboard", "where are we".
+---
+
+# Peaks-Cli Solo Status (wrapper)
+
+Peaks-Cli Solo Status is a thin wrapper that renders a compact status table for the current peaks-solo orchestrator state. It is the answer to "I just want to know where we are" — no PRD, no RD, no QA, no full peaks-solo orchestration. Just read the existing CLI state and render a 1-screen summary.
+
+**This is a transparent wrapper.** The user does not stay in this skill — the status table is rendered, and control hands off (back to the user, or to `peaks-solo` if the user wants to act on the status).
+
+## Skill presence (MANDATORY first action)
+
+```bash
+peaks skill presence:set peaks-solo-status --project <repo> --mode <mode> --gate startup
+peaks project memories --project <repo> --json  # load durable memory
+```
+
+## Step 1: Read the current state
+
+Use only existing CLI primitives (no new commands). **Important contract note**: `peaks session list` does NOT support `--project` (verified by dogfood 2026-06-04); it returns all sessions globally. To scope to the current project, read `.peaks/.session.json` for the bound `sessionId`, then use `peaks session info <sid>` for the bound session's full state, and filter `peaks session list` output by `projectRoot` to find other sessions in the same project.
+
+```bash
+# 1. Active skill presence
+peaks skill presence --json
+
+# 2. The bound session id (from .peaks/.session.json — local read, no CLI)
+sid=$(cat .peaks/.session.json | python3 -c "import sys,json; print(json.load(sys.stdin)['sessionId'])")
+
+# 3. The bound session's full state
+peaks session info "$sid" --json
+
+# 4. All sessions globally (then post-filter to current project)
+peaks session list --json
+# Note: this returns all sessions across all projects; the wrapper filters by
+# matching `projectRoot` against the bound session's `projectRoot` to show only
+# the sessions for THIS project. Sessions from other projects are ignored.
+
+# 5. Per-request role state (PRD / RD / QA / TXT for the bound project)
+peaks project dashboard --project <repo> --json
+
+# 6. Per-request detail (if a specific rid is in flight)
+peaks request show <rid> --role rd --project <repo> --json
+peaks request show <rid> --role qa --project <repo> --json
+```
+
+All 6 calls are read-only. Total cost: sub-second. (The original draft said "5 calls"; the corrected count is 6 because the post-filter step is now explicit.)
+
+## Step 2: Render the status table
+
+Compact 1-screen format:
+
+```
+=== peaks-solo status ===
+Session:   2026-06-04-session-b60252
+Active:    peaks-solo (mode: full-auto, gate: qa-validation)
+Workspace: /Users/yuanyuan/.../peaks-cli/.peaks/2026-06-04-session-b60252
+
+| Role | State          | Artifact                |
+|------|----------------|-------------------------|
+| PRD  | handed-off     | prd/requests/003.md     |
+| RD   | qa-handoff     | rd/requests/003.md      |
+| QA   | running        | qa/requests/003.md      |
+| TXT  | (not started)  | -                       |
+
+QA verdict: pending
+Last activity: 2026-06-04T17:00:00.000Z (12 min ago)
+Standards: 5/5 existing (no delta)
+Health: skill-doctor 35/35 pass
+```
+
+If the session is fresh (no in-flight slice), render a different layout:
+
+```
+=== peaks-solo status ===
+Session: 2026-06-04-session-b60252
+Active:  peaks-solo (mode: full-auto, gate: startup)
+Workspace: /Users/yuanyuan/.../peaks-cli/.peaks/2026-06-04-session-b60252
+
+No in-flight slice. Ready for a new request.
+Health: skill-doctor 35/35 pass
+```
+
+## Step 3: Ask the user what to do next
+
+| Option | What it does |
+|---|---|
+| Continue from the current gate | Hand off to `peaks-solo` with the gate already at the current state. Existing artifacts are preserved. |
+| Open a new slice in this session | Keep the workspace, treat the current request as a new slice (new `rid`). |
+| Just summarize and exit | No further action; the user will decide later. |
+
+## Step 4: Hand off (if user picked option 1 or 2)
+
+Re-assert `peaks-solo` presence so the status header reads correctly for the rest of the run:
+
+```bash
+peaks skill presence:set peaks-solo --project <repo> --mode <mode> --gate <matching-gate>
+```
+
+Then yield control.
+
+## Hard rules (do NOT skip)
+
+- **Never write to `.peaks/<sid>/`.** This skill is read-only on the workspace; it only reads existing CLI state.
+- **Never add a new `peaks <cmd>`.** Use only the existing read-only CLI primitives: `peaks skill presence`, `peaks session list`, `peaks session info`, `peaks project dashboard`, `peaks request show`. **Note**: `peaks session list` does not support `--project`; filter its output by `projectRoot` post-hoc.
+- **Never auto-progress the workflow.** The status table is informational only. The user chooses what to do via `AskUserQuestion`. Never silent about what comes next — always present the 3 options.
+- **Never expose sensitive data in the table.** Do NOT include full PRD bodies, full tech-doc bodies, or any test code in the table. Just state names, paths, and counts.
+
+## Anti-patterns (do NOT do)
+
+- Do NOT run `peaks workspace init` on the real session. The wrapper is read-only.
+- Do NOT run `peaks request transition` (would change state). The wrapper is informational only.
+- Do NOT write the status to a file (e.g. `.peaks/<sid>/status.md`). The user can see it in the chat; persisting it adds noise to the workspace.
+- Do NOT block on slow CLI calls. The 5 read-only calls are sub-second each. If any takes >5s, fail fast and report the slow command.
+
+## Cross-references
+
+- The "drives a CLI on the user's behalf" pattern (mirror of `peaks-sop`) is the closest existing precedent.
+- `peaks-solo-resume` (P2.1) and `peaks-solo-test` (P2.2) are the sibling wrappers. `peaks-solo-resume` focuses on workflow-state introspection + resume decision; `peaks-solo-status` is the broader 5-CLI snapshot. The two are complementary, not redundant.
+- The "read 5 CLI primitives, render 1 table" pattern is intentionally minimal — the wrapper does NOT add a new status-introspection CLI command (would violate the dev-preference.md "default-no on new CLI" rule).

package/skills/peaks-solo-test/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: peaks-solo-test
+description: Run the project's test suite on the current repo and report results. Use when the user says "run the tests", "跑一下 test", "跑测试", or invokes `/peaks-solo-test` directly. Runs `pnpm vitest run` (or the project's equivalent test command), captures pass/fail counts and any failures, and surfaces a compact summary. Triggers on `/peaks-solo-test`, "跑一下 test", "跑测试", "run the tests", "test now".
+---
+
+# Peaks-Cli Solo Test (wrapper)
+
+Peaks-Cli Solo Test is a thin wrapper that runs the project's test suite on the current repo and reports results. It is the answer to "I just want to see if the tests pass" — no PRD, no RD, no QA, no full peaks-solo orchestration. Just `pnpm vitest run` and a compact summary.
+
+**This is a transparent wrapper.** The user does not stay in this skill — the test command runs, the result is summarized, and control hands off (back to the user, or to `peaks-solo` if the user wants to act on the result).
+
+## Skill presence (MANDATORY first action)
+
+```bash
+peaks skill presence:set peaks-solo-test --project <repo> --mode <mode> --gate startup
+peaks project memories --project <repo> --json  # load durable memory
+```
+
+## Step 1: Detect the project's test command
+
+The Peaks-Cli project standard is `pnpm vitest run` (per `vitest.config.ts` + `package.json` scripts). For other project types, check the package.json scripts first. If the user explicitly named a different command (e.g. "跑 `pnpm test` not vitest"), use that.
+
+```bash
+# Default for peaks-cli itself + most TS projects with vitest
+pnpm vitest run
+```
+
+For non-vitest projects (jest, mocha, pytest, etc.), the wrapper respects the project's existing test command. If the user says "run jest" or "run pytest", use that. Do NOT silently default to vitest.
+
+## Step 2: Run the test suite
+
+```bash
+# Run with a reasonable timeout (5 min default; override for slow suites)
+timeout 300 pnpm vitest run 2>&1 | tail -100
+```
+
+Capture both stdout and stderr. If the exit code is 0, tests passed. If non-zero, tests failed or the command errored out.
+
+## Step 3: Summarize the result
+
+Render a compact summary:
+
+- **Test files**: `X passed, Y failed, Z skipped` (from the `Test Files  X passed (Y)` line)
+- **Tests**: `A passed, B failed, C skipped` (from the `Tests  A passed | B skipped (C)` line)
+- **Wall-clock**: the `Duration` line
+- **Failures (if any)**: the first 5-10 failing test names + their failure messages, in priority order (the `FAIL` lines in the test output)
+
+Then ask the user what they want to do next via `AskUserQuestion`:
+
+| Option | What it does |
+|---|---|
+| Show the full failure list | Print all failing test names + messages (not just the first 5-10) |
+| Open a slice to fix the failures | Hand off to `peaks-solo` with the failing tests as the slice's "acceptance criteria" |
+| Just summarize and exit | No further action; the user will decide later |
+
+## Step 4: Hand off (if user picked option 2)
+
+Re-assert `peaks-solo` presence so the status header reads correctly for the rest of the run:
+
+```bash
+peaks skill presence:set peaks-solo --project <repo> --mode <mode> --gate qa-validation
+```
+
+Then yield control. The user's next message will land in `peaks-solo` (in QA validation phase, since the failing tests are the validation surface).
+
+## Hard rules (do NOT skip)
+
+- **Never silently fix test failures.** The user must choose what to do via `AskUserQuestion`. Silently "auto-fix"ing a failing test would mask the failure.
+- **Never modify source code in this skill.** This is a wrapper. The actual fix (if the user wants one) is `peaks-solo`'s job.
+- **Never add a new `peaks <cmd>`.** Use only existing primitives: `peaks skill presence:set`, `peaks project memories`, `peaks workspace init` (for the handoff), `peaks request transition` (if going to QA-validation). The actual test command is the project's existing test runner, not a `peaks <cmd>`.
+- **Never trust the test runner's exit code as the only signal.** Some failures print partial success (e.g. 100 passed + 1 failed); the wrapper must show the failures, not just say "exit 0".
+
+## Anti-patterns (do NOT do)
+
+- Do NOT run `peaks workspace init` on the real session. The wrapper is read-only on the workspace; it only reads the test results, not the workflow state.
+- Do NOT write to `.peaks/<sid>/`. This skill is read-only on the workspace.
+- Do NOT auto-fail the workflow if the tests fail. The user gets a summary + 3 options; the workflow state is unchanged.
+- Do NOT run `pnpm vitest run --watch` or any interactive mode. The wrapper captures the output as a one-shot run; interactive mode would block the orchestrator.
+
+## Cross-references
+
+- The "drives a CLI on the user's behalf" pattern (mirror of `peaks-sop`) is the closest existing precedent.
+- `peaks-solo-resume` (sibling wrapper, P2.1) is the workflow-state introspection variant; `peaks-solo-test` is the test-execution variant.
+- The "harness a project-native test runner" pattern is intentionally minimal — the wrapper should NOT add a new CLI for running tests (would violate the dev-preference.md "default-no on new CLI" rule + the user's explicit ask for "skill-first, CLI-auxiliary").

package/skills/peaks-txt/SKILL.md

@@ -107,17 +107,19 @@ Each entry should include:
 
 ## Project memory guidance
 
-When a skill artifact contains reusable project facts, decisions, rules, or constraints, mark only the stable extract with:
+When a skill artifact contains reusable project facts, decisions, rules, constraints, **or LLM-discovered runtime lessons**, mark only the stable extract with:
 
 ```markdown
 <!-- peaks-memory:start -->
 title: Short project memory title
-kind: project
+kind: project | decision | convention | rule | reference | module | lesson
 ---
 Stable memory body.
 <!-- peaks-memory:end -->
 ```
 
+The `lesson` kind is specifically for **runtime observations the LLM made during work** (e.g. "this project's antv6 Drawer uses `size` not `width`"; "this codebase imports test helpers from `src/test-utils/` not `__mocks__/`"). Lessons are loaded by `peaks project memories` as `HOT` so they appear in every future RD preflight.
+
 The primary write target is the target project's `.peaks/memory`. Use `peaks memory extract --project <path> --artifact <artifact> --apply` to write durable project memories; omit `--apply` to preview without writing.
 
 ## Matt Pocock skills integration
@@ -191,12 +193,13 @@ peaks understand show --project <repo> --json
 peaks capabilities --json
 
 # 5. Write the handoff capsule (see template above), then embed memory markers
-#    For each stable project fact, decision, rule, or convention discovered this session,
-#    append a <!-- peaks-memory:start --> block inside the capsule body:
+#    For each stable project fact, decision, rule, convention, or LLM-discovered
+#    runtime LESSON discovered this session, append a <!-- peaks-memory:start -->
+#    block inside the capsule body:
 #
 #    <!-- peaks-memory:start -->
 #    title: Short project memory title
-#    kind: project | decision | convention | rule | reference | module
+#    kind: project | decision | convention | rule | reference | module | lesson
 #    ---
 #    Stable memory body. Concrete facts only — no secrets, no transient state.
 #    <!-- peaks-memory:end -->