peaks-cli 1.0.27 → 1.1.0

package/dist/src/cli/commands/core-artifact-commands.js

@@ -10,6 +10,7 @@ import { inspectSkillRunbook } from '../../services/skills/skill-runbook-service
 import { setSkillPresence, clearSkillPresence, getSkillPresence, isSkillPresenceMode, touchSkillHeartbeat } from '../../services/skills/skill-presence-service.js';
 import { ensureSession, getSessionMeta, setSessionMeta, setSessionTitle, listSessionMetas } from '../../services/session/session-manager.js';
 import { findProjectRoot } from '../../services/config/config-safety.js';
+import { generateProjectContext } from '../../services/memory/project-context-service.js';
 import { fail, ok } from '../../shared/result.js';
 import { addJsonOption, failUnsupportedNonDryRun, getErrorMessage, isArtifactProvider, isArtifactSetupStep, printResult } from '../cli-helpers.js';
 export function registerCoreAndArtifactCommands(program, io) {
@@ -73,15 +74,16 @@ export function registerCoreAndArtifactCommands(program, io) {
         .command('presence:set <name>')
         .description('Set the currently active Peaks skill for session-wide visibility')
         .option('--mode <mode>', 'execution mode')
-        .option('--gate <gate>', 'current gate')).action(async (name, options) => {
+        .option('--gate <gate>', 'current gate')
+        .option('--project <path>', 'project root path (auto-detected from cwd when omitted)')).action(async (name, options) => {
+        const projectRoot = options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
         if (options.mode !== undefined && !isSkillPresenceMode(options.mode)) {
             printResult(io, fail('skill.presence:set', 'INVALID_MODE', `Invalid mode: ${options.mode} (expected one of: full-auto, assisted, swarm, strict)`, { name, mode: options.mode }, ['Use a valid mode: full-auto, assisted, swarm, or strict']), options.json);
             process.exitCode = 1;
             return;
         }
-        const presence = setSkillPresence(name, options.mode, options.gate);
+        const presence = setSkillPresence(name, options.mode, options.gate, options.project);
         // Also update session metadata so session dirs self-document
-        const projectRoot = findProjectRoot(process.cwd()) ?? process.cwd();
         const sessionId = await ensureSession(projectRoot);
         setSessionMeta(projectRoot, sessionId, {
             skill: name,
@@ -92,9 +94,18 @@ export function registerCoreAndArtifactCommands(program, io) {
     });
     addJsonOption(skill
         .command('presence:clear')
-        .description('Clear the active Peaks skill presence indicator')).action((options) => {
-        const removed = clearSkillPresence();
-        printResult(io, ok('skill.presence:clear', { active: false, removed }), options.json);
+        .description('Clear the active Peaks skill presence indicator and update project context')
+        .option('--project <path>', 'project root path (auto-detected from cwd when omitted)')).action((options) => {
+        const projectRoot = options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        const removed = clearSkillPresence(options.project);
+        // Auto-update project context so future sessions have up-to-date history
+        try {
+            generateProjectContext(projectRoot);
+        }
+        catch {
+            // non-fatal: context update failure should not block presence clear
+        }
+        printResult(io, ok('skill.presence:clear', { active: false, removed, projectContextUpdated: true }), options.json);
     });
     addJsonOption(skill
         .command('heartbeat')
@@ -216,11 +227,11 @@ export function registerCoreAndArtifactCommands(program, io) {
     const memory = program.command('memory').description('Manage project-local Peaks memory');
     addJsonOption(memory
         .command('extract')
-        .description('Extract stable project memory from skill artifacts into project .claude/memory')
+        .description('Extract stable project memory from skill artifacts into project .peaks/memory')
         .requiredOption('--project <path>', 'target project root')
         .requiredOption('--artifact <path...>', 'skill artifact paths inside the project')
         .option('--dry-run', 'preview writes without changing files', true)
-        .option('--apply', 'write extracted memories into project .claude/memory')).action((options) => {
+        .option('--apply', 'write extracted memories into project .peaks/memory')).action((options) => {
         try {
             const result = executeProjectMemoryExtract({ projectRoot: options.project, artifactPaths: options.artifact, apply: options.apply === true });
             printResult(io, ok('memory.extract', summarizeProjectMemoryExtractResult(result)), options.json);
@@ -232,11 +243,11 @@ export function registerCoreAndArtifactCommands(program, io) {
     });
     addJsonOption(memory
         .command('sync')
-        .description('Back up project .claude/memory into the artifact workspace')
+        .description('Back up project .peaks/memory into the artifact workspace')
         .requiredOption('--project <path>', 'target project root')
         .requiredOption('--workspace <path>', 'artifact workspace path')
         .option('--dry-run', 'preview copies without changing files', true)
-        .option('--apply', 'copy project .claude/memory into artifact workspace backup')).action((options) => {
+        .option('--apply', 'copy project .peaks/memory into artifact workspace backup')).action((options) => {
         try {
             const result = executeProjectMemoryBackup({ projectRoot: options.project, artifactWorkspacePath: options.workspace, apply: options.apply === true });
             printResult(io, ok('memory.sync', summarizeProjectMemoryBackupResult(result)), options.json);

package/dist/src/cli/commands/project-commands.js

@@ -1,4 +1,6 @@
 import { loadProjectDashboard } from '../../services/dashboard/project-dashboard-service.js';
+import { generateProjectContext, readProjectContext } from '../../services/memory/project-context-service.js';
+import { readProjectMemories } from '../../services/memory/project-memory-service.js';
 import { fail, ok } from '../../shared/result.js';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
 export function registerProjectCommands(program, io) {
@@ -39,4 +41,61 @@ export function registerProjectCommands(program, io) {
             process.exitCode = 1;
         }
     });
+    addJsonOption(project
+        .command('context')
+        .description('Generate or read persistent project context for cross-session Peaks understanding')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--read', 'read existing PROJECT.md without regenerating')).action((options) => {
+        try {
+            if (options.read) {
+                const content = readProjectContext(options.project);
+                if (content === null) {
+                    printResult(io, ok('project.context', { exists: false, path: `${options.project}/.peaks/PROJECT.md` }), options.json);
+                    return;
+                }
+                printResult(io, ok('project.context', { exists: true, path: `${options.project}/.peaks/PROJECT.md`, content }), options.json);
+                return;
+            }
+            const result = generateProjectContext(options.project);
+            printResult(io, ok('project.context', {
+                path: result.path,
+                sessionCount: result.sessionCount,
+                content: result.content
+            }), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('project.context', 'PROJECT_CONTEXT_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Check the project path and .peaks directory']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    // --- Structured project memory (durable, LLM-authored, stored under .peaks/memory) ---
+    addJsonOption(project
+        .command('memories')
+        .description('Read durable project memories (decisions, conventions, modules, rules) from .peaks/memory for LLM consumption')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--kind <kind>', 'filter by kind: project, rule, decision, reference, feedback, convention, module')).action((options) => {
+        try {
+            const result = readProjectMemories(options.project);
+            if (options.kind) {
+                const memories = result.memories.filter((memory) => memory.kind === options.kind);
+                printResult(io, ok('project.memories', {
+                    memoryDir: result.memoryDir,
+                    kind: options.kind,
+                    total: memories.length,
+                    memories
+                }), options.json);
+                return;
+            }
+            printResult(io, ok('project.memories', {
+                memoryDir: result.memoryDir,
+                total: result.total,
+                byKind: result.byKind,
+                memories: result.memories
+            }), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('project.memories', 'PROJECT_MEMORIES_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Check the project path and .peaks/memory directory']), options.json);
+            process.exitCode = 1;
+        }
+    });
 }

package/dist/src/services/memory/project-context-service.d.ts

@@ -0,0 +1,11 @@
+export type ProjectContextSection = {
+    heading: string;
+    body: string;
+};
+export declare function generateProjectContext(projectRoot: string): {
+    path: string;
+    content: string;
+    sessionCount: number;
+};
+export declare function readProjectContext(projectRoot: string): string | null;
+export declare function getProjectContextPath(projectRoot: string): string;

package/dist/src/services/memory/project-context-service.js

@@ -0,0 +1,147 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { listSessionMetas } from '../session/session-manager.js';
+const PROJECT_CONTEXT_FILE = '.peaks/PROJECT.md';
+const CONTEXT_HEADER = `# Peaks Project Context
+
+> Auto-generated project memory. Peaks reads this at the start of each session to understand
+> the project's history, tech stack, conventions, and past decisions.
+> Last updated: `;
+const MANAGED_BLOCK_START = '<!-- peaks-managed:session-history-start -->';
+const MANAGED_BLOCK_END = '<!-- peaks-managed:session-history-end -->';
+function projectName(projectRoot) {
+    const pkgPath = join(projectRoot, 'package.json');
+    if (!existsSync(pkgPath))
+        return projectRoot.split(/[\\/]/).pop() ?? 'unknown';
+    try {
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+        return pkg.name ?? projectRoot.split(/[\\/]/).pop() ?? 'unknown';
+    }
+    catch {
+        return projectRoot.split(/[\\/]/).pop() ?? 'unknown';
+    }
+}
+function listMdFiles(dir, maxDepth = 3) {
+    const results = [];
+    if (!existsSync(dir) || maxDepth <= 0)
+        return results;
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return results;
+    }
+    for (const entry of entries) {
+        if (entry.name.startsWith('.'))
+            continue;
+        const full = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            results.push(...listMdFiles(full, maxDepth - 1));
+        }
+        else if (entry.isFile() && entry.name.endsWith('.md')) {
+            results.push(full);
+        }
+    }
+    return results;
+}
+function extractOneLineSummary(sessionRoot) {
+    const artifacts = listMdFiles(sessionRoot, 4);
+    for (const artifact of artifacts.slice(0, 5)) {
+        try {
+            const content = readFileSync(artifact, 'utf8');
+            // Grab the first non-heading, non-empty line after the front section
+            const lines = content.split(/\r?\n/);
+            for (const line of lines) {
+                const trimmed = line.trim();
+                if (!trimmed || trimmed.startsWith('#') || trimmed.startsWith('-') || trimmed.startsWith('`'))
+                    continue;
+                if (trimmed.length > 10 && trimmed.length < 200)
+                    return trimmed;
+                break;
+            }
+        }
+        catch {
+            // skip unreadable
+        }
+    }
+    return null;
+}
+function buildSessionHistory(projectRoot) {
+    const metas = listSessionMetas(projectRoot);
+    if (metas.length === 0) {
+        return `${MANAGED_BLOCK_START}\n\n_No sessions recorded yet._\n\n${MANAGED_BLOCK_END}`;
+    }
+    const maxSessions = 15;
+    // Sort by createdAt descending (most recent first)
+    const sorted = [...metas].sort((a, b) => (b.createdAt || '').localeCompare(a.createdAt || ''));
+    const recent = sorted.slice(0, maxSessions);
+    let body = `${MANAGED_BLOCK_START}\n\n## Timeline (${metas.length} sessions`;
+    if (metas.length > maxSessions)
+        body += `, showing last ${maxSessions}`;
+    body += ')\n\n';
+    // Human-readable timeline: date | name | brief
+    body += `| Date | Directory | Title | What |\n`;
+    body += `|------|-----------|-------|------|\n`;
+    for (const meta of recent) {
+        const date = meta.createdAt ? meta.createdAt.slice(0, 10) : '?';
+        const dir = meta.sessionId;
+        const title = (meta.title ?? 'Untitled').slice(0, 40);
+        const skill = meta.skill ?? '-';
+        // Extract one-line summary from artifacts for the "What" column
+        const sessionRoot = join(projectRoot, '.peaks', meta.sessionId);
+        const summary = extractOneLineSummary(sessionRoot);
+        const brief = summary ? summary.slice(0, 70) : skill;
+        body += `| ${date} | \`${dir}\` | ${title} | ${brief} |\n`;
+    }
+    body += `\n${MANAGED_BLOCK_END}`;
+    return body;
+}
+export function generateProjectContext(projectRoot) {
+    const peaksDir = join(projectRoot, '.peaks');
+    if (!existsSync(peaksDir)) {
+        mkdirSync(peaksDir, { recursive: true });
+    }
+    const contextPath = join(projectRoot, PROJECT_CONTEXT_FILE);
+    const name = projectName(projectRoot);
+    const now = new Date().toISOString();
+    const sessionHistory = buildSessionHistory(projectRoot);
+    const header = `${CONTEXT_HEADER}${now}\n\n## Project: ${name}\n`;
+    let content;
+    if (existsSync(contextPath)) {
+        const existing = readFileSync(contextPath, 'utf8');
+        const startIdx = existing.indexOf(MANAGED_BLOCK_START);
+        const endIdx = existing.indexOf(MANAGED_BLOCK_END);
+        // Update the Last-updated timestamp in the header
+        const updatedExisting = existing.replace(/Last updated: .*/, `Last updated: ${now}`);
+        if (startIdx >= 0 && endIdx > startIdx) {
+            // Replace managed block, preserve user content outside it
+            const before = updatedExisting.slice(0, startIdx);
+            const after = updatedExisting.slice(endIdx + MANAGED_BLOCK_END.length);
+            content = before + sessionHistory + after;
+        }
+        else {
+            // No managed block found — append
+            content = updatedExisting.trimEnd() + '\n\n' + sessionHistory + '\n';
+        }
+    }
+    else {
+        content = header + '\n' + sessionHistory + '\n';
+    }
+    writeFileSync(contextPath, content, 'utf8');
+    return { path: contextPath, content, sessionCount: listSessionMetas(projectRoot).length };
+}
+export function readProjectContext(projectRoot) {
+    const contextPath = join(projectRoot, PROJECT_CONTEXT_FILE);
+    if (!existsSync(contextPath))
+        return null;
+    try {
+        return readFileSync(contextPath, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+export function getProjectContextPath(projectRoot) {
+    return join(projectRoot, PROJECT_CONTEXT_FILE);
+}

package/dist/src/services/memory/project-memory-service.d.ts

@@ -1,4 +1,4 @@
-export type ProjectMemoryKind = 'project' | 'rule' | 'decision' | 'reference' | 'feedback';
+export type ProjectMemoryKind = 'project' | 'rule' | 'decision' | 'reference' | 'feedback' | 'convention' | 'module';
 export type ExtractedProjectMemory = {
     title: string;
     kind: ProjectMemoryKind;
@@ -59,6 +59,21 @@ export type ProjectMemoryBackupPlan = {
 export type ProjectMemoryBackupResult = ProjectMemoryBackupPlan & {
     copiedFiles: string[];
 };
+export type StoredProjectMemory = {
+    name: string;
+    title: string;
+    kind: ProjectMemoryKind;
+    sourceArtifact: string | null;
+    body: string;
+    filePath: string;
+};
+export type ProjectMemoryReadResult = {
+    projectRoot: string;
+    memoryDir: string;
+    total: number;
+    byKind: Record<ProjectMemoryKind, StoredProjectMemory[]>;
+    memories: StoredProjectMemory[];
+};
 type ExtractPlanOptions = {
     projectRoot: string;
     artifactPaths: string[];
@@ -76,4 +91,5 @@ export declare function createProjectMemoryBackupPlan(options: BackupPlanOptions
 export declare function executeProjectMemoryBackup(options: BackupPlanOptions): ProjectMemoryBackupResult;
 export declare function summarizeProjectMemoryExtractResult(result: ProjectMemoryExtractResult): ProjectMemoryExtractSummary;
 export declare function summarizeProjectMemoryBackupResult(result: ProjectMemoryBackupResult): ProjectMemoryBackupSummary;
+export declare function readProjectMemories(projectRoot: string): ProjectMemoryReadResult;
 export {};

package/dist/src/services/memory/project-memory-service.js

@@ -4,7 +4,7 @@ import { isInsidePath, isWindowsAbsolutePath, normalizePath, resolveInputPath, s
 import { containsSensitiveConfigValue, isSensitiveConfigPath } from '../config/config-service.js';
 const START_MARKER = '<!-- peaks-memory:start -->';
 const END_MARKER = '<!-- peaks-memory:end -->';
-const VALID_MEMORY_KINDS = new Set(['project', 'rule', 'decision', 'reference', 'feedback']);
+const VALID_MEMORY_KINDS = new Set(['project', 'rule', 'decision', 'reference', 'feedback', 'convention', 'module']);
 function normalizeRoot(path) {
     return resolveInputPath(path);
 }
@@ -42,11 +42,11 @@ function assertInsideProject(path, projectRoot) {
 function assertSafeProjectMemoryDir(projectRoot) {
     const resolvedRoot = normalizeRoot(projectRoot);
     const realRoot = normalizeRealRoot(projectRoot);
-    const claudeDir = join(resolvedRoot, '.claude');
-    if (existsSync(claudeDir) && lstatSync(claudeDir).isSymbolicLink()) {
+    const peaksDir = join(resolvedRoot, '.peaks');
+    if (existsSync(peaksDir) && lstatSync(peaksDir).isSymbolicLink()) {
         throw new Error('Project memory directory must stay inside the project root');
     }
-    const memoryDir = join(claudeDir, 'memory');
+    const memoryDir = join(peaksDir, 'memory');
     if (existsSync(memoryDir)) {
         if (lstatSync(memoryDir).isSymbolicLink()) {
             throw new Error('Project memory directory must stay inside the project root');
@@ -136,6 +136,41 @@ function renderMemoryFile(memory) {
         ''
     ].join('\n');
 }
+function parseStoredMemoryFile(content, filePath) {
+    const normalized = content.replace(/\r\n/g, '\n');
+    if (!normalized.startsWith('---\n'))
+        return null;
+    const endIndex = normalized.indexOf('\n---\n', 4);
+    if (endIndex < 0)
+        return null;
+    const frontmatter = normalized.slice(4, endIndex);
+    const body = normalized.slice(endIndex + '\n---\n'.length).trim();
+    let name;
+    let description;
+    let kind;
+    let sourceArtifact;
+    for (const rawLine of frontmatter.split('\n')) {
+        const line = rawLine.trim();
+        if (line.startsWith('name:'))
+            name = line.slice('name:'.length).trim();
+        else if (line.startsWith('description:'))
+            description = line.slice('description:'.length).trim();
+        else if (line.startsWith('type:'))
+            kind = line.slice('type:'.length).trim();
+        else if (line.startsWith('sourceArtifact:'))
+            sourceArtifact = line.slice('sourceArtifact:'.length).trim();
+    }
+    if (!name || !kind || !VALID_MEMORY_KINDS.has(kind) || body.length === 0)
+        return null;
+    return {
+        name,
+        title: description ?? name,
+        kind: kind,
+        sourceArtifact: sourceArtifact && sourceArtifact !== 'undefined' ? sourceArtifact : null,
+        body,
+        filePath
+    };
+}
 function summarizeExtractResult(result) {
     return {
         apply: result.apply,
@@ -304,3 +339,36 @@ export function summarizeProjectMemoryExtractResult(result) {
 export function summarizeProjectMemoryBackupResult(result) {
     return summarizeBackupResult(result);
 }
+function emptyByKind() {
+    return {
+        project: [],
+        rule: [],
+        decision: [],
+        reference: [],
+        feedback: [],
+        convention: [],
+        module: []
+    };
+}
+export function readProjectMemories(projectRoot) {
+    const normalizedRoot = normalizeRoot(projectRoot);
+    const memoryDir = assertSafeProjectMemoryDir(normalizedRoot);
+    const memories = [];
+    for (const filePath of listMarkdownFiles(memoryDir)) {
+        const parsed = parseStoredMemoryFile(readFileSync(filePath, 'utf8'), filePath);
+        if (parsed)
+            memories.push(parsed);
+    }
+    memories.sort((left, right) => left.name.localeCompare(right.name));
+    const byKind = emptyByKind();
+    for (const memory of memories) {
+        byKind[memory.kind].push(memory);
+    }
+    return {
+        projectRoot: normalizedRoot,
+        memoryDir,
+        total: memories.length,
+        byKind,
+        memories
+    };
+}

package/dist/src/services/skills/skill-presence-service.d.ts

@@ -9,8 +9,8 @@ export type SkillPresence = {
     setAt: string;
     lastHeartbeat?: string;
 };
-export declare function exportSkillPresence(): string;
-export declare function setSkillPresence(skill: string, mode?: string, gate?: string): SkillPresence;
-export declare function getSkillPresence(): SkillPresence | null;
-export declare function touchSkillHeartbeat(): SkillPresence | null;
-export declare function clearSkillPresence(): boolean;
+export declare function exportSkillPresence(projectRootOverride?: string): string;
+export declare function setSkillPresence(skill: string, mode?: string, gate?: string, projectRootOverride?: string): SkillPresence;
+export declare function getSkillPresence(projectRootOverride?: string): SkillPresence | null;
+export declare function touchSkillHeartbeat(projectRootOverride?: string): SkillPresence | null;
+export declare function clearSkillPresence(projectRootOverride?: string): boolean;

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

@@ -12,14 +12,16 @@ export function isSkillPresenceMode(value) {
 }
 const PRESENCE_FILE = '.peaks/.active-skill.json';
 const SESSION_FILE = '.peaks/.session.json';
-function resolveProjectRoot() {
+function resolveProjectRoot(override) {
+    if (override)
+        return resolve(override);
     return findProjectRoot(process.cwd()) ?? process.cwd();
 }
-function resolvePresencePath() {
-    return resolve(resolveProjectRoot(), PRESENCE_FILE);
+function resolvePresencePath(projectRootOverride) {
+    return resolve(resolveProjectRoot(projectRootOverride), PRESENCE_FILE);
 }
-function getCurrentSessionId() {
-    const sessionPath = resolve(resolveProjectRoot(), SESSION_FILE);
+function getCurrentSessionId(projectRootOverride) {
+    const sessionPath = resolve(resolveProjectRoot(projectRootOverride), SESSION_FILE);
     if (!existsSync(sessionPath))
         return null;
     try {
@@ -32,12 +34,12 @@ function getCurrentSessionId() {
         return null;
     }
 }
-export function exportSkillPresence() {
-    return resolvePresencePath();
+export function exportSkillPresence(projectRootOverride) {
+    return resolvePresencePath(projectRootOverride);
 }
-export function setSkillPresence(skill, mode, gate) {
+export function setSkillPresence(skill, mode, gate, projectRootOverride) {
     const validatedMode = mode && isSkillPresenceMode(mode) ? mode : undefined;
-    const sessionId = getCurrentSessionId();
+    const sessionId = getCurrentSessionId(projectRootOverride);
     const now = new Date().toISOString();
     const presence = {
         skill,
@@ -47,7 +49,7 @@ export function setSkillPresence(skill, mode, gate) {
         setAt: now,
         lastHeartbeat: now
     };
-    const presencePath = resolvePresencePath();
+    const presencePath = resolvePresencePath(projectRootOverride);
     const presenceDir = dirname(presencePath);
     if (!existsSync(presenceDir)) {
         mkdirSync(presenceDir, { recursive: true });
@@ -55,8 +57,8 @@ export function setSkillPresence(skill, mode, gate) {
     writeFileSync(presencePath, JSON.stringify(presence, null, 2), 'utf8');
     return presence;
 }
-export function getSkillPresence() {
-    const presencePath = resolvePresencePath();
+export function getSkillPresence(projectRootOverride) {
+    const presencePath = resolvePresencePath(projectRootOverride);
     if (!existsSync(presencePath)) {
         return null;
     }
@@ -67,7 +69,7 @@ export function getSkillPresence() {
             return null;
         }
         if (typeof parsed.sessionId === 'string' && parsed.sessionId.length > 0) {
-            const currentSessionId = getCurrentSessionId();
+            const currentSessionId = getCurrentSessionId(projectRootOverride);
             if (currentSessionId && parsed.sessionId !== currentSessionId) {
                 unlinkSync(presencePath);
                 return null;
@@ -79,8 +81,8 @@ export function getSkillPresence() {
         return null;
     }
 }
-export function touchSkillHeartbeat() {
-    const presencePath = resolvePresencePath();
+export function touchSkillHeartbeat(projectRootOverride) {
+    const presencePath = resolvePresencePath(projectRootOverride);
     if (!existsSync(presencePath)) {
         return null;
     }
@@ -91,7 +93,7 @@ export function touchSkillHeartbeat() {
             return null;
         }
         if (typeof parsed.sessionId === 'string' && parsed.sessionId.length > 0) {
-            const currentSessionId = getCurrentSessionId();
+            const currentSessionId = getCurrentSessionId(projectRootOverride);
             if (currentSessionId && parsed.sessionId !== currentSessionId) {
                 unlinkSync(presencePath);
                 return null;
@@ -105,8 +107,8 @@ export function touchSkillHeartbeat() {
         return null;
     }
 }
-export function clearSkillPresence() {
-    const presencePath = resolvePresencePath();
+export function clearSkillPresence(projectRootOverride) {
+    const presencePath = resolvePresencePath(projectRootOverride);
     if (!existsSync(presencePath)) {
         return false;
     }

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

@@ -1 +1 @@
-export declare const CLI_VERSION = "1.0.27";
+export declare const CLI_VERSION = "1.1.0";

package/dist/src/shared/version.js

@@ -1 +1 @@
-export const CLI_VERSION = "1.0.27";
+export const CLI_VERSION = "1.1.0";

package/package.json

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

package/skills/peaks-prd/SKILL.md

@@ -12,10 +12,16 @@ Peaks-Cli PRD turns user intent into verifiable product artifacts.
 Before any analysis or tool call, immediately run:
 
 ```bash
-peaks skill presence:set peaks-prd --mode <mode> --gate startup
+peaks skill presence:set peaks-prd --project <repo> --mode <mode> --gate startup
 ```
+Read persistent project memory via CLI (durable, LLM-authored memories):
 
-Then display: `Peaks-Cli Skill: peaks-prd | Peaks-Cli Gate: startup | Next: <one short action>`. Update with `peaks skill presence:set peaks-prd --mode <mode> --gate <gate>` when gates change. When the role's work ends, run `peaks skill presence:clear`.
+```bash
+peaks project memories --project <repo> --json
+```
+
+This returns durable memories from `.peaks/memory` — decisions, conventions, modules, and rules captured in past sessions. Filter with `--kind <decision|convention|module|rule|reference|project>`. (`.peaks/PROJECT.md` is a human-readable session timeline only.)
+Then display: `Peaks-Cli Skill: peaks-prd | Peaks-Cli Gate: startup | Next: <one short action>`. Update with `peaks skill presence:set peaks-prd --project <repo> --mode <mode> --gate <gate>` when gates change. When the role's work ends, run `peaks skill presence:clear --project <repo>`.
 
 ## Responsibilities
 
@@ -54,7 +60,7 @@ For a feature / bug / clarification request with no authenticated source documen
 ```bash
 # 0. confirm PRD's own runbook integrity before driving any phase
 peaks skill runbook peaks-prd --json
-peaks skill presence:set peaks-prd               # show persistent skill presence every turn
+peaks skill presence:set peaks-prd --project <repo>  # show persistent skill presence every turn
 
 # 1. capture the request as the canonical PRD artifact (preview, then apply)
 peaks request init --role prd --id <request-id> --project <repo> --json
@@ -74,7 +80,7 @@ peaks codegraph status  --project <repo>                   # local index status
 
 # 5. write goals / non-goals / acceptance into the artifact body, then hand off
 peaks request show <request-id> --role prd --project <repo> --json
-peaks skill presence:clear                      # handoff complete, remove presence indicator
+peaks skill presence:clear --project <repo>                      # handoff complete, remove presence indicator
 ```
 
 For an authenticated product document request (Feishu/Lark/wiki), add before step 5:

package/skills/peaks-qa/SKILL.md

@@ -12,10 +12,16 @@ Peaks-Cli QA proves that planned changes are protected and accepted.
 Before any analysis or tool call, immediately run:
 
 ```bash
-peaks skill presence:set peaks-qa --mode <mode> --gate startup
+peaks skill presence:set peaks-qa --project <repo> --mode <mode> --gate startup
 ```
+Read persistent project memory via CLI (durable, LLM-authored memories):
 
-Then display: `Peaks-Cli Skill: peaks-qa | Peaks-Cli Gate: startup | Next: <one short action>`. Update with `peaks skill presence:set peaks-qa --mode <mode> --gate <gate>` when gates change. When the role's work ends, run `peaks skill presence:clear`.
+```bash
+peaks project memories --project <repo> --json
+```
+
+This returns durable memories from `.peaks/memory` — decisions, conventions, modules, and rules captured in past sessions. Filter with `--kind <decision|convention|module|rule|reference|project>`. (`.peaks/PROJECT.md` is a human-readable session timeline only.)
+Then display: `Peaks-Cli Skill: peaks-qa | Peaks-Cli Gate: startup | Next: <one short action>`. Update with `peaks skill presence:set peaks-qa --project <repo> --mode <mode> --gate <gate>` when gates change. When the role's work ends, run `peaks skill presence:clear --project <repo>`.
 
 ## Responsibilities
 
@@ -47,7 +53,7 @@ The default sequence the QA skill should execute. Do not skip the boundary check
 ```bash
 # 0. confirm QA's own runbook integrity before validating anything
 peaks skill runbook peaks-qa --json
-peaks skill presence:set peaks-qa               # show persistent skill presence every turn
+peaks skill presence:set peaks-qa --project <repo>  # show persistent skill presence every turn
 
 # 1. capture the QA request artifact and read upstream scope
 peaks request init --role qa --id <request-id> --project <repo> --apply --json
@@ -134,7 +140,7 @@ peaks request lint <rid> --role qa --project <repo> --json
 # 9. on verdict=return-to-rd, route findings back through the request id; otherwise close.
 peaks request show <request-id> --role qa --project <repo> --json
 peaks openspec archive <change-id> --project <repo> --json   # preview, then --apply on full pass
-peaks skill presence:clear                      # QA complete, remove presence indicator
+peaks skill presence:clear --project <repo>                      # QA complete, remove presence indicator
 ```
 
 Verdict `pass` is blocked until every applicable validation gate has evidence in the artifact.

package/skills/peaks-rd/SKILL.md

@@ -12,10 +12,16 @@ Peaks-Cli RD owns engineering analysis, implementation planning, and refactor ex
 Before any analysis or tool call, immediately run:
 
 ```bash
-peaks skill presence:set peaks-rd --mode <mode> --gate startup
+peaks skill presence:set peaks-rd --project <repo> --mode <mode> --gate startup
 ```
+Read persistent project memory via CLI (durable, LLM-authored memories):
 
-Then display: `Peaks-Cli Skill: peaks-rd | Peaks-Cli Gate: startup | Next: <one short action>`. Update with `peaks skill presence:set peaks-rd --mode <mode> --gate <gate>` when gates change. When the role's work ends, run `peaks skill presence:clear`.
+```bash
+peaks project memories --project <repo> --json
+```
+
+This returns durable memories from `.peaks/memory` — decisions, conventions, modules, and rules captured in past sessions. Filter with `--kind <decision|convention|module|rule|reference|project>`. (`.peaks/PROJECT.md` is a human-readable session timeline only.)
+Then display: `Peaks-Cli Skill: peaks-rd | Peaks-Cli Gate: startup | Next: <one short action>`. Update with `peaks skill presence:set peaks-rd --project <repo> --mode <mode> --gate <gate>` when gates change. When the role's work ends, run `peaks skill presence:clear --project <repo>`.
 
 ## Responsibilities
 
@@ -41,7 +47,7 @@ The default sequence the RD skill should execute for a code-touching request. Sk
 ```bash
 # 0. confirm RD's own runbook integrity before any code edit
 peaks skill runbook peaks-rd --json
-peaks skill presence:set peaks-rd               # show persistent skill presence every turn
+peaks skill presence:set peaks-rd --project <repo>  # show persistent skill presence every turn
 
 # 1. capture the RD request artifact and read upstream PRD / UI scope
 peaks request init --role rd --id <request-id> --project <repo> --apply --json
@@ -138,7 +144,7 @@ peaks openspec validate <change-id> --project <repo> --json    # exit gate (re-r
 # 8. hand off to QA via the cross-linked request id
 peaks request init --role qa --id <request-id> --project <repo> --apply --json
 peaks request show <request-id> --role rd --project <repo> --json
-peaks skill presence:clear                      # handoff complete, remove presence indicator
+peaks skill presence:clear --project <repo>                      # handoff complete, remove presence indicator
 ```
 
 For refactor work, the coverage ≥ 95% gate in `Refactor hard gates` still applies and must be recorded in the artifact before slicing begins.

package/skills/peaks-sc/SKILL.md

@@ -12,10 +12,16 @@ Peaks-Cli SC records how product, RD, QA, code, and artifacts move together.
 Before any analysis or tool call, immediately run:
 
 ```bash
-peaks skill presence:set peaks-sc --mode <mode> --gate startup
+peaks skill presence:set peaks-sc --project <repo> --mode <mode> --gate startup
 ```
+Read persistent project memory via CLI (durable, LLM-authored memories):
 
-Then display: `Peaks-Cli Skill: peaks-sc | Peaks-Cli Gate: startup | Next: <one short action>`. Update with `peaks skill presence:set peaks-sc --mode <mode> --gate <gate>` when gates change. When the role's work ends, run `peaks skill presence:clear`.
+```bash
+peaks project memories --project <repo> --json
+```
+
+This returns durable memories from `.peaks/memory` — decisions, conventions, modules, and rules captured in past sessions. Filter with `--kind <decision|convention|module|rule|reference|project>`. (`.peaks/PROJECT.md` is a human-readable session timeline only.)
+Then display: `Peaks-Cli Skill: peaks-sc | Peaks-Cli Gate: startup | Next: <one short action>`. Update with `peaks skill presence:set peaks-sc --project <repo> --mode <mode> --gate <gate>` when gates change. When the role's work ends, run `peaks skill presence:clear --project <repo>`.
 
 ## Responsibilities
 
@@ -50,7 +56,7 @@ Use gstack as a concrete source-control and release workflow reference for the `
 
 ## Project memory backup
 
-Project `.claude/memory` is the primary source for durable project memory. At approved checkpoints, use `peaks memory sync --project <path> --workspace <artifact-workspace> --apply` to back up the full project memory directory into the artifact repository workspace; do not treat the artifact backup as a second writable memory source.
+Project `.peaks/memory` is the primary source for durable project memory. At approved checkpoints, use `peaks memory sync --project <path> --workspace <artifact-workspace> --apply` to back up the full project memory directory into the artifact repository workspace; do not treat the artifact backup as a second writable memory source.
 
 ## Commit boundary derivation
 
@@ -77,7 +83,7 @@ Use this sequence when SC owns the change-control pass for a refactor or release
 # in:  none
 # out: runbook version, presence set
 peaks skill runbook peaks-sc --json
-peaks skill presence:set peaks-sc               # show persistent skill presence every turn
+peaks skill presence:set peaks-sc --project <repo>  # show persistent skill presence every turn
 
 # 1. Derive commit boundaries (OpenSpec preferred, git diff fallback)
 # in:  change-id, repo path
@@ -115,7 +121,7 @@ peaks sc boundary --slice-id <slice-id> --artifact <artifact-path> --code <code-
 # out: sync result or dry-run preview
 peaks memory sync --project <repo> --workspace <workspace> --apply --json
 peaks artifacts sync --workspace <workspace> --apply --json
-peaks skill presence:clear                      # SC complete, remove presence indicator
+peaks skill presence:clear --project <repo>                      # SC complete, remove presence indicator
 ```
 
 The final two `--apply` calls require explicit authorization. Without it, default to `--dry-run` or omit the sync calls entirely and keep the boundary evidence local under `.peaks/<session-id>/`.

package/skills/peaks-solo/SKILL.md

@@ -71,12 +71,30 @@ If the user already names a profile in their invocation (e.g. `/peaks-solo --ful
 Only after the mode is known (user selected or explicitly named), run:
 
 ```bash
-peaks skill presence:set peaks-solo --mode <mode-value> --gate startup
+peaks skill presence:set peaks-solo --project <repo> --mode <mode-value> --gate startup
 ```
 
 Then display the compact status header: `Peaks-Cli Skill: peaks-solo | Peaks-Cli Gate: startup | Next: <one short action>`. Display this header on EVERY turn while the skill is active.
 
-Update with `peaks skill presence:set peaks-solo --mode <mode> --gate <gate>` when gates change. The presence file persists across the full workflow lifecycle — do NOT clear it at workflow end.
+Update with `peaks skill presence:set peaks-solo --project <repo> --mode <mode> --gate <gate>` when gates change. The presence file persists across the full workflow lifecycle — do NOT clear it at workflow end.
+
+### Peaks-Cli Step 2.3: Load project memory (durable, LLM-authored memories)
+
+Before planning any work, read the project's persistent memory — durable memories that survive across sessions:
+
+```bash
+peaks project memories --project <repo> --json
+```
+
+This returns durable memories from `.peaks/memory`, grouped by kind:
+- **module** — code areas touched, with risk and rationale captured by past sessions
+- **decision** — architectural choices, why they were made, what they affect
+- **convention** — discovered project patterns (code style, naming, tooling)
+- **rule** / **reference** / **project** — standing constraints, external pointers, and project context
+
+Filter with `--kind <decision|convention|module|rule|reference|project>` when you only need one slice. Use this to understand what exists, what was decided, and what to avoid re-litigating. Memories are LLM-authored at approved checkpoints via `peaks memory extract`.
+
+`.peaks/PROJECT.md` is a human-readable session timeline only — do NOT use it for LLM context.
 
 ### Peaks-Cli Step 2.5: Set session title
 
@@ -579,7 +597,7 @@ Solo is itself a skill running in the current session. To "invoke peaks-rd" or "
 **Presence restoration after role skill returns (MANDATORY):** Role skills (peaks-rd, peaks-qa, peaks-ui) call `peaks skill presence:set <role>` internally, which overwrites `.peaks/.active-skill.json`. After EVERY role skill returns — whether success, repair-needed, or failure — Solo MUST immediately restore the orchestrator presence by re-running the same presence command from Step 2:
 
 ```bash
-peaks skill presence:set peaks-solo --mode <mode> --gate <current-gate>
+peaks skill presence:set peaks-solo --project <repo> --mode <mode> --gate <current-gate>
 ```
 
 This keeps the CLAUDE.md status header accurate (`Peaks-Cli Skill: peaks-solo`) instead of showing a stale role name. Use the current mode and gate values; the gate may have advanced since startup. Skipping this step causes the header to display the last role skill name permanently.
@@ -606,7 +624,7 @@ When `peaks-qa` returns `verdict=return-to-rd`, Solo does NOT manually rewrite R
 6. Repeat steps 1-5 until QA returns `verdict=pass`, or the cap below fires.
    **After each repair iteration** (after peaks-rd and peaks-qa both return), Solo MUST restore presence:
    ```bash
-   peaks skill presence:set peaks-solo --mode <mode> --gate repair-cycle-<N>
+   peaks skill presence:set peaks-solo --project <repo> --mode <mode> --gate repair-cycle-<N>
    ```
 
 **Repair cycle cap**: After 3 repair cycles without a passing QA verdict, emit a blocked TXT handoff regardless of remaining issues. Do not loop indefinitely. If a specific issue cannot be resolved within 3 cycles, mark it as a known blocker in the TXT handoff and proceed to the SC phase.
@@ -781,7 +799,7 @@ Use Peaks-Cli TXT for the compact handoff capsule: mode, validated decisions, ar
 
 ### Workflow completion (no auto-exit)
 
-Do NOT call `peaks skill presence:clear` at workflow end. The presence file and header remain active so the user stays inside the workflow context. The user can continue with follow-up requirements naturally — no need to re-invoke `/peaks-solo`. The header continues to display the active skill and current gate.
+Do NOT call `peaks skill presence:clear --project <repo>` at workflow end. The presence file and header remain active so the user stays inside the workflow context. The user can continue with follow-up requirements naturally — no need to re-invoke `/peaks-solo`. The header continues to display the active skill and current gate.
 
 ## Peaks-Cli External references and lifecycle
 

package/skills/peaks-txt/SKILL.md

@@ -12,10 +12,16 @@ Peaks-Cli TXT compresses workflow context into portable, role-specific artifacts
 Before any analysis or tool call, immediately run:
 
 ```bash
-peaks skill presence:set peaks-txt --mode <mode> --gate startup
+peaks skill presence:set peaks-txt --project <repo> --mode <mode> --gate startup
 ```
+Read persistent project memory via CLI (durable, LLM-authored memories):
 
-Then display: `Peaks-Cli Skill: peaks-txt | Peaks-Cli Gate: startup | Next: <one short action>`. Update with `peaks skill presence:set peaks-txt --mode <mode> --gate <gate>` when gates change. When the role's work ends, run `peaks skill presence:clear`.
+```bash
+peaks project memories --project <repo> --json
+```
+
+This returns durable memories from `.peaks/memory` — decisions, conventions, modules, and rules captured in past sessions. Filter with `--kind <decision|convention|module|rule|reference|project>`. (`.peaks/PROJECT.md` is a human-readable session timeline only.)
+Then display: `Peaks-Cli Skill: peaks-txt | Peaks-Cli Gate: startup | Next: <one short action>`. Update with `peaks skill presence:set peaks-txt --project <repo> --mode <mode> --gate <gate>` when gates change. When the role's work ends, run `peaks skill presence:clear --project <repo>`.
 
 ## Responsibilities
 
@@ -90,7 +96,7 @@ Each entry should include:
 - why it exists;
 - affected skills;
 - how future PRD/RD/UI/QA/SC/Solo workflows should apply it;
-- whether it is stable enough for `.claude/memory` extraction.
+- whether it is stable enough for `.peaks/memory` extraction.
 
 ## Project memory guidance
 
@@ -105,7 +111,7 @@ Stable memory body.
 <!-- peaks-memory:end -->
 ```
 
-The primary write target is the target project's `.claude/memory`. Use `peaks memory extract --project <path> --artifact <artifact> --apply` only after the user or active profile allows durable project memory writes.
+The primary write target is the target project's `.peaks/memory`. Use `peaks memory extract --project <path> --artifact <artifact> --apply` only after the user or active profile allows durable project memory writes.
 
 ## Matt Pocock skills integration
 
@@ -161,7 +167,7 @@ Use this sequence when TXT compresses an in-flight workflow into a portable, com
 ```bash
 # 0. Confirm TXT's own runbook integrity before compressing a handoff
 peaks skill runbook peaks-txt --json
-peaks skill presence:set peaks-txt               # show persistent skill presence every turn
+peaks skill presence:set peaks-txt --project <repo>  # show persistent skill presence every turn
 
 # 1. Inventory per-role artifacts already produced for the request
 peaks request list --project <repo> --json
@@ -180,7 +186,7 @@ peaks capabilities --json
 # 5. Memory extraction — dry-run by default, apply only when authorized
 peaks memory extract --project <repo> --artifact <artifact-path> --dry-run --json
 peaks memory extract --project <repo> --artifact <artifact-path> --apply --json
-peaks skill presence:clear                      # handoff capsule complete, remove presence indicator
+peaks skill presence:clear --project <repo>                      # handoff capsule complete, remove presence indicator
 ```
 
 The final `--apply` call requires explicit user or profile authorization. Without it, keep the capsule under `.peaks/<session-id>/txt/` and reference artifact paths from other roles instead of duplicating their content.

package/skills/peaks-ui/SKILL.md

@@ -12,10 +12,16 @@ Peaks-Cli UI handles experience, interaction, visual direction, and UI-specific
 Before any analysis or tool call, immediately run:
 
 ```bash
-peaks skill presence:set peaks-ui --mode <mode> --gate startup
+peaks skill presence:set peaks-ui --project <repo> --mode <mode> --gate startup
 ```
+Read persistent project memory via CLI (durable, LLM-authored memories):
 
-Then display: `Peaks-Cli Skill: peaks-ui | Peaks-Cli Gate: startup | Next: <one short action>`. Update with `peaks skill presence:set peaks-ui --mode <mode> --gate <gate>` when gates change. When the role's work ends, run `peaks skill presence:clear`.
+```bash
+peaks project memories --project <repo> --json
+```
+
+This returns durable memories from `.peaks/memory` — decisions, conventions, modules, and rules captured in past sessions. Filter with `--kind <decision|convention|module|rule|reference|project>`. (`.peaks/PROJECT.md` is a human-readable session timeline only.)
+Then display: `Peaks-Cli Skill: peaks-ui | Peaks-Cli Gate: startup | Next: <one short action>`. Update with `peaks skill presence:set peaks-ui --project <repo> --mode <mode> --gate <gate>` when gates change. When the role's work ends, run `peaks skill presence:clear --project <repo>`.
 
 ## Responsibilities
 
@@ -48,7 +54,7 @@ The default sequence the UI skill should execute. Skip steps that do not apply;
 ```bash
 # 0. confirm UI's own runbook integrity before driving any phase
 peaks skill runbook peaks-ui --json
-peaks skill presence:set peaks-ui               # show persistent skill presence every turn
+peaks skill presence:set peaks-ui --project <repo>  # show persistent skill presence every turn
 
 # 1. capture the UI request as a durable artifact tied to the same PRD request id
 peaks request init --role ui --id <request-id> --project <repo> --json
@@ -113,7 +119,7 @@ peaks mcp apply --capability playwright-mcp.browser-validation --yes --json
 # 7. hand off to RD / QA via the cross-linked request id
 peaks request list --project <repo> --json
 peaks request show <request-id> --role ui --project <repo> --json
-peaks skill presence:clear                      # handoff complete, remove presence indicator
+peaks skill presence:clear --project <repo>                      # handoff complete, remove presence indicator
 ```
 
 Handoff is blocked until the UI artifact's `state` reaches `direction-locked` or `handed-off`.