peaks-cli 1.4.2 → 2.0.0

package/skills/peaks-rd/references/rd-fanout-contracts.md

@@ -0,0 +1,70 @@
+# peaks-rd 4-way parallel fan-out (slice 004)
+
+The Parallel review fan-out is the canonical RD-side review pattern: at the
+end of implementation, RD fires 4 sub-agents in parallel via
+`peaks sub-agent dispatch <role>` instead of running them sequentially.
+
+## The 4 sub-agents
+
+- **Sub-agent 1 — code-reviewer** runs `code-review` against the diff and
+  writes `rd/code-review.md`.
+- **Sub-agent 2 — security-reviewer** runs `security-review` against the
+  changed surface and writes `rd/security-review.md`.
+- **Sub-agent 3 — perf-baseline-reviewer** measures the perf surface
+  (slice 025) and writes `rd/perf-baseline.md`. Skipped when the slice
+  has no perf surface (e.g. config / docs / chore) or when the bugfix
+  is not perf-shaped.
+- **Sub-agent 4 — qa-test-cases-writer** drafts the QA test plan and
+  writes `qa/test-cases/<rid>.md`. The test plan is the deliverable —
+  these test cases do NOT need to be executed by this sub-agent (the
+  QA reviewer executes them in Gate D). Do NOT write to `tests/`; the
+  writer's only write target is `qa/test-cases/<rid>.md`.
+
+## Hard prohibitions on all 4 sub-agents (single block)
+
+- Sub-agents are spawned via `Skill(skill="...")` and run in their own
+  conversation context. They MUST NOT mutate parent settings
+  (`peaks skill presence:set`, hooks install, `.claude/settings.json`).
+- Sub-agents MUST NOT call `peaks workflow verify-pipeline` — that is
+  Solo's responsibility.
+- Sub-agents MUST NOT modify the request artifact body — they only
+  write their respective review artifact.
+- Sub-agents MUST NOT install or persist external material (no
+  `npm install` of unapproved packages, no Playwright MCP install).
+- Sub-agents return a compact JSON envelope
+  (`{ ok, artifact, blockers, notes }`) to the parent RD loop; the
+  parent aggregates into the final qa-handoff.
+
+## Aggregation
+
+The parent RD loop receives the 4 envelopes, runs `peaks request lint`
+on the produced artifacts, and only then attempts
+`peaks request transition --state qa-handoff`. The aggregation step
+runs 4 ls checks: Gate B3 (code-review file), Gate B4 (security-review
+file), Gate B9 (perf-baseline file, when the slice has a perf
+surface), and the `qa-test-cases` pre-draft (the 4th sub-agent's
+deliverable). A failure in any of the 4 sub-agents → blocked, no
+auto-downgrade.
+
+## Degradation
+
+When the `qa-test-cases-writer` sub-agent fails, the parent RD loop
+records the failure as `qa-test-cases-subagent-degraded-to-inline-qa-draft`
+in the request artifact and proceeds; the QA main loop falls back to
+drafting the test plan inline at Gate D. The other 3 sub-agents
+(code-reviewer, security-reviewer, perf-baseline-reviewer) are NOT
+degradeable — their failure blocks qa-handoff.
+
+## Gate C evidence (RD-side, type-specific)
+
+| Request type | Required RD evidence (under `.peaks/<id>/`) |
+|---|---|
+| feature / refactor | `rd/tech-doc.md` + `rd/code-review.md` + `rd/security-review.md` + `rd/perf-baseline.md` + `qa/test-cases/<rid>.md` |
+| bugfix | `rd/bug-analysis.md` + `rd/code-review.md` + `rd/security-review.md` + `qa/test-cases/<rid>.md` (rd/perf-baseline.md only when perf-shaped) |
+| config | `rd/security-review.md` |
+| docs / chore | (no extra evidence required) |
+
+Always required (in addition to the type-specific row):
+`ls .peaks/<id>/rd/requests/<rid>.md`. Missing any required file →
+DO NOT attempt the qa-handoff transition; CLI will reject with
+`PREREQUISITES_MISSING`.

package/skills/peaks-rd/references/rd-runbook.md

@@ -1,4 +1,4 @@
-# Default runbook (RD)
+## Default runbook (RD)
 
 > Body of `## Default runbook` + numbered runbook steps #0–#8. The default sequence the RD skill should execute for a code-touching request. Skip steps that do not apply to the request type; do not skip the artifact, coverage gate, or red-line scope steps.
 

package/skills/peaks-solo/SKILL.md

@@ -72,6 +72,12 @@ After Step 0 anchored the workspace, run the resume-detection probe (one `find`
 
 → see `references/resume-detection.md` for the full detection algorithm + classification table.
 
+### Peaks-Cli Step 0.55: 1.x → 2.0 detection (BLOCKING on first invocation per session, when the project is not on a 2.0 layout)
+
+Per the "one-key completion" tenet (2026-06-11), peaks-cli 2.0 should detect a 1.x consumer project and prompt the user to upgrade. After Step 0.7 returns "fresh" (no in-flight slice), run the 1.x detection probe: `peaks upgrade --detect-1x --project <root> --json`. If the result is `isOneX: true`, surface an `AskUserQuestion` with the upgrade prompt. Persist the decision to `.peaks/preferences.json` (key: `autoUpgradePrompt` with values `opt-in` / `skip-this-session` / `skip-forever`) so subsequent runs in the same project don't re-ask.
+
+→ see `references/step-0-55-1x-detection.md` for the full detection algorithm + AskUserQuestion options + persistence contract.
+
 ### Peaks-Cli Step 1: Mode selection
 
 When the user did not name a profile (`full-auto` / `assisted` / `swarm` / `strict`), use `AskUserQuestion` with `Full auto (Recommended)` as the first option. Map the choice to `--mode` value.
@@ -191,15 +197,15 @@ After final validation, refresh project-local standards via `peaks standards ini
 
 ## Peaks-Cli External references and lifecycle
 
-Inventory of 3rd-party integrations (codegraph, mattpocock/skills, shadcn/ui, MCPs, Context7). Three-stage pattern: capability discovery via `peaks capabilities` → references only → Peaks-Cli CLI for side effects.
+Inventory of 3rd-party integrations (codegraph, mattpocock/skills, shadcn/ui, MCPs, Context7). Three-stage pattern: capability discovery via `peaks capabilities` → references only → Peaks-Cli CLI for side effects. Peaks-Cli artifacts and Peaks-Cli acceptance criteria remain authoritative; do not execute upstream installer scripts; MCP servers (Playwright MCP, Chrome DevTools MCP, Figma Context MCP) are not managed by peaks-cli — the LLM checks its own tool list for `mcp__<server>__*` entries; if absent, the user installs via the IDE-native install command (e.g. `claude mcp add playwright -- npx @playwright/mcp@latest` for Claude Code).
 
-→ see `references/external-references.md` for the full inventory + lifecycle rules.
+→ see `references/external-references.md` for the full inventory + lifecycle rules, and `references/external-skill-invocation.md` for the three-stage (Discovery → Reference → Side effect through Peaks CLI only) contract + the do-not-execute / do-not-persist / tool-list self-check rules.
 
 ## Codegraph orchestration context
 
-Solo treats `peaks codegraph affected --project <path> <changed-files...> --json` as optional project-analysis enhancement. Output is untrusted supporting evidence — never treat as approval for scope, design, or QA verdict.
+Solo treats `peaks codegraph affected --project <path> <changed-files...> --json` as optional project-analysis enhancement. Output is untrusted supporting evidence — never treat as approval for scope, design, or QA verdict. Solo must not treat codegraph output as approval; never mutate agent settings, Claude settings, or hooks from codegraph; do not commit `.codegraph/` artifacts or persist generated `.codegraph/` databases into git. Solo coordinates codegraph context across the role handoff between RD (writes `.peaks/<session-id>/rd/codegraph-context.md`) and QA / TXT (consume the same envelope).
 
-→ see `references/codegraph-orchestration.md` for the full contract.
+→ see `references/codegraph-orchestration.md` for the full contract (including the agent-settings / settings-mutation prohibition, the no-`.codegraph/` commit rule, and the role-handoff envelope).
 
 ## Sub-agent context governance (G7 + G7.7 + G8 + G9 — slice #010)
 

package/skills/peaks-solo/references/step-0-55-1x-detection.md

@@ -0,0 +1,82 @@
+# Step 0.55 — 1.x → 2.0 detection reference
+
+> Body of `### Peaks-Cli Step 0.55`. Slice: 2026-06-12-solo-step-0-55-1x-detection.
+
+## Why this step exists
+
+The peaks-cli 1.x → 2.0 closeout ships:
+
+1. A postinstall that auto-detects 1.x state and dispatches the upgrade (slice 1, commit `b6e34e6`).
+2. A standards-migrate path that thins `.claude/rules/**/*.md` and scaffolds `.peaks/standards/` (slice 2, commit `33dd392`).
+3. **THIS STEP** — a peaks-solo startup sequence probe that detects 1.x state when the user invokes `/peaks-solo` directly in a 1.x consumer project, and prompts the user to upgrade.
+
+The 1.x user experience is: "I just typed /peaks-solo. Why is it not working in 2.0 mode?" Step 0.55 catches this case and surfaces an `AskUserQuestion` with a one-click upgrade.
+
+## Detection algorithm
+
+```bash
+# 1. Read-only probe via the umbrella CLI
+peaks upgrade --detect-1x --project <root> --json
+```
+
+The CLI returns:
+```json
+{
+  "ok": true,
+  "command": "upgrade.detect-1x",
+  "data": {
+    "isOneX": true,
+    "signals": [
+      "<path> has schema_version 1.0.0, expected '2.0.0'",
+      "..."
+    ],
+    "projectRoot": "/path/to/project",
+    "configPath": null
+  },
+  "warnings": [],
+  "nextActions": [
+    "Detected 1.x state. peaks-solo Step 0.55 should present an AskUserQuestion to invoke `peaks upgrade --to 2.0 --auto --project /path/to/project`."
+  ]
+}
+```
+
+The detection logic mirrors `scripts/install-skills.mjs:detect1xProjectState` (canonical implementation) — it walks up to find `.peaks/_runtime/`, then sniffs:
+
+1. `~/.peaks/config.json` for `version: 1.x`
+2. `<projectRoot>/.claude/rules/common/dev-preference.md` for "peaks progress"
+3. `<projectRoot>/.peaks/preferences.json` for missing or non-`2.0.0` `schema_version`
+
+The TS mirror in `src/services/upgrade/1x-detector-service.ts` is the canonical entrypoint for the skill; the postinstall `.mjs` version is the canonical entrypoint for the npm-install flow. The two implementations MUST stay in parity (a parity test is in the slice's test suite).
+
+## AskUserQuestion (only when `isOneX: true`)
+
+| Option | What it does |
+|---|---|
+| Run `peaks upgrade --to 2.0 --auto --project <root>` (Recommended) | Invokes the umbrella. The user sees the 6 sub-step results in the terminal. After the upgrade, re-run peaks-solo with the standing 2.0 layout. Persist `autoUpgradePrompt: opt-in` to `.peaks/preferences.json`. |
+| Skip for this session | Continue with the standing 1.x layout. Persist `autoUpgradePrompt: skip-this-session` to `.peaks/preferences.json`. The next time the user invokes peaks-solo in this project, the question re-asks. |
+| Never ask again for this project | Persist `autoUpgradePrompt: skip-forever` to `.peaks/preferences.json`. Step 0.55 becomes a no-op for this project from now on. The user can re-enable later by removing the `autoUpgradePrompt` key from preferences.json. |
+
+## Persistence contract
+
+The decision is persisted via `peaks preferences set --project <root> --key autoUpgradePrompt --value <opt-in|skip-this-session|skip-forever> --apply`. Subsequent Step 0.55 invocations read the value first:
+
+- If `opt-in` (and Step 0.55 is the first invocation in the session), the user has already opted in; auto-run the umbrella without re-asking.
+- If `skip-this-session`, the user already said no this session; skip without re-asking (but re-ask next session).
+- If `skip-forever`, the user said no permanently; skip without re-asking.
+- If the key is absent, present the AskUserQuestion.
+
+## What is NOT in this step
+
+- The auto-upgrade execution itself: the umbrella is invoked via the AskUserQuestion's recommended option. The umbrella's behavior (6 sub-commands + write-upgrade-record) is documented in the umbrella's own help text.
+- The postinstall auto-dispatch: that's `scripts/install-skills.mjs:autoUpgrade1xProjectIfPresent`, which fires fire-and-forget on `npm i -g peaks-cli@2.0`. Step 0.55 is the user-invoked path.
+- Re-authoring the 1.x detector heuristics: the implementation is a 1:1 mirror of the canonical `.mjs` version. Drift is prevented by the parity test.
+
+## How this integrates with the rest of the workflow
+
+- Step 0.5 (OpenSpec opt-in) — runs first if `openspec/` is missing.
+- Step 0 (anchor) — runs always.
+- Step 0.7 (resume detection) — runs after Step 0.
+- **Step 0.55 (1.x detection) — runs after Step 0.7, only when the project is not on a 2.0 layout.**
+- Step 1 (mode selection) — runs after Step 0.55.
+
+The 1.x detection is intentionally placed AFTER Step 0.7 because the user might already have a 1.x-converted in-flight slice; the resume flow takes precedence over the upgrade prompt.

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

@@ -102,6 +102,15 @@ ls .peaks/<id>/ui/design-draft.md 2>&1
 
 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.
 
+| Request type | Required RD evidence (under `.peaks/<id>/`) |
+|---|---|
+| `feature` / `refactor` | `rd/tech-doc.md` + `rd/code-review.md` + `rd/security-review.md` + `rd/perf-baseline.md` + `qa/test-cases/<rid>.md` (qa/test-cases pre-drafted by the 4th sub-agent in peaks-rd's parallel fan-out — slice 004) |
+| `bugfix` | `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` | `rd/security-review.md` |
+| `docs` / `chore` | (no extra evidence required) |
+
+Always required (in addition to the type-specific row): `ls .peaks/<id>/rd/requests/<rid>.md`. Missing any required file → DO NOT attempt the qa-handoff transition; CLI will reject with PREREQUISITES_MISSING.
+
 ```bash
 # Always required
 ls .peaks/<id>/rd/requests/<rid>.md