peaks-cli 1.2.4 → 1.2.6

package/dist/src/services/session/session-manager.js

@@ -61,6 +61,25 @@ function writeSessionFile(projectRoot, info) {
     }
     writeFileSync(sessionFile, JSON.stringify(info, null, 2), 'utf8');
 }
+/**
+ * Bind the project's current session to the given session id by writing
+ * `.peaks/.session.json`. The single-session binding is the source of truth
+ * for `ensureSession()` and any other path that needs to discover the
+ * active session without an explicit --session-id flag.
+ *
+ * This does NOT touch the per-session `session.json` inside `.peaks/<id>/`;
+ * that file is owned by `setSessionMeta` and records session-scoped
+ * metadata (title, skill, mode, gate, etc.).
+ */
+export function setCurrentSessionBinding(projectRoot, sessionId) {
+    const info = {
+        sessionId,
+        createdAt: new Date().toISOString(),
+        projectRoot
+    };
+    writeSessionFile(projectRoot, info);
+    return info;
+}
 function getMetaFilePath(projectRoot, sessionId) {
     return join(projectRoot, '.peaks', sessionId, META_FILE);
 }

package/dist/src/services/skills/skill-presence-service.js

@@ -1,6 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { findProjectRoot } from '../config/config-safety.js';
+import { ensureMemoryBootstrap } from '../memory/project-memory-service.js';
 export const VALID_SKILL_PRESENCE_MODES = [
     'full-auto',
     'assisted',
@@ -67,6 +68,16 @@ export function setSkillPresence(skill, mode, gate, projectRootOverride) {
         mkdirSync(presenceDir, { recursive: true });
     }
     writeFileSync(presencePath, JSON.stringify(presence, null, 2), 'utf8');
+    // Skill-activation side effect: ensure `.peaks/memory/` and a full-shape
+    // empty `index.json` exist for the project. This is the user-facing fix
+    // for "stock projects never get a memory directory or index". Every peaks
+    // skill starts with `peaks skill presence:set peaks-<role>`, so doing the
+    // bootstrap here means the very first skill invocation in a fresh project
+    // (or in a stock project that pre-dates the memory layer) brings the
+    // memory store into existence. The helper is fail-open, so a failure here
+    // does not block presence from being written.
+    const projectRoot = resolveProjectRoot(projectRootOverride);
+    ensureMemoryBootstrap(projectRoot);
     return presence;
 }
 export function getSkillPresence(projectRootOverride) {

package/dist/src/services/workspace/workspace-service.d.ts

@@ -1,16 +1,31 @@
 export type WorkspaceInitOptions = {
     projectRoot: string;
     sessionId: string;
+    /**
+     * When true, the conflict check is skipped and the new session id is
+     * written to .peaks/.session.json even if the project is already bound
+     * to a different (real) session. Use only with explicit user authorization
+     * — the CLI surfaces this as `--allow-session-rebind`.
+     */
+    allowSessionRebind?: boolean;
 };
 export type WorkspaceInitReport = {
     sessionId: string;
     sessionRoot: string;
     created: string[];
     alreadyExisted: string[];
+    bound: boolean;
+    previousSessionId: string | null;
 };
 export declare class InvalidSessionIdError extends Error {
     readonly code = "INVALID_SESSION_ID";
     constructor(message: string);
 }
+export declare class ConflictingSessionError extends Error {
+    readonly existingSessionId: string;
+    readonly requestedSessionId: string;
+    readonly code = "CONFLICTING_SESSION";
+    constructor(message: string, existingSessionId: string, requestedSessionId: string);
+}
 export declare function validateSessionId(sessionId: string): void;
 export declare function initWorkspace(options: WorkspaceInitOptions): Promise<WorkspaceInitReport>;

package/dist/src/services/workspace/workspace-service.js

@@ -1,6 +1,7 @@
 import { mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { isDirectory } from '../../shared/fs.js';
+import { getSessionId, setCurrentSessionBinding } from '../session/session-manager.js';
 const SUBDIRECTORIES = [
     'prd/source',
     'prd/requests',
@@ -9,6 +10,7 @@ const SUBDIRECTORIES = [
     'qa/test-cases',
     'qa/test-reports',
     'qa/requests',
+    'qa/screenshots',
     'sc',
     'txt',
     'system'
@@ -24,6 +26,17 @@ export class InvalidSessionIdError extends Error {
         this.name = 'InvalidSessionIdError';
     }
 }
+export class ConflictingSessionError extends Error {
+    existingSessionId;
+    requestedSessionId;
+    code = 'CONFLICTING_SESSION';
+    constructor(message, existingSessionId, requestedSessionId) {
+        super(message);
+        this.existingSessionId = existingSessionId;
+        this.requestedSessionId = requestedSessionId;
+        this.name = 'ConflictingSessionError';
+    }
+}
 export function validateSessionId(sessionId) {
     // Auto-generated session IDs (YYYY-MM-DD-session-<hex>) bypass manual validation
     if (AUTO_SESSION_PATTERN.test(sessionId)) {
@@ -68,5 +81,51 @@ export async function initWorkspace(options) {
             created.push(sub);
         }
     }
-    return { sessionId: options.sessionId, sessionRoot, created, alreadyExisted };
+    // Bind this session as the project's current one.
+    //
+    // Single source of truth: `peaks workspace init` is the only CLI entry point
+    // that takes an explicit --session-id, so it owns the binding to .session.json.
+    // Without this write, downstream commands that fall through to
+    // `ensureSession()` would auto-generate a *different* id and create a second
+    // session directory — the bug that confuses the LLM in peaks-solo.
+    //
+    // Conflict rule: if .session.json already points at a different session
+    // whose directory is real (has session.json inside), the caller is starting
+    // a parallel session without closing the previous one. Refuse to bind —
+    // this is the "strict" mode the user picked. The user must finish or delete
+    // the existing session first.
+    const existingSessionId = getSessionId(options.projectRoot);
+    let previousSessionId = null;
+    let bound = false;
+    if (existingSessionId === null) {
+        // No prior binding — adopt the requested id.
+        setCurrentSessionBinding(options.projectRoot, options.sessionId);
+        bound = true;
+    }
+    else if (existingSessionId === options.sessionId) {
+        // Already bound to the same id — idempotent.
+        bound = true;
+    }
+    else {
+        // Different id already bound. The existing session is "real" if its
+        // directory is non-empty — that holds the user's data (rd/, qa/, ui/,
+        // etc.) regardless of whether the per-session metadata file is present.
+        // Refuse to rebind without explicit authorization.
+        previousSessionId = existingSessionId;
+        const existingSessionDir = join(options.projectRoot, '.peaks', existingSessionId);
+        if (await isDirectory(existingSessionDir) && !options.allowSessionRebind) {
+            const { readdirSync } = await import('node:fs');
+            const entries = readdirSync(existingSessionDir);
+            if (entries.length > 0) {
+                throw new ConflictingSessionError(`Project is already bound to session "${existingSessionId}". ` +
+                    `Cannot start session "${options.sessionId}" without closing the previous one. ` +
+                    `Either finish/abandon the prior session first, or pass --allow-session-rebind to override.`, existingSessionId, options.sessionId);
+            }
+        }
+        // Either: existing session dir is empty (true leftover, no user data),
+        // or the caller explicitly authorised a rebind. Overwrite.
+        setCurrentSessionBinding(options.projectRoot, options.sessionId);
+        bound = true;
+    }
+    return { sessionId: options.sessionId, sessionRoot, created, alreadyExisted, bound, previousSessionId };
 }

package/dist/src/shared/version.d.ts

@@ -1 +1 @@
-export declare const CLI_VERSION = "1.2.4";
+export declare const CLI_VERSION = "1.2.6";

package/dist/src/shared/version.js

@@ -1 +1 @@
-export const CLI_VERSION = "1.2.4";
+export const CLI_VERSION = "1.2.6";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-cli",
-  "version": "1.2.4",
+  "version": "1.2.6",
   "description": "Peaks CLI and short skill family for Claude Code automation.",
   "author": "SquabbyZ",
   "license": "MIT",

package/skills/peaks-prd/SKILL.md

@@ -7,6 +7,42 @@ description: Product and requirement skill for Peaks. Use when a workflow needs
 
 Peaks-Cli PRD turns user intent into verifiable product artifacts.
 
+## Hard contracts for PRD source-document screenshots (BLOCKING)
+
+When the PRD source is an authenticated web document (Feishu / Lark / Notion / Confluence / GitHub / any site that demands a login before the document body is reachable), PRD uses the Playwright MCP headed browser to render it. The two contracts are the same as in `peaks-qa` and `peaks-rd`; the role differs.
+
+### Contract 1 — Source-document screenshots must land under .peaks/<sid>/prd/source/
+
+PRD's `mcp__playwright__browser_take_screenshot` calls MUST pass `filename` inside `.peaks/<session-id>/prd/source/`, not in the project root and not in `.peaks/<sid>/qa/screenshots/` (PRD's evidence is upstream of QA's). Example:
+
+```bash
+mcp__playwright__browser_take_screenshot \
+  filename=".peaks/<sid>/prd/source/<doc-name>-page-<n>.png" \
+  fullPage=true
+```
+
+After the navigation / snapshot batch, run `find . -maxdepth 1 -name '*.png'` and verify the project root is clean. Sanitise before retention: no login URLs, cookies, headers, tokens, storage state, browser traces, or screenshots containing PII or SSO/MFA material.
+
+### Contract 2 — Login / CAPTCHA / SSO / MFA wall is a hard block, not a skip
+
+If `browser_navigate` redirects to a login / captcha / SSO / MFA, PRD does NOT silently fall back to unauthenticated `fetch` or `WebFetch`. The visible browser is already open; the skill must surface the wall with `AskUserQuestion`:
+
+```
+AskUserQuestion({
+  question: "PRD source <URL> hit a login wall. How should PRD proceed?",
+  options: [
+    { label: "I am logged in / I'll log in now",
+      description: "Pause PRD. The user completes login in the visible browser, then types 'logged in' or equivalent. PRD resumes browser_navigate + browser_snapshot from the post-login page." },
+    { label: "Skip browser capture, paste the document",
+      description: "The user pastes the document content as Markdown / plain text into the chat or drops a .md / .pdf export into .peaks/<sid>/prd/source/. PRD ingests the paste / file. Sanitise cookies / PII / SSO before retention." },
+    { label: "Mark PRD as blocked",
+      description: "Set the PRD state to blocked with reason doc-inaccessible. Do not fabricate facts from a partial read." }
+  ]
+})
+```
+
+Do not infer login from DOM state. The full hard-block contract is defined in `peaks-qa`; PRD inherits the same rules.
+
 ## Skill presence (MANDATORY first action)
 
 Before any analysis or tool call, immediately run:

package/skills/peaks-qa/SKILL.md

@@ -7,9 +7,98 @@ description: QA and verification skill for Peaks. Use when a workflow needs unit
 
 Peaks-Cli QA proves that planned changes are protected and accepted.
 
-## Skill presence (MANDATORY first action)
+## Hard contracts for browser validation (BLOCKING — read before any browser_take_screenshot / login flow)
 
-Before any analysis or tool call, immediately run:
+These two contracts are non-negotiable. The previous prose-only phrasing let the LLM skip the browser gate entirely when an auth wall appeared, and let screenshots land in the project root because the LLM forgot to pass `filename`. Both fail modes are blocking violations; the rules below are what a reviewer should hold the skill to.
+
+### Contract 1 — Screenshot path is mandatory and must land under .peaks/<sid>/qa/screenshots/
+
+Every `mcp__playwright__browser_take_screenshot` call **MUST** pass `filename` whose absolute path is **inside** `.peaks/<session-id>/qa/screenshots/`. Concrete form:
+
+```bash
+mcp__playwright__browser_take_screenshot \
+  filename=".peaks/<sid>/qa/screenshots/<state-or-step>.png" \
+  fullPage=true
+```
+
+The default behaviour of Playwright MCP when `filename` is omitted or points outside that directory is to write a screenshot to the current working directory, which leaves `.png` files scattered at the project root. **This is a workflow violation.** If a screenshot does land outside `.peaks/<sid>/qa/screenshots/` for any reason (e.g. an upstream tool wrote there), QA MUST move it into that directory before declaring the test report complete; do not commit project-root `.png` files. Sanitise before retention: no login URLs, cookies, headers, tokens, storage state, browser traces, or screenshots/logs containing PII or SSO/MFA material.
+
+This rule is enforced by a Peaks-Cli preflight check inside this skill:
+
+```bash
+# After every browser_take_screenshot batch and before declaring the test report complete:
+ls .peaks/<sid>/qa/screenshots/*.png 2>&1
+#   Expected: at least one .png file under the screenshots directory.
+#   "No such file" → BLOCKED. Either the screenshot was never taken, or
+#   it landed in the project root (move it before continuing).
+find . -maxdepth 1 -name '*.png' 2>&1
+#   Expected: empty. Any .png at the project root is a leak — move it
+#   to .peaks/<sid>/qa/screenshots/ before completing this skill.
+```
+
+### Contract 2 — Login / CAPTCHA / SSO / MFA wall is a hard block, not a skip
+
+When the headed browser hits a login wall (Feishu / Lark SSO, GitHub OAuth, custom captcha, MFA push, anything that needs the human), QA **MUST NOT** silently downgrade to static screenshots, manual steps, or any other tool. The skill must surface the wall to the user with `AskUserQuestion` and pick one of three paths:
+
+```
+AskUserQuestion({
+  question: "Headed browser hit a login wall at <URL>. How should QA proceed?",
+  options: [
+    { label: "I am logged in / I'll log in now",
+      description: "Pause QA. The visible browser is already open; the user completes login in-place, then types 'logged in' or equivalent. QA then resumes browser_navigate + browser_snapshot from the post-login page." },
+    { label: "Skip browser validation for this slice",
+      description: "Mark the affected acceptance items as unverified in the test report. Do NOT issue a pass verdict. The slice stays in qa-running with the browser gate marked blocked, reason=login-required. peaks-solo's repair loop will surface this on the next cycle." },
+    { label: "Cancel the workflow",
+      description: "Stop QA immediately. Emit a blocked TXT handoff so peaks-solo can surface the auth wall to the user. Do not mark any acceptance items as accepted." }
+  ]
+})
+```
+
+Do **not** infer login completion from DOM state (presence of an avatar, a user-name span, etc.) — only the user's explicit confirmation counts. Do **not** route through Chrome DevTools MCP as a substitute for the headed browser; it does not launch a browser and cannot simulate user interaction.
+
+This is the hard-block replacement for the previous "wait for the user" prose. Without an explicit decision from the user, QA does not advance past the wall.
+
+## 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-qa`. 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-qa.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 qa --project <repo> --json` if it needs to.
+2. `peaks request show <rid> --role prd --project <repo> --json` (and `--role rd`, `--role ui` if UI is in the swarm plan).
+3. Standards preflight (dry-run only).
+4. Write `.peaks/<session-id>/qa/test-cases/<rid>.md` with test cases that link to PRD acceptance items.
+5. Return only a compact JSON envelope:
+
+```json
+{
+  "role": "qa-test-cases",
+  "rid": "<rid>",
+  "status": "ok" | "blocked" | "skipped",
+  "artefacts": [".peaks/<sid>/qa/test-cases/<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 run the actual test suite, do NOT execute security/perf tools, do NOT open a browser — those are the **QA validation** phase, not the Swarm planning phase. The Swarm sub-agent is "QA(test-cases)" (planning), which only produces the test-case artefact. The actual validation runs after RD implementation in a separate sub-agent or inline run.
+- 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 `--type` is `docs` or `chore`, return `{"status":"skipped","reason":"type=<type>"}` and exit — there is no acceptance surface to plan tests for.
+
+## 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-qa --project <repo> --mode <mode> --gate startup

package/skills/peaks-rd/SKILL.md

@@ -7,9 +7,76 @@ description: Research and development skill for Peaks. Use for engineering analy
 
 Peaks-Cli RD owns engineering analysis, implementation planning, and refactor execution contracts.
 
-## Skill presence (MANDATORY first action)
+## Hard contracts for browser self-test (BLOCKING — read before any browser_take_screenshot / login flow)
 
-Before any analysis or tool call, immediately run:
+For frontend or UI-affecting slices, RD's self-test uses the Playwright MCP headed browser to verify the implementation behaves correctly before handing off to QA. The two contracts below are identical in spirit to `peaks-qa`'s contracts — RD and QA share the same headed-browser path and the same evidence conventions; only the role differs.
+
+### Contract 1 — Self-test screenshots must land under .peaks/<sid>/qa/screenshots/
+
+Even though RD runs the self-test, **the screenshot evidence is QA's** by convention (the test report under `.peaks/<sid>/qa/test-reports/` cites these paths). Therefore RD's `mcp__playwright__browser_take_screenshot` calls MUST pass `filename` whose absolute path is inside `.peaks/<session-id>/qa/screenshots/`, exactly the same contract QA enforces. Do not let Playwright fall back to the project root.
+
+### Contract 2 — Login / CAPTCHA / SSO / MFA wall is a hard block, not a skip
+
+When the headed browser hits an auth wall, RD does **not** skip the browser gate. The skill must surface the wall with `AskUserQuestion` and pick one of three paths:
+
+```
+AskUserQuestion({
+  question: "Headed browser hit a login wall at <URL>. How should RD self-test proceed?",
+  options: [
+    { label: "I am logged in / I'll log in now",
+      description: "Pause RD. The visible browser is already open; the user completes login in-place, then types 'logged in' or equivalent. RD resumes browser_navigate + browser_snapshot from the post-login page." },
+    { label: "Skip browser self-test, hand off to QA",
+      description: "Mark the slice's browser self-test as deferred. Do NOT mark the slice as RD-done; transition to qa-handoff with browser-gate=blocked reason=login-required, and let QA's gate machinery surface the wall to the user again." },
+    { label: "Cancel the workflow",
+      description: "Stop RD. Emit a blocked TXT handoff so peaks-solo can surface the auth wall to the user. Do not modify code paths that the browser gate would have covered." }
+  ]
+})
+```
+
+The full hard-block contract is defined in `peaks-qa` (see "Hard contracts for browser validation" there); RD inherits the same rules. Without an explicit decision from the user, RD does not advance past the wall.
+
+## 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-rd`. 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-rd.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. Read it from the prompt arguments (or from `.peaks/.active-skill.json` if you can, but do not write it).
+- **Statusline install** — already done by Solo at session startup; do not re-run.
+
+What the sub-agent **MUST** still do, from this skill's contract:
+
+0. **Do NOT call `peaks request init`** — Solo has already initialised the request artefact slot in the main loop before fan-out (the runbook has the exact `peaks request init --role rd --id <rid> --project <repo> --apply --type <type> --json` call). The sub-agent reads the slot via `peaks request show <rid> --role rd --project <repo> --json` if it needs to.
+2. `peaks request show <rid> --role prd --project <repo> --json` (and `--role ui` if UI is in the swarm plan).
+3. Standards preflight (dry-run only; Solo owns the apply step).
+4. Project-scan read; create `rd/project-scan.md` only if Solo flagged it missing in the dispatch prompt.
+5. Write the planning artefact: `rd/tech-doc.md` (feature/refactor) or `rd/bug-analysis.md` (bugfix). If `--type` is `config|docs|chore`, **no planning artefact is required** — return immediately with `{"role":"rd-planning","status":"skipped","reason":"type=<type>"}`.
+6. Return only a compact JSON envelope — Solo will run the convergence gate (`ls` checks):
+
+```json
+{
+  "role": "rd-planning",
+  "rid": "<rid>",
+  "status": "ok" | "blocked" | "skipped",
+  "artefacts": [".peaks/<sid>/rd/tech-doc.md"],
+  "warnings": [],
+  "blockedReason": null
+}
+```
+
+**Hard prohibitions** (sub-agent context, in addition to general red lines):
+
+- Do NOT call `Skill(skill="...")` from inside the sub-agent — that defeats the fan-out.
+- Do NOT call `peaks skill presence:set` — Solo owns the active-skill file.
+- 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>"}` and let Solo handle the user message.
+- Do NOT modify code (the Swarm phase is planning only; code edits happen in the RD implementation phase, which is a separate sub-agent or inline run after Gate B).
+
+After returning, Solo re-checks Gate B (`ls .peaks/<sid>/rd/tech-doc.md` etc.) and proceeds to RD implementation, which is a different sub-agent or inline run.
+
+## Skill presence (MANDATORY first action — main-loop context only)
+
+When this skill is running in the main Claude session (not as a sub-agent — i.e. user invoked `peaks-rd` directly, or `peaks-solo` is executing the role inline in assisted/strict mode), before any analysis or tool call, immediately run:
 
 ```bash
 peaks skill presence:set peaks-rd --project <repo> --mode <mode> --gate startup