peaks-cli 1.2.3 → 1.2.5

package/skills/peaks-sop/references/sop-authoring.md

@@ -8,7 +8,7 @@ interview → generate → debug loop, and security notes. The skill drives the
 
 SOP **definitions** live in one of two layers:
 - **Global** `~/.peaks/sops/<sop-id>/sop.json` (+ `SKILL.md`) — personal, reusable across every project. `init` / `lint` / `register` default here.
-- **Project** `<project>/.peaks/sops/<sop-id>/sop.json` — committed into the repo and team-shared. Pass `--project <repo>` to `init` / `lint` / `register` to use this layer. The project layer **wins** over global for the same id; execution reads (`check`/`advance`/enforce) and `sop registry --project` see the merged view.
+- **Project** `<project>/.peaks/sops/<sop-id>/sop.json` — committed into the repo and team-shared. Pass `--project <repo>` to `init` / `lint` / `register` to use this layer. The project layer **wins** over global for the same id; execution reads (`check` / `advance` / `gate enforce` / `registry`) default `--project` to the current directory, so they see the merged view without an explicit flag.
 
 A SOP's **run-state** is always per-project: `<project>/.peaks/sop-state/<sop-id>/state.json` (git-ignored — runtime, not shared). `check` / `advance` take `--project` (default: current directory) — that says which project the gate paths resolve against, whose progress advances, and which definition layer wins.
 

package/skills/peaks-txt/SKILL.md

@@ -207,12 +207,28 @@ peaks capabilities --json
 
 # 6. Memory extraction — --apply is REQUIRED to write .peaks/memory
 #    (without --apply the command only previews; the directory will NOT be created)
+#    You MUST scan the handoff capsule for embedded memory blocks FIRST. If none
+#    are present, the step is a no-op (the command succeeds with extractedCount=0
+#    and writes nothing). If blocks are present, --apply writes them and the
+#    index is regenerated.
+grep -c "peaks-memory:start" .peaks/<id>/txt/handoff.md || true   # skill-side scan; do NOT add a new CLI
 peaks memory extract --project <repo> --artifact .peaks/<id>/txt/handoff.md --apply --json
 peaks skill presence:clear --project <repo>                      # handoff capsule complete, remove presence indicator
 ```
 
 `peaks memory extract --apply` writes to `.peaks/memory` (without `--apply` it only previews). The handoff capsule `.peaks/<id>/txt/handoff.md` is the primary artifact for extraction — embed `<!-- peaks-memory:start -->` blocks in it for stable project facts before running extract.
 
+### Memory block embedding rule (BLOCKING — read before writing the handoff)
+
+Every handoff capsule you emit **MUST** include the scan for stable facts. The minimum acceptable is:
+
+- Run `grep -c 'peaks-memory:start' .peaks/<id>/txt/handoff.md` after writing the capsule body.
+- If the count is 0 AND this session surfaced a stable project fact (an architectural decision, a stack constraint, a naming convention, a refactor approved by the user, an API pattern, a hard rule from RD/QA review), you MUST go back and embed at least one `<!-- peaks-memory:start -->` block before declaring TXT complete. Skipping the block is a workflow violation.
+- If the count is 0 AND no stable fact was surfaced (pure analysis, no code touched, all transient), it is acceptable to skip embedding — but you MUST still run `peaks memory extract --apply` so the artefact state stays consistent (the command will be a no-op write, that's fine).
+- If the count is ≥ 1, the `--apply` extract will write one markdown per block to `.peaks/memory/` and regenerate `index.json`. The user sees the durable persistence; that is the entire point of this step.
+
+This rule is the skill-side half of the **Skill is primary, CLI is auxiliary** contract: the LLM is responsible for embedding blocks (skill prompt, no CLI can decide what is stable), and the CLI is responsible for atomic persistence (`peaks memory extract --apply`, single shot, structured JSON envelope).
+
 ### Transition verification gates (MANDATORY — run the command, see the output)
 
 You cannot declare TXT complete from memory. Each gate below is a `ls` command you **MUST run** and whose output you **MUST see** before proceeding.

package/skills/peaks-ui/SKILL.md

@@ -7,9 +7,68 @@ description: UI and experience skill for Peaks. Use when a workflow touches UI/U
 
 Peaks-Cli UI handles experience, interaction, visual direction, and UI-specific refactor artifacts.
 
-## Skill presence (MANDATORY first action)
+## Hard contracts for browser inspection (BLOCKING — read before any browser_take_screenshot / login flow)
 
-Before any analysis or tool call, immediately run:
+UI's headed-browser work (visual inspection, regression seed capture, Figma / live-page cross-check) follows the same two contracts as `peaks-qa` and `peaks-rd`. The contracts are defined in full in `peaks-qa` ("Hard contracts for browser validation"); UI inherits them.
+
+### Contract 1 — Inspection screenshots must land under .peaks/<sid>/qa/screenshots/
+
+Every `mcp__playwright__browser_take_screenshot` call **MUST** pass `filename` inside `.peaks/<session-id>/qa/screenshots/`, named after the inspection target (e.g. `home-after-cta.png`, `empty-state-v2.png`). Do not let Playwright fall back to the project root. After every batch, run:
+
+```bash
+ls .peaks/<sid>/qa/screenshots/*.png 2>&1
+find . -maxdepth 1 -name '*.png' 2>&1
+```
+
+`find` must be empty; any project-root `.png` is a leak and must be moved into the screenshots directory before completing this skill.
+
+### Contract 2 — Login / CAPTCHA / SSO / MFA wall is a hard block, not a skip
+
+UI's headed-browser inspection hits the same auth walls. The flow is identical to QA: `AskUserQuestion` with three options (logged in / skip / cancel); no silent downgrade to static screenshots, no inferring login from DOM state. The full hard-block contract is defined in `peaks-qa`; UI inherits it.
+
+## Sub-agent dispatch (when launched by peaks-solo swarm)
+
+When this skill is launched as a sub-agent via `Task(subagent_type="general-purpose", ...)` from `peaks-solo`, the following sections of THIS skill are **suspended** for the sub-agent run:
+
+- **Skill presence (MANDATORY first action)** — do NOT call `peaks skill presence:set peaks-ui`. The sub-agent must not overwrite `.peaks/.active-skill.json`; the main Solo loop owns that file. If you need to mark your own state, write a marker file at `.peaks/<session-id>/system/sub-agent-ui.json` and only that.
+- **Workspace initialization** — Solo has already run `peaks workspace init` before fan-out. Do not re-run it.
+- **Mode selection** — Solo has already chosen the mode.
+- **Statusline install** — already done by Solo at session startup.
+
+What the sub-agent **MUST** still do:
+
+0. **Do NOT call `peaks request init`** — Solo has already initialised the request artefact slot in the main loop before fan-out. The sub-agent reads it via `peaks request show <rid> --role ui --project <repo> --json` if it needs to.
+2. `peaks request show <rid> --role prd --project <repo> --json` to read the PRD scope.
+3. Read project-scan (`rd/project-scan.md`) for component library, CSS framework, design-system context.
+4. Run the prototype fidelity check (Figma / PRD visuals / headed browser).
+5. Write the two artefacts: `.peaks/<session-id>/ui/design-draft.md` and `.peaks/<session-id>/ui/requests/<rid>.md`.
+6. Return only a compact JSON envelope:
+
+```json
+{
+  "role": "ui",
+  "rid": "<rid>",
+  "status": "ok" | "blocked" | "skipped",
+  "artefacts": [".peaks/<sid>/ui/design-draft.md", ".peaks/<sid>/ui/requests/<rid>.md"],
+  "warnings": [],
+  "blockedReason": null
+}
+```
+
+**Hard prohibitions** (sub-agent context):
+
+- Do NOT call `Skill(skill="...")`.
+- Do NOT call `peaks skill presence:set` — Solo owns the active-skill file.
+- Do NOT modify application code. UI is design-direction only; the actual frontend code is written in the RD implementation phase.
+- Do NOT install MCP servers. If `peaks mcp list` shows playwright-mcp missing and the headed browser is required, return `{"status":"blocked","blockedReason":"playwright-mcp-unavailable"}` and let Solo escalate to the user.
+- Do NOT commit, push, install hooks, or apply settings.json mutations.
+- Do NOT ask the user interactive questions. If you need clarification, return `{"status":"blocked","blockedReason":"<text>"}`.
+
+If the request does not affect user-visible behavior (no frontend keyword hit, `frontendOnly=false`), the swarm plan should not include UI at all — Solo will not launch this sub-agent. But if it does launch you and you determine the work is non-visual, return `{"status":"skipped","reason":"non-frontend-request"}` so Solo can record the misfire.
+
+## Skill presence (MANDATORY first action — main-loop context only)
+
+When this skill is running in the main Claude session (not as a sub-agent), before any analysis or tool call, immediately run:
 
 ```bash
 peaks skill presence:set peaks-ui --project <repo> --mode <mode> --gate startup