peaks-cli 1.0.27 → 1.0.28

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')

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

@@ -1,6 +1,15 @@
 import { loadProjectDashboard } from '../../services/dashboard/project-dashboard-service.js';
+import { generateProjectContext, loadOntology, readProjectContext, upsertDecision, upsertModule } from '../../services/memory/project-context-service.js';
 import { fail, ok } from '../../shared/result.js';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+function defined(obj) {
+    const result = {};
+    for (const [k, v] of Object.entries(obj)) {
+        if (v !== undefined)
+            result[k] = v;
+    }
+    return result;
+}
 export function registerProjectCommands(program, io) {
     const project = program.command('project').description('Aggregate Peaks state for a target project (read-only)');
     addJsonOption(project
@@ -39,4 +48,132 @@ 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;
+        }
+    });
+    // --- Ontology commands (structured project memory for LLM consumption) ---
+    const ontology = project.command('ontology').description('Query structured project memory (modules, decisions, conventions)');
+    addJsonOption(ontology
+        .command('show')
+        .description('Read the full ontology JSON for LLM consumption')
+        .requiredOption('--project <path>', 'target project root')).action((options) => {
+        try {
+            const onto = loadOntology(options.project);
+            if (onto === null) {
+                // Auto-generate if missing
+                const result = generateProjectContext(options.project);
+                printResult(io, ok('project.ontology', result.ontology), options.json);
+                return;
+            }
+            printResult(io, ok('project.ontology', onto), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('project.ontology', 'ONTOLOGY_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Check the project path']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(ontology
+        .command('module')
+        .description('Record or query a project module')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--id <id>', 'module id (kebab-case)')
+        .option('--path <path>', 'file path for the module')
+        .option('--risk <level>', 'risk level: low, medium, high')
+        .option('--summary <text>', 'brief module description')
+        .option('--session <id>', 'session id')
+        .option('--put', 'write/update the module entry')).action((options) => {
+        try {
+            if (options.put) {
+                if (!options.id || !options.path || !options.session) {
+                    printResult(io, fail('project.ontology.module', 'MISSING_FIELDS', '--id, --path, --session required with --put', {}, ['Provide all required fields']), options.json);
+                    process.exitCode = 1;
+                    return;
+                }
+                const risk = (options.risk === 'low' || options.risk === 'medium' || options.risk === 'high') ? options.risk : undefined;
+                const result = upsertModule(options.project, defined({
+                    id: options.id,
+                    path: options.path,
+                    session: options.session,
+                    risk,
+                    summary: options.summary
+                }));
+                printResult(io, ok('project.ontology.module', { modules: result.modules }), options.json);
+                return;
+            }
+            const onto = loadOntology(options.project) ?? generateProjectContext(options.project).ontology;
+            if (options.id) {
+                const mod = onto.modules.find((m) => m.id === options.id);
+                printResult(io, ok('project.ontology.module', mod ?? { notFound: true, id: options.id }), options.json);
+                return;
+            }
+            printResult(io, ok('project.ontology.module', { modules: onto.modules }), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('project.ontology.module', 'ONTOLOGY_MODULE_FAILED', getErrorMessage(error), {}, []), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(ontology
+        .command('decision')
+        .description('Record or query architectural decisions')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--id <id>', 'decision id')
+        .option('--what <text>', 'what was decided')
+        .option('--why <text>', 'rationale behind the decision')
+        .option('--scope <modules>', 'comma-separated module ids')
+        .option('--session <id>', 'session id')
+        .option('--date <date>', 'decision date')
+        .option('--put', 'write/update the decision')).action((options) => {
+        try {
+            if (options.put) {
+                if (!options.id || !options.what || !options.session || !options.date) {
+                    printResult(io, fail('project.ontology.decision', 'MISSING_FIELDS', '--id, --what, --session, --date required with --put', {}, []), options.json);
+                    process.exitCode = 1;
+                    return;
+                }
+                const result = upsertDecision(options.project, defined({
+                    id: options.id, what: options.what, why: options.why,
+                    scope: options.scope ? options.scope.split(',').map((s) => s.trim()).filter(Boolean) : [],
+                    session: options.session, date: options.date
+                }));
+                printResult(io, ok('project.ontology.decision', { decisions: result.decisions }), options.json);
+                return;
+            }
+            const onto = loadOntology(options.project) ?? generateProjectContext(options.project).ontology;
+            if (options.id) {
+                const dec = onto.decisions.find((d) => d.id === options.id);
+                printResult(io, ok('project.ontology.decision', dec ?? { notFound: true, id: options.id }), options.json);
+                return;
+            }
+            printResult(io, ok('project.ontology.decision', { decisions: onto.decisions }), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('project.ontology.decision', 'ONTOLOGY_DECISION_FAILED', getErrorMessage(error), {}, []), options.json);
+            process.exitCode = 1;
+        }
+    });
 }

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

@@ -0,0 +1,49 @@
+export type ProjectContextSection = {
+    heading: string;
+    body: string;
+};
+export type Module = {
+    id: string;
+    path: string;
+    risk?: 'low' | 'medium' | 'high';
+    sessions: string[];
+    summary?: string;
+};
+export type Decision = {
+    id: string;
+    what: string;
+    why?: string;
+    scope: string[];
+    session: string;
+    date: string;
+};
+export type Convention = {
+    id: string;
+    rule: string;
+    category: 'code-style' | 'architecture' | 'naming' | 'tooling' | 'other';
+    source: string;
+    date: string;
+};
+export type Ontology = {
+    version: 1;
+    updated: string;
+    project: string;
+    modules: Module[];
+    decisions: Decision[];
+    conventions: Convention[];
+};
+export declare function loadOntology(projectRoot: string): Ontology | null;
+export declare function saveOntology(projectRoot: string, onto: Ontology): void;
+export declare function upsertModule(projectRoot: string, mod: Omit<Module, 'sessions'> & {
+    session: string;
+}): Ontology;
+export declare function upsertDecision(projectRoot: string, dec: Decision): Ontology;
+export declare function upsertConvention(projectRoot: string, conv: Convention): Ontology;
+export declare function generateProjectContext(projectRoot: string): {
+    path: string;
+    content: string;
+    sessionCount: number;
+    ontology: Ontology;
+};
+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,449 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { listSessionMetas } from '../session/session-manager.js';
+const PROJECT_CONTEXT_FILE = '.peaks/PROJECT.md';
+const ONTOLOGY_FILE = '.peaks/ontology.json';
+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 extractArtifactSummary(filePath, sessionRoot) {
+    try {
+        const content = readFileSync(filePath, 'utf8');
+        const lines = content.split(/\r?\n/);
+        const firstHeading = lines.find((l) => /^#\s/.test(l))?.replace(/^#\s+/, '').trim();
+        const stateLine = lines.find((l) => /^\-\s*state:\s*/.test(l))?.trim();
+        const relPath = relative(sessionRoot, filePath).split(/[\\/]/).join('/');
+        const parts = [];
+        if (firstHeading)
+            parts.push(firstHeading);
+        if (stateLine)
+            parts.push(stateLine.replace(/^-\s*state:\s*/, ''));
+        if (parts.length === 0)
+            return `- \`${relPath}\``;
+        return `- \`${relPath}\` — ${parts.join(' | ')}`;
+    }
+    catch {
+        return null;
+    }
+}
+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 renderSessionBlock(meta, projectRoot) {
+    const title = meta.title ?? 'Untitled';
+    const date = meta.createdAt ? meta.createdAt.slice(0, 10) : '?';
+    const skill = meta.skill ?? '-';
+    const mode = meta.mode ?? '-';
+    let block = `### ${date} — ${title}\n`;
+    block += `- ${skill} (${mode})`;
+    const sessionRoot = join(projectRoot, '.peaks', meta.sessionId);
+    const summary = extractOneLineSummary(sessionRoot);
+    if (summary) {
+        block += ` — ${summary.slice(0, 120)}`;
+    }
+    block += '\n';
+    // Key artifact paths only
+    const artifacts = listMdFiles(sessionRoot, 3);
+    if (artifacts.length > 0) {
+        const paths = artifacts.slice(0, 8).map((f) => relative(sessionRoot, f).split(/[\\/]/).join('/'));
+        block += `  ${paths.join('  ')}\n`;
+    }
+    return block;
+}
+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;
+}
+// --- Ontology engine ---
+function emptyOntology(projectName) {
+    return {
+        version: 1,
+        updated: new Date().toISOString(),
+        project: projectName,
+        modules: [],
+        decisions: [],
+        conventions: []
+    };
+}
+function ontoPath(projectRoot) {
+    return join(projectRoot, ONTOLOGY_FILE);
+}
+export function loadOntology(projectRoot) {
+    const path = ontoPath(projectRoot);
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = JSON.parse(readFileSync(path, 'utf8'));
+        if (raw?.version === 1 && Array.isArray(raw.modules)) {
+            return raw;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+function slugify(text) {
+    return text.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'unknown';
+}
+function scanModulesFromArtifacts(sessionRoot, sessionId) {
+    const artifacts = listMdFiles(sessionRoot, 4);
+    const modules = [];
+    const seen = new Set();
+    for (const artifact of artifacts.slice(0, 10)) {
+        try {
+            const content = readFileSync(artifact, 'utf8');
+            // Extract file paths — non-capturing groups for extensions
+            const patterns = [
+                /\b(src\/[^\s)`\]}"]+\.(?:tsx?|jsx?|css|less|scss|vue|svelte))\b/g,
+                /\b(packages\/[^\s)`\]}"]+\.(?:tsx?|jsx?))\b/g
+            ];
+            for (const pattern of patterns) {
+                let m;
+                while ((m = pattern.exec(content)) !== null) {
+                    const filePath = m[1] ?? '';
+                    if (!filePath || filePath.length > 120 || filePath.length < 5)
+                        continue;
+                    const id = slugify(filePath.replace(/\.[^.]+$/, '').replace(/[\/\\]/g, '-'));
+                    if (seen.has(id))
+                        continue;
+                    seen.add(id);
+                    modules.push({ id, path: filePath });
+                    if (modules.length >= 30)
+                        break;
+                }
+                if (modules.length >= 30)
+                    break;
+            }
+        }
+        catch {
+            // skip unreadable
+        }
+    }
+    return modules;
+}
+function scanDecisionsFromArtifacts(sessionRoot, session) {
+    const artifacts = listMdFiles(sessionRoot, 4);
+    const decisions = [];
+    const date = session.createdAt ? session.createdAt.slice(0, 10) : new Date().toISOString().slice(0, 10);
+    for (const artifact of artifacts.slice(0, 10)) {
+        try {
+            const content = readFileSync(artifact, 'utf8');
+            // Look for decision markers: "- Decision: ..." or "Decision: ..." or "ADR: ..."
+            const decRegex = /^[\s-]*(?:decision|adr|决定|决策)\s*:\s*(.+?)$/gim;
+            let m;
+            while ((m = decRegex.exec(content)) !== null) {
+                const what = (m[1] ?? '').trim().slice(0, 200);
+                if (what.length < 5)
+                    continue;
+                const id = slugify(what.slice(0, 40));
+                // Collect scope from surrounding context (modules mentioned within 3 lines before/after)
+                const scope = [];
+                const lineIdx = content.slice(0, m.index).split('\n').length;
+                const lines = content.split('\n');
+                for (let i = Math.max(0, lineIdx - 3); i < Math.min(lines.length, lineIdx + 3); i++) {
+                    const line = lines[i] ?? '';
+                    const pathMatch = /src\/[^\s)`\]}"]+\.(tsx?|jsx?)/.exec(line);
+                    if (pathMatch?.[0])
+                        scope.push(pathMatch[0]);
+                }
+                decisions.push({ id, what, scope: [...new Set(scope)].slice(0, 5), session: session.sessionId, date });
+                if (decisions.length >= 10)
+                    break;
+            }
+        }
+        catch {
+            // skip unreadable
+        }
+    }
+    return decisions;
+}
+function scanConventionsFromArtifacts(sessionRoot, session) {
+    const artifacts = listMdFiles(sessionRoot, 4);
+    const conventions = [];
+    const date = session.createdAt ? session.createdAt.slice(0, 10) : new Date().toISOString().slice(0, 10);
+    for (const artifact of artifacts.slice(0, 10)) {
+        try {
+            const content = readFileSync(artifact, 'utf8');
+            const convRegex = /^[\s-]*(?:convention|约定|规范)\s*:\s*(.+?)$/gim;
+            let m;
+            while ((m = convRegex.exec(content)) !== null) {
+                const rule = (m[1] ?? '').trim().slice(0, 200);
+                if (rule.length < 5)
+                    continue;
+                const id = slugify(rule.slice(0, 40));
+                // Infer category from keywords
+                let category = 'other';
+                if (/class|function|interface|type|hook|component/i.test(rule))
+                    category = 'code-style';
+                else if (/service|layer|package|module|shared|extract/i.test(rule))
+                    category = 'architecture';
+                else if (/naming|命名|文件名|prefix|suffix/i.test(rule))
+                    category = 'naming';
+                else if (/tooling|lint|format|build|test/i.test(rule))
+                    category = 'tooling';
+                conventions.push({ id, rule, category, source: session.sessionId, date });
+                if (conventions.length >= 10)
+                    break;
+            }
+        }
+        catch {
+            // skip unreadable
+        }
+    }
+    return conventions;
+}
+function buildOntology(projectRoot) {
+    const name = projectName(projectRoot);
+    const existing = loadOntology(projectRoot);
+    const onto = existing ?? emptyOntology(name);
+    onto.updated = new Date().toISOString();
+    onto.project = name;
+    const metas = listSessionMetas(projectRoot);
+    const knownSessions = new Set(metas.map((m) => m.sessionId));
+    // Prune: remove modules/decisions/conventions from sessions that no longer exist
+    onto.modules = onto.modules.filter((m) => m.sessions.some((s) => knownSessions.has(s)));
+    onto.decisions = onto.decisions.filter((d) => knownSessions.has(d.session));
+    onto.conventions = onto.conventions.filter((c) => knownSessions.has(c.source));
+    // Merge: scan each session for new modules and decisions
+    const moduleMap = new Map();
+    for (const m of onto.modules)
+        moduleMap.set(m.id, m);
+    const decisionMap = new Map();
+    for (const d of onto.decisions)
+        decisionMap.set(d.id, d);
+    for (const meta of metas) {
+        const sessionRoot = join(projectRoot, '.peaks', meta.sessionId);
+        // Modules
+        const foundModules = scanModulesFromArtifacts(sessionRoot, meta.sessionId);
+        for (const fm of foundModules) {
+            if (moduleMap.has(fm.id)) {
+                const existing = moduleMap.get(fm.id);
+                if (!existing.sessions.includes(meta.sessionId)) {
+                    existing.sessions.push(meta.sessionId);
+                }
+            }
+            else {
+                moduleMap.set(fm.id, {
+                    id: fm.id,
+                    path: fm.path,
+                    sessions: [meta.sessionId]
+                });
+            }
+        }
+        // Decisions
+        const foundDecisions = scanDecisionsFromArtifacts(sessionRoot, meta);
+        for (const fd of foundDecisions) {
+            if (!decisionMap.has(fd.id)) {
+                decisionMap.set(fd.id, fd);
+            }
+        }
+        // Conventions
+        const foundConventions = scanConventionsFromArtifacts(sessionRoot, meta);
+        const convMap = new Map();
+        for (const c of onto.conventions)
+            convMap.set(c.id, c);
+        for (const fc of foundConventions) {
+            if (!convMap.has(fc.id)) {
+                convMap.set(fc.id, fc);
+            }
+        }
+        onto.conventions = [...convMap.values()].sort((a, b) => a.date.localeCompare(b.date));
+    }
+    // Dedup: remove shorter paths that are substring-matches of longer paths
+    const modules = [...moduleMap.values()];
+    const deduped = modules.filter((m) => {
+        return !modules.some((other) => other !== m && other.path.length > m.path.length && other.path.endsWith(m.path));
+    });
+    onto.modules = deduped.sort((a, b) => b.sessions.length - a.sessions.length);
+    onto.decisions = [...decisionMap.values()].sort((a, b) => b.date.localeCompare(a.date));
+    return onto;
+}
+export function saveOntology(projectRoot, onto) {
+    const peaksDir = join(projectRoot, '.peaks');
+    if (!existsSync(peaksDir))
+        mkdirSync(peaksDir, { recursive: true });
+    writeFileSync(ontoPath(projectRoot), JSON.stringify(onto, null, 2), 'utf8');
+}
+// Mutations for skills to call when they discover new facts
+export function upsertModule(projectRoot, mod) {
+    const onto = buildOntology(projectRoot);
+    const existing = onto.modules.find((m) => m.id === mod.id);
+    if (existing) {
+        if (!existing.sessions.includes(mod.session))
+            existing.sessions.push(mod.session);
+        if (mod.risk)
+            existing.risk = mod.risk;
+        if (mod.summary)
+            existing.summary = mod.summary;
+    }
+    else {
+        onto.modules.push({ ...mod, sessions: [mod.session] });
+    }
+    onto.updated = new Date().toISOString();
+    saveOntology(projectRoot, onto);
+    return onto;
+}
+export function upsertDecision(projectRoot, dec) {
+    const onto = buildOntology(projectRoot);
+    const idx = onto.decisions.findIndex((d) => d.id === dec.id);
+    if (idx >= 0) {
+        onto.decisions[idx] = dec;
+    }
+    else {
+        onto.decisions.push(dec);
+    }
+    onto.updated = new Date().toISOString();
+    saveOntology(projectRoot, onto);
+    return onto;
+}
+export function upsertConvention(projectRoot, conv) {
+    const onto = buildOntology(projectRoot);
+    const idx = onto.conventions.findIndex((c) => c.id === conv.id);
+    if (idx >= 0) {
+        onto.conventions[idx] = conv;
+    }
+    else {
+        onto.conventions.push(conv);
+    }
+    onto.updated = new Date().toISOString();
+    saveOntology(projectRoot, onto);
+    return onto;
+}
+// --- Context generator (unified: PROJECT.md + ontology.json) ---
+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');
+    // Build and save ontology alongside PROJECT.md
+    const ontology = buildOntology(projectRoot);
+    saveOntology(projectRoot, ontology);
+    return { path: contextPath, content, sessionCount: listSessionMetas(projectRoot).length, ontology };
+}
+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/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.0.28";

package/dist/src/shared/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-cli",
-  "version": "1.0.27",
+  "version": "1.0.28",
   "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 (structured ontology for LLM):
 
-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 ontology show --project <repo> --json
+```
+
+This returns `.peaks/ontology.json` — structured modules, decisions, and conventions from past sessions. (`.peaks/PROJECT.md` is a human-readable 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 (structured ontology for LLM):
 
-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 ontology show --project <repo> --json
+```
+
+This returns `.peaks/ontology.json` — structured modules, decisions, and conventions from past sessions. (`.peaks/PROJECT.md` is a human-readable 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 (structured ontology for LLM):
 
-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 ontology show --project <repo> --json
+```
+
+This returns `.peaks/ontology.json` — structured modules, decisions, and conventions from past sessions. (`.peaks/PROJECT.md` is a human-readable 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 (structured ontology for LLM):
 
-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 ontology show --project <repo> --json
+```
+
+This returns `.peaks/ontology.json` — structured modules, decisions, and conventions from past sessions. (`.peaks/PROJECT.md` is a human-readable 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
 
@@ -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,29 @@ 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 (structured ontology for LLM)
+
+Before planning any work, read the project's persistent memory — structured data that survives across sessions:
+
+```bash
+peaks project ontology show --project <repo> --json
+```
+
+This returns `.peaks/ontology.json` containing:
+- **modules** — code areas touched, with risk levels and which sessions modified them
+- **decisions** — architectural choices, why they were made, what modules they affect
+- **conventions** — discovered project patterns (code style, naming, tooling)
+
+Use this to understand what exists, what was decided, and what to avoid re-litigating. The ontology is auto-updated on `peaks skill presence:clear`.
+
+`.peaks/PROJECT.md` is a human-readable timeline only — do NOT use it for LLM context.
 
 ### Peaks-Cli Step 2.5: Set session title
 
@@ -579,7 +596,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 +623,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 +798,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 (structured ontology for LLM):
 
-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 ontology show --project <repo> --json
+```
+
+This returns `.peaks/ontology.json` — structured modules, decisions, and conventions from past sessions. (`.peaks/PROJECT.md` is a human-readable 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
 
@@ -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 (structured ontology for LLM):
 
-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 ontology show --project <repo> --json
+```
+
+This returns `.peaks/ontology.json` — structured modules, decisions, and conventions from past sessions. (`.peaks/PROJECT.md` is a human-readable 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`.