peaks-cli 1.3.9 → 1.4.0

package/skills/peaks-qa/references/qa-perf-test-plan.md

@@ -0,0 +1,67 @@
+# Performance test plan (project-level, slice 025)
+
+> Body of `## Performance test plan`. Slice 025 introduces a
+> project-level performance baseline that is **stable across slices
+> within a session** and is refreshed only when a slice's diff matches
+> the trigger table. The per-slice
+> `qa/performance-findings-<rid>.md` references this baseline by path +
+> hash.
+
+## Location
+
+`.peaks/_runtime/<sessionId>/qa/perf-baseline.md`. The CLI is
+`peaks workflow plan read perf --project <repo> --json` /
+`peaks workflow plan refresh perf --project <repo> --apply` /
+`peaks workflow plan detect-trigger --project <repo> --rid <rid> --json`.
+
+## Generation workflow
+
+1. `peaks workflow plan read perf --project <repo> --json` — return the
+   existing baseline envelope. When missing, proceed to step 2.
+2. `peaks workflow plan detect-trigger --rid <rid> --project <repo> --json`
+   — return `{ triggered, reason }`. The perf baseline is refreshed on
+   the same triggers as the security plan: new dep, new route/hook
+   registration, or `--refresh`.
+3. If `triggered: true`, run
+   `peaks workflow plan refresh perf --project <repo> --apply --json`.
+4. The slice's `qa/performance-findings-<rid>.md` opens with the
+   `## Plan reference` block referencing the baseline hash + path.
+5. The slice result records the diff vs the baseline threshold
+   (lighthouse / k6 / autocannon output) — see peaks-rd's
+   `mandatory-perf-baseline.md` for the RD-side measurement workflow.
+
+## Content schema (deterministic — body is normalized before hashing)
+
+- `## CLI Command Inventory` — auto-enumerated from
+  `src/cli/commands/*-commands.ts`. Sorted alphabetically.
+- `## Routes / Hooks` — fixed narrative. CLI is a CLI tool, no HTTP.
+- `## Baseline Measurements` — placeholder table; the RD fills the
+  actual numbers (CLI does not call measurement tools).
+- `## Thresholds` — placeholder; RD fills per-route thresholds.
+
+## Refresh trigger table (shared with security plan)
+
+| Signal | Reason string | Re-generates the baseline? |
+|---|---|---|
+| New dep in `dependencies` / `optionalDependencies` | `new-dependency` | yes |
+| New file under `src/services/{auth,security,secrets,payments,filesystem}/` | `auth-surface-added` | yes |
+| New `*auth*.ts` file anywhere in `src/` | `auth-surface-added` | yes |
+| New route / command registration (`router.ts`, `commands/*-commands.ts`) | `hot-path-added` | yes |
+| `--refresh` on the slice workflow | `manual-override` | yes |
+| devDependencies change only | (none) | no — locked Q1 default |
+| Pure text edits to `rd/*` or `qa/test-cases/*` | (none) | no |
+
+## Back-compat (1 minor release)
+
+The pre-slice-025 non-suffixed `qa/performance-findings.md` is still
+accepted by `peaks workflow verify-pipeline` Gate C during the
+1-minor-release window. The path resolver
+(`src/services/workflow/artifact-paths.ts`) handles the fallback and
+emits a `legacy-redirect` warning.
+
+## CLI surface recap
+
+| Command | Returns | JSON shape |
+|---|---|---|
+| `peaks workflow plan read perf --project <repo>` | `exists`, `path`, `hash`, `refreshedAt`, `source` | `{ ok, command, data: { ... } }` |
+| `peaks workflow plan refresh perf --project <repo> [--apply]` | `writtenFiles`, `wouldWrite`, `hash`, `refreshedAt`, `dryRun` | `{ ok, command, data: { ... } }` |

package/skills/peaks-qa/references/qa-security-test-plan.md

@@ -0,0 +1,73 @@
+# Security test plan (project-level, slice 025)
+
+> Body of `## Security test plan`. Slice 025 introduces a project-level
+> security test plan that is **stable across slices within a session**
+> and is refreshed only when a slice's diff matches the trigger table.
+> The per-slice `qa/security-findings-<rid>.md` references this plan by
+> path + hash; the plan itself is NOT regenerated per slice.
+
+## Location
+
+`.peaks/_runtime/<sessionId>/qa/security-test-plan.md`. The CLI is
+`peaks workflow plan read security --project <repo> --json` /
+`peaks workflow plan refresh security --project <repo> --apply` /
+`peaks workflow plan detect-trigger --project <repo> --rid <rid> --json`.
+
+## Generation workflow
+
+1. `peaks workflow plan read security --project <repo> --json` — return
+   the existing plan envelope (exists, path, hash, refreshedAt). When
+   the plan does not exist, the slice workflow proceeds to step 2.
+2. `peaks workflow plan detect-trigger --rid <rid> --project <repo> --json`
+   — return `{ triggered, reason }` based on the trigger table below.
+3. If `triggered: true`, run
+   `peaks workflow plan refresh security --project <repo> --apply --json`
+   — atomic write; the response carries the new hash + refreshedAt.
+4. The slice's `qa/security-findings-<rid>.md` opens with the
+   `## Plan reference` block: `plan-hash: <hash>`, `plan-path: <path>`,
+   `unchanged-since: <prev-rid> | new`.
+5. Re-read with `peaks workflow plan read security` to confirm the
+   post-write envelope matches the value embedded in the slice result.
+
+## Content schema (deterministic — body is normalized before hashing)
+
+- `## Threat Model` — fixed narrative. Auth boundary, secret storage,
+  external API surface, file system writes.
+- `## Sensitive Service Files` — auto-enumerated from
+  `src/services/{auth,security,secrets,payments,filesystem}/`. Empty
+  buckets render as `- (none)`. Files sorted alphabetically.
+- `## Auth Surface (*auth*.ts files repo-wide)` — auto-enumerated.
+- `## Runtime Dependencies` — split into `dependencies` and
+  `optionalDependencies` (per locked decision 1, `devDependencies` are
+  **excluded** from the trigger scan and from the plan body).
+- `## Test Matrix` — fixed narrative. Points the slice workflow at
+  peaks-qa's per-slice diff scan.
+
+## Refresh trigger table (locked decision 1)
+
+| Signal | Reason string | Re-generates the plan? |
+|---|---|---|
+| New dep in `dependencies` / `optionalDependencies` | `new-dependency` | yes |
+| New file under `src/services/{auth,security,secrets,payments,filesystem}/` | `auth-surface-added` | yes |
+| New `*auth*.ts` file anywhere in `src/` | `auth-surface-added` | yes |
+| New route / command registration (`router.ts`, `commands/*-commands.ts`) | `hot-path-added` | yes |
+| `--refresh` on the slice workflow | `manual-override` | yes |
+| devDependencies change only | (none) | no — locked Q1 default |
+| Pure text edits to `rd/*` or `qa/test-cases/*` | (none) | no |
+
+## Back-compat (1 minor release)
+
+The pre-slice-025 non-suffixed `qa/security-findings.md` is still
+accepted by `peaks workflow verify-pipeline` Gate C during the
+1-minor-release window. The path resolver
+(`src/services/workflow/artifact-paths.ts`) handles the fallback and
+emits a `legacy-redirect` warning in the gate's violation list. The
+form is rejected after the next minor bump.
+
+## CLI surface recap
+
+| Command | Returns | JSON shape |
+|---|---|---|
+| `peaks workflow plan read security --project <repo>` | `exists`, `path`, `hash`, `refreshedAt`, `source` | `{ ok, command, data: { ... } }` |
+| `peaks workflow plan refresh security --project <repo> [--apply]` | `writtenFiles`, `wouldWrite`, `hash`, `refreshedAt`, `dryRun` | `{ ok, command, data: { ... } }` |
+| `peaks workflow plan detect-trigger --project <repo> --rid <rid> [--refresh]` | `triggered`, `reason` | `{ ok, command, data: { ... } }` |

package/skills/peaks-qa/references/qa-transition-gates.md

@@ -6,12 +6,12 @@
 
 | Type | qa:running requires | qa:verdict-issued also requires |
 |---|---|---|
-| feature / refactor | `qa/test-cases/<rid>.md` | `qa/test-reports/<rid>.md` + `qa/security-findings.md` + `qa/performance-findings.md` |
-| bugfix | `qa/test-cases/<rid>.md` (MUST include the regression test) | `qa/test-reports/<rid>.md` + `qa/security-findings.md` (perf optional unless the bug is performance-related) |
-| config | (none) | `qa/security-findings.md` only |
+| feature / refactor | `qa/test-cases/<rid>.md` | `qa/test-reports/<rid>.md` + `qa/security-findings-<rid>.md` + `qa/performance-findings-<rid>.md` |
+| bugfix | `qa/test-cases/<rid>.md` (MUST include the regression test) | `qa/test-reports/<rid>.md` + `qa/security-findings-<rid>.md` (perf optional unless the bug is performance-related) |
+| config | (none) | `qa/security-findings-<rid>.md` only |
 | docs / chore | (none) | (none) |
 
-For feature / refactor, `security-findings.md` and `performance-findings.md` MUST exist — record `"no findings"` inside if truly clean rather than skipping the file.
+For feature / refactor, the `<rid>`-suffixed security-findings and performance-findings MUST exist — record `"no findings"` inside if truly clean rather than skipping the file. The pre-slice-025 non-suffixed `security-findings.md` / `performance-findings.md` paths are accepted as a 1-minor-release back-compat fallback; the resolver in `src/services/workflow/artifact-paths.ts` picks the suffixed form when both exist, and Gate C logs a `legacy-redirect` warning so users know to migrate. The form is rejected after the next minor bump.
 
 **Peaks-Cli Gate A — After test-case generation:**
 ```bash
@@ -29,13 +29,15 @@ npx vitest run --changed --reporter=verbose 2>&1 | tail -30
 
 **Peaks-Cli Gate A3 — Security test executed (NOT just a checklist item):**
 ```bash
-ls .peaks/<changeId>/qa/security-findings.md 2>&1
-# Expected: .peaks/<changeId>/qa/security-findings.md
+ls .peaks/<changeId>/qa/security-findings-<rid>.md 2>&1
+# Expected: .peaks/<changeId>/qa/security-findings-<rid>.md
+# Back-compat (1 minor release): .peaks/<changeId>/qa/security-findings.md is also accepted.
 ```
 
 **Peaks-Cli Gate A4 — Performance test executed:**
 ```bash
-ls .peaks/<changeId>/qa/performance-findings.md 2>&1
+ls .peaks/<changeId>/qa/performance-findings-<rid>.md 2>&1
+# Back-compat (1 minor release): .peaks/<changeId>/qa/performance-findings.md is also accepted.
 ```
 
 **Peaks-Cli Gate B — After test-report write (MUST contain execution results):**
@@ -49,10 +51,12 @@ grep -c "pass\|fail\|blocked" .peaks/<changeId>/qa/test-reports/<rid>.md
 ```bash
 ls .peaks/<changeId>/qa/test-cases/<rid>.md \
    .peaks/<changeId>/qa/test-reports/<rid>.md \
-   .peaks/<changeId>/qa/security-findings.md \
-   .peaks/<changeId>/qa/performance-findings.md \
+   .peaks/<changeId>/qa/security-findings-<rid>.md \
+   .peaks/<changeId>/qa/performance-findings-<rid>.md \
    .peaks/<changeId>/qa/requests/<rid>.md
 # All five must exist. Missing any → QA incomplete, verdict blocked.
+# Back-compat (1 minor release): security-findings.md / performance-findings.md
+# (no <rid> suffix) are also accepted during the 1-minor-release window.
 ```
 
 **Peaks-Cli Gate E — Acceptance coverage:**

package/skills/peaks-rd/SKILL.md

@@ -98,9 +98,9 @@ Before every code or mock change, RD must write and then enforce a red-line scop
 
 ## Mandatory perf-baseline output (RD-side perf gate)
 
-**BLOCKING — Do not hand off to QA without a perf-baseline file when the slice has a user-visible performance surface.** The QA stage's Gate A4 (performance check) needs a stable reference to diff against; without an RD-side baseline, the first time Gate A4 runs it has nothing to compare against.
+**BLOCKING — Do not hand off to QA without a perf-baseline file when the slice has a user-visible performance surface.** The QA stage's Gate A4 (performance check) needs a stable reference to diff against; without an RD-side baseline, the first time Gate A4 runs it has nothing to compare against. **Slice 025**: the perf baseline is stable across slices within a session and is refreshed on trigger; use `peaks workflow plan refresh perf --apply` for refreshes.
 
-→ see `references/mandatory-perf-baseline.md` for the full "when this applies" + `peaks perf baseline --apply` workflow.
+→ see `references/mandatory-perf-baseline.md` for the full "when this applies" + `peaks perf baseline --apply` workflow + slice-025 refresh contract.
 
 ## Implementation completion gates
 

package/skills/peaks-rd/references/mandatory-perf-baseline.md

@@ -2,6 +2,8 @@
 
 > Body of `## Mandatory perf-baseline output` + numbered perf-baseline steps. **BLOCKING — Do not hand off to QA without a perf-baseline file when the slice has a user-visible performance surface.** The QA stage's Gate A4 (performance check) needs a stable reference to diff against; without an RD-side baseline, the first time Gate A4 runs it has nothing to compare against and any regression it finds is a blind-side surprise. The user-facing pain of leaving perf to QA only has historically been a 3-cycle repair loop. The RD-side baseline closes that loop.
 
+> **Slice 025 — stable across slices within a session; refreshed on trigger.** The perf baseline is a **project-level** artifact (`.peaks/_runtime/<sessionId>/qa/perf-baseline.md`) and is **stable across slices within a session**. It is regenerated only when the slice diff matches the refresh trigger table (see `peaks-qa/references/qa-perf-test-plan.md`). Slices that do not trigger a refresh reference the existing baseline by hash from the per-slice `qa/performance-findings-<rid>.md` (not by regenerating the baseline). The CLI is `peaks workflow plan read|refresh|detect-trigger perf --project <repo>`; the RD-side `peaks perf baseline --apply` workflow below still scaffolds the initial file but the canonical refresh path post-slice-025 is the new `peaks workflow plan refresh` primitive.
+
 **When this applies:**
 - feature / refactor slices that touch a route, hook, API, or any user-perceivable surface
 - bugfix slices where the bug is performance-shaped (slow render, hot loop, N+1)