peaks-cli 1.2.2 → 1.2.4

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

@@ -275,10 +275,14 @@ export function registerCoreAndArtifactCommands(program, io) {
         .requiredOption('--project <path>', 'target project root')
         .requiredOption('--artifact <path...>', 'skill artifact paths inside the project')
         .option('--dry-run', 'preview writes without changing files')
-        .option('--apply', 'write extracted memories into project .peaks/memory (default behavior)')).action((options) => {
+        .option('--apply', 'write extracted memories into project .peaks/memory')).action((options) => {
+        if (options.dryRun === true && options.apply === true) {
+            printResult(io, fail('memory.extract', 'INVALID_MEMORY_EXTRACT_FLAGS', 'Use either --dry-run or --apply, not both', {}, ['Run without --apply to preview writes, or pass --apply to write memories']), options.json);
+            process.exitCode = 1;
+            return;
+        }
         try {
-            const shouldApply = options.dryRun !== true;
-            const result = executeProjectMemoryExtract({ projectRoot: options.project, artifactPaths: options.artifact, apply: shouldApply });
+            const result = executeProjectMemoryExtract({ projectRoot: options.project, artifactPaths: options.artifact, apply: options.apply === true });
             printResult(io, ok('memory.extract', summarizeProjectMemoryExtractResult(result)), options.json);
         }
         catch (error) {
@@ -292,10 +296,14 @@ export function registerCoreAndArtifactCommands(program, io) {
         .requiredOption('--project <path>', 'target project root')
         .requiredOption('--workspace <path>', 'artifact workspace path')
         .option('--dry-run', 'preview copies without changing files')
-        .option('--apply', 'copy project .peaks/memory into artifact workspace backup (default behavior)')).action((options) => {
+        .option('--apply', 'copy project .peaks/memory into artifact workspace backup')).action((options) => {
+        if (options.dryRun === true && options.apply === true) {
+            printResult(io, fail('memory.sync', 'INVALID_MEMORY_SYNC_FLAGS', 'Use either --dry-run or --apply, not both', {}, ['Run without --apply to preview copies, or pass --apply to back up memories']), options.json);
+            process.exitCode = 1;
+            return;
+        }
         try {
-            const shouldApply = options.dryRun !== true;
-            const result = executeProjectMemoryBackup({ projectRoot: options.project, artifactWorkspacePath: options.workspace, apply: shouldApply });
+            const result = executeProjectMemoryBackup({ projectRoot: options.project, artifactWorkspacePath: options.workspace, apply: options.apply === true });
             printResult(io, ok('memory.sync', summarizeProjectMemoryBackupResult(result)), options.json);
         }
         catch (error) {

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

@@ -1,6 +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 { extractSessionMemories, readMemoryIndex, 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) {
@@ -68,6 +68,56 @@ export function registerProjectCommands(program, io) {
             process.exitCode = 1;
         }
     });
+    // --- Extract memories from a session's artifacts into .peaks/memory ---
+    addJsonOption(project
+        .command('memories:extract')
+        .description('Scan a session artifact directory and extract <!-- peaks-memory:start --> blocks into .peaks/memory/')
+        .requiredOption('--session-id <id>', 'session id (e.g. 2026-05-29-session-89ff35)')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--dry-run', 'preview writes without changing files', true)
+        .option('--apply', 'write extracted memories into .peaks/memory/')).action((options) => {
+        if (options.dryRun === true && options.apply === true) {
+            printResult(io, fail('project.memories:extract', 'INVALID_MEMORY_EXTRACT_FLAGS', 'Use either --dry-run or --apply, not both', { sessionId: options.sessionId, projectRoot: options.project }, ['Run without --apply to preview writes, or pass --apply to write memories']), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        try {
+            const result = extractSessionMemories({
+                projectRoot: options.project,
+                sessionId: options.sessionId,
+                apply: options.apply === true
+            });
+            printResult(io, ok('project.memories:extract', {
+                scannedFiles: result.scannedFiles,
+                extractedCount: result.extractedCount,
+                writtenFiles: result.writtenFiles,
+                memoryDir: result.primaryMemoryDir,
+                indexUpdated: result.updatedIndex
+            }), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('project.memories:extract', 'MEMORY_EXTRACT_FAILED', getErrorMessage(error), { sessionId: options.sessionId, projectRoot: options.project }, ['Check the session-id and project path']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    // --- Read memory index (lightweight, always-safe to load) ---
+    addJsonOption(project
+        .command('memory-index')
+        .description('Read the memory index — lightweight hot/warm分层 view of all project memories')
+        .requiredOption('--project <path>', 'target project root')).action((options) => {
+        try {
+            const index = readMemoryIndex(options.project);
+            if (!index) {
+                printResult(io, ok('project.memory-index', { exists: false, message: 'No memory index found. Run `peaks project memories:extract` first.' }), options.json);
+                return;
+            }
+            printResult(io, ok('project.memory-index', { exists: true, index }), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('project.memory-index', 'MEMORY_INDEX_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Check the project path and .peaks/memory directory']), options.json);
+            process.exitCode = 1;
+        }
+    });
     // --- Structured project memory (durable, LLM-authored, stored under .peaks/memory) ---
     addJsonOption(project
         .command('memories')

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

@@ -105,8 +105,8 @@ export function registerSopCommands(program, io) {
     });
     addJsonOption(sop
         .command('registry')
-        .description('List registered SOPs and gates (global; --project merges in the repo layer)')
-        .option('--project <path>', 'also include and prefer the repo layer (<path>/.peaks/sops)')).action(async (options) => {
+        .description('List registered SOPs and gates (global; merges in the cwd project layer by default)')
+        .option('--project <path>', 'also include and prefer the repo layer (<path>/.peaks/sops) (default: current directory)', '.')).action(async (options) => {
         try {
             const registry = await readRegistry(options.project);
             printResult(io, ok('sop.registry', registry), options.json);

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

@@ -74,6 +74,36 @@ export type ProjectMemoryReadResult = {
     byKind: Record<ProjectMemoryKind, StoredProjectMemory[]>;
     memories: StoredProjectMemory[];
 };
+export type MemoryIndexEntry = {
+    name: string;
+    kind: ProjectMemoryKind;
+    description: string;
+    sourcePath: string;
+    sourceArtifact: string | null;
+    updatedAt: string;
+};
+export type MemoryIndex = {
+    version: 1;
+    updatedAt: string;
+    hot: Record<ProjectMemoryKind, MemoryIndexEntry[]>;
+    warm: Record<ProjectMemoryKind, MemoryIndexEntry[]>;
+};
+export type ExtractSessionMemoriesOptions = {
+    projectRoot: string;
+    sessionId: string;
+    apply?: boolean;
+};
+export type ExtractSessionMemoriesResult = {
+    apply: boolean;
+    projectRoot: string;
+    sessionId: string;
+    primaryMemoryDir: string;
+    memoryIndexPath: string;
+    scannedFiles: number;
+    extractedCount: number;
+    writtenFiles: string[];
+    updatedIndex: boolean;
+};
 type ExtractPlanOptions = {
     projectRoot: string;
     artifactPaths: string[];
@@ -84,6 +114,8 @@ type BackupPlanOptions = {
     artifactWorkspacePath: string;
     apply?: boolean;
 };
+export declare function readMemoryIndex(projectRoot: string): MemoryIndex | null;
+export declare function extractSessionMemories(options: ExtractSessionMemoriesOptions): ExtractSessionMemoriesResult;
 export declare function extractStableProjectMemories(content: string, sourceArtifact: string): ExtractedProjectMemory[];
 export declare function createProjectMemoryExtractPlan(options: ExtractPlanOptions): ProjectMemoryExtractPlan;
 export declare function executeProjectMemoryExtract(options: ExtractPlanOptions): ProjectMemoryExtractResult;

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

@@ -1,7 +1,12 @@
-import { closeSync, constants, copyFileSync, existsSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { closeSync, constants, copyFileSync, existsSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, realpathSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
 import { isInsidePath, isWindowsAbsolutePath, normalizePath, resolveInputPath, stablePath, stableRealPath } from '../../shared/path-utils.js';
 import { containsSensitiveConfigValue, isSensitiveConfigPath } from '../config/config-service.js';
+// Hot kinds: full body kept in index for always-available context
+const HOT_KINDS = new Set(['feedback', 'decision', 'rule', 'convention', 'module']);
+// ---------------------------------------------------------------------------
+// Internal helpers (kept from original, sorted by dependency order)
+// ---------------------------------------------------------------------------
 const START_MARKER = '<!-- peaks-memory:start -->';
 const END_MARKER = '<!-- peaks-memory:end -->';
 const VALID_MEMORY_KINDS = new Set(['project', 'rule', 'decision', 'reference', 'feedback', 'convention', 'module']);
@@ -171,47 +176,25 @@ function parseStoredMemoryFile(content, filePath) {
         filePath
     };
 }
-function summarizeExtractResult(result) {
-    return {
-        apply: result.apply,
-        projectRoot: result.projectRoot,
-        primaryMemoryDir: result.primaryMemoryDir,
-        backupPolicy: result.backupPolicy,
-        extractedCount: result.extractedMemories.length,
-        plannedWrites: result.plannedWrites.map((write) => ({
-            filePath: write.filePath,
-            title: write.memory.title,
-            kind: write.memory.kind,
-            sourceArtifact: write.memory.sourceArtifact
-        })),
-        writtenFiles: result.writtenFiles
-    };
-}
-function summarizeBackupResult(result) {
-    return {
-        apply: result.apply,
-        projectRoot: result.projectRoot,
-        artifactWorkspacePath: result.artifactWorkspacePath,
-        primaryMemoryDir: result.primaryMemoryDir,
-        backupMemoryDir: result.backupMemoryDir,
-        plannedCopies: result.plannedCopies,
-        copiedFiles: result.copiedFiles
-    };
-}
-function listMarkdownFiles(dirPath) {
+function listMarkdownFiles(dirPath, options = {}) {
     if (!existsSync(dirPath))
         return [];
+    const { maxDepth = Infinity, skipDotfiles = true } = options;
     const files = [];
-    const stack = [dirPath];
+    const stack = [{ path: dirPath, depth: 0 }];
     while (stack.length > 0) {
-        const currentDir = stack.pop();
-        for (const entry of readdirSync(currentDir, { withFileTypes: true }).sort((left, right) => left.name.localeCompare(right.name))) {
-            const entryPath = join(currentDir, entry.name);
+        const frame = stack.pop();
+        if (frame.depth > maxDepth)
+            continue;
+        for (const entry of readdirSync(frame.path, { withFileTypes: true }).sort((left, right) => left.name.localeCompare(right.name))) {
+            if (skipDotfiles && entry.name.startsWith('.'))
+                continue;
+            const entryPath = join(frame.path, entry.name);
             if (entry.isSymbolicLink()) {
                 continue;
             }
             if (entry.isDirectory()) {
-                stack.push(entryPath);
+                stack.push({ path: entryPath, depth: frame.depth + 1 });
                 continue;
             }
             if (entry.isFile() && entry.name.endsWith('.md')) {
@@ -221,6 +204,255 @@ function listMarkdownFiles(dirPath) {
     }
     return files.sort((left, right) => left.localeCompare(right));
 }
+// ---------------------------------------------------------------------------
+// Description summarization (deterministic, no LLM call)
+// ---------------------------------------------------------------------------
+function summarizeMemoryBody(body) {
+    const cleaned = body
+        .replace(/^#{1,6}\s+/gm, '')
+        .replace(/`{1,3}[^`]*`{1,3}/g, '')
+        .replace(/^\s*[-*+]\s+/gm, '')
+        .replace(/\n+/g, ' ')
+        .trim();
+    const sentences = cleaned.split(/(?<=[.!?])\s+/).filter((s) => s.length > 20 && !/^\[.+\]$/.test(s));
+    if (sentences.length === 0) {
+        return cleaned.slice(0, 120) || 'Project memory';
+    }
+    const first = sentences[0];
+    if (first.length <= 120) {
+        return first;
+    }
+    return first.slice(0, 117) + '...';
+}
+// ---------------------------------------------------------------------------
+// Session memory extraction (new extract path)
+// ---------------------------------------------------------------------------
+function assertSafeSessionDir(projectRoot, sessionId) {
+    const normalizedRoot = normalizeRoot(projectRoot);
+    const realRoot = normalizeRealRoot(projectRoot);
+    const sessionDir = join(normalizedRoot, '.peaks', sessionId);
+    if (!existsSync(sessionDir)) {
+        // Distinguish "not found" (caller will treat as no-op) from "escapes project
+        // root" (caller must surface a hard error). We probe by checking whether the
+        // joined path, after realpath, would still be inside the project root.
+        if (isAbsolute(join(normalizedRoot, '.peaks', sessionId))) {
+            const realJoined = safeRealpath(join(normalizedRoot, '.peaks', sessionId));
+            if (realJoined && !isInsidePath(realJoined, realRoot)) {
+                throw new Error('Session directory must stay inside the project root');
+            }
+        }
+        throw new Error('SESSION_DIR_NOT_FOUND');
+    }
+    const stats = lstatSync(sessionDir);
+    if (stats.isSymbolicLink()) {
+        throw new Error('Session directory must stay inside the project root');
+    }
+    const realSessionDir = realpathSync(sessionDir);
+    if (!isInsidePath(realSessionDir, realRoot)) {
+        throw new Error('Session directory must stay inside the project root');
+    }
+    return sessionDir;
+}
+function safeRealpath(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return null;
+    }
+}
+function readMemoryFileMtime(filePath) {
+    try {
+        return statSync(filePath).mtime.toISOString().slice(0, 10);
+    }
+    catch {
+        return new Date().toISOString().slice(0, 10);
+    }
+}
+function readStoredMemoryNames(memoryDir) {
+    const names = new Set();
+    for (const filePath of listMarkdownFiles(memoryDir)) {
+        const parsed = parseStoredMemoryFile(readFileSync(filePath, 'utf8'), filePath);
+        if (parsed)
+            names.add(parsed.name);
+    }
+    return names;
+}
+function generateMemoryIndexFile(projectRoot, memoryDir, indexPath) {
+    const memories = readProjectMemories(projectRoot);
+    const hot = {
+        feedback: [], decision: [], rule: [], convention: [], module: []
+    };
+    const warm = {
+        project: [], reference: []
+    };
+    for (const memory of memories.memories) {
+        const entry = {
+            name: memory.name,
+            kind: memory.kind,
+            description: memory.body ? summarizeMemoryBody(memory.body) : memory.title,
+            sourcePath: memory.filePath,
+            sourceArtifact: memory.sourceArtifact,
+            updatedAt: readMemoryFileMtime(memory.filePath)
+        };
+        if (HOT_KINDS.has(memory.kind)) {
+            hot[memory.kind].push(entry);
+        }
+        else {
+            warm[memory.kind].push(entry);
+        }
+    }
+    for (const kind of [...Object.keys(hot), ...Object.keys(warm)]) {
+        const arr = hot[kind] ?? warm[kind];
+        if (arr)
+            arr.sort((a, b) => a.name.localeCompare(b.name));
+    }
+    const index = {
+        version: 1,
+        updatedAt: new Date().toISOString(),
+        hot: hot,
+        warm: warm
+    };
+    const fd = openSync(indexPath, constants.O_WRONLY | constants.O_CREAT | constants.O_TRUNC, 0o644);
+    try {
+        writeFileSync(fd, JSON.stringify(index, null, 2), 'utf8');
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function readExistingIndex(indexPath) {
+    if (!existsSync(indexPath))
+        return null;
+    try {
+        const raw = readFileSync(indexPath, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (parsed.version === 1)
+            return parsed;
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+export function readMemoryIndex(projectRoot) {
+    const normalizedRoot = normalizeRoot(projectRoot);
+    const memoryDir = assertSafeProjectMemoryDir(normalizedRoot);
+    const indexPath = join(memoryDir, 'index.json');
+    if (existsSync(memoryDir)) {
+        const files = listMarkdownFiles(memoryDir);
+        if (files.length > 0) {
+            try {
+                generateMemoryIndexFile(normalizedRoot, memoryDir, indexPath);
+            }
+            catch {
+                // fall through to read existing
+            }
+        }
+    }
+    return readExistingIndex(indexPath);
+}
+export function extractSessionMemories(options) {
+    const projectRoot = normalizeRoot(options.projectRoot);
+    const apply = options.apply ?? false;
+    const primaryMemoryDir = assertSafeProjectMemoryDir(projectRoot);
+    const memoryIndexPath = join(primaryMemoryDir, 'index.json');
+    // Resolve sessionDir through realpath + inside-project guard so a hostile
+    // sessionId (`..`, abs path, symlink chain) cannot walk the scanner outside
+    // the project root. A sentinel "SESSION_DIR_NOT_FOUND" distinguishes a
+    // benign miss from an escape attempt.
+    let sessionDir;
+    try {
+        sessionDir = assertSafeSessionDir(projectRoot, options.sessionId);
+    }
+    catch (error) {
+        if (error instanceof Error && error.message === 'SESSION_DIR_NOT_FOUND') {
+            return {
+                apply,
+                projectRoot,
+                sessionId: options.sessionId,
+                primaryMemoryDir,
+                memoryIndexPath,
+                scannedFiles: 0,
+                extractedCount: 0,
+                writtenFiles: [],
+                updatedIndex: false
+            };
+        }
+        throw error;
+    }
+    const scannedFiles = listMarkdownFiles(sessionDir, { maxDepth: 6, skipDotfiles: true });
+    const allExtracted = [];
+    for (const filePath of scannedFiles) {
+        try {
+            const content = readFileSync(filePath, 'utf8');
+            const relativePath = relative(projectRoot, filePath).replaceAll('\\', '/');
+            const extracted = extractStableProjectMemories(content, relativePath);
+            allExtracted.push(...extracted);
+        }
+        catch {
+            // skip unreadable files
+        }
+    }
+    if (allExtracted.length === 0) {
+        return {
+            apply,
+            projectRoot,
+            sessionId: options.sessionId,
+            primaryMemoryDir,
+            memoryIndexPath,
+            scannedFiles: scannedFiles.length,
+            extractedCount: 0,
+            writtenFiles: [],
+            updatedIndex: false
+        };
+    }
+    const slugCounts = new Map();
+    for (const memory of allExtracted) {
+        const slug = slugify(memory.title);
+        slugCounts.set(slug, (slugCounts.get(slug) ?? 0) + 1);
+    }
+    const duplicateTitles = [...slugCounts.entries()].filter(([, count]) => count > 1).map(([slug]) => slug);
+    if (duplicateTitles.length > 0) {
+        throw new Error(`Duplicate memory titles are not allowed: ${duplicateTitles.join(', ')}`);
+    }
+    // Idempotency: pre-read existing memory names so a re-run of the same
+    // session does not throw EEXIST. `writtenFiles` reports only the new
+    // writes so callers can still tell what the run actually produced.
+    const existingNames = apply ? readStoredMemoryNames(primaryMemoryDir) : new Set();
+    const writtenFiles = [];
+    if (apply) {
+        mkdirSync(primaryMemoryDir, { recursive: true });
+        for (const memory of allExtracted) {
+            const slug = slugify(memory.title);
+            if (existingNames.has(slug))
+                continue;
+            const targetPath = join(primaryMemoryDir, `${slug}.md`);
+            const safePath = resolveInputPath(targetPath);
+            const stableSafePath = stablePath(safePath);
+            if (!isInsidePath(stableSafePath, stableRealPath(primaryMemoryDir))) {
+                throw new Error('Project memory write target must stay inside the project memory directory');
+            }
+            writeNewFile(safePath, renderMemoryFile(memory));
+            writtenFiles.push(safePath);
+        }
+        generateMemoryIndexFile(projectRoot, primaryMemoryDir, memoryIndexPath);
+    }
+    return {
+        apply,
+        projectRoot,
+        sessionId: options.sessionId,
+        primaryMemoryDir,
+        memoryIndexPath,
+        scannedFiles: scannedFiles.length,
+        extractedCount: allExtracted.length,
+        writtenFiles,
+        updatedIndex: apply && writtenFiles.length > 0
+    };
+}
+// ---------------------------------------------------------------------------
+// Old extract path (kept for core-artifact-commands.ts)
+// ---------------------------------------------------------------------------
 export function extractStableProjectMemories(content, sourceArtifact) {
     const memories = [];
     let searchStart = 0;
@@ -241,6 +473,33 @@ export function extractStableProjectMemories(content, sourceArtifact) {
     }
     return memories.sort((left, right) => slugify(left.title).localeCompare(slugify(right.title)));
 }
+function summarizeExtractResult(result) {
+    return {
+        apply: result.apply,
+        projectRoot: result.projectRoot,
+        primaryMemoryDir: result.primaryMemoryDir,
+        backupPolicy: result.backupPolicy,
+        extractedCount: result.extractedMemories.length,
+        plannedWrites: result.plannedWrites.map((write) => ({
+            filePath: write.filePath,
+            title: write.memory.title,
+            kind: write.memory.kind,
+            sourceArtifact: write.memory.sourceArtifact
+        })),
+        writtenFiles: result.writtenFiles
+    };
+}
+function summarizeBackupResult(result) {
+    return {
+        apply: result.apply,
+        projectRoot: result.projectRoot,
+        artifactWorkspacePath: result.artifactWorkspacePath,
+        primaryMemoryDir: result.primaryMemoryDir,
+        backupMemoryDir: result.backupMemoryDir,
+        plannedCopies: result.plannedCopies,
+        copiedFiles: result.copiedFiles
+    };
+}
 export function createProjectMemoryExtractPlan(options) {
     const projectRoot = normalizeRoot(options.projectRoot);
     const primaryMemoryDir = assertSafeProjectMemoryDir(projectRoot);

package/dist/src/services/sop/sop-check-service.d.ts

@@ -20,6 +20,22 @@ export declare class SopCheckError extends Error {
     readonly code: string;
     constructor(code: string, message: string);
 }
+/**
+ * Strip meta content from a string for grep evaluation. The grep gate's
+ * `stripMeta:true` opt-in lets content-publishing SOPs avoid the "literal-word
+ * trap" (the author discussing the gate's pattern in the post would itself
+ * trigger the gate). Three classes of meta are removed:
+ *
+ *  - HTML comments: `<!-- ... -->`
+ *  - Fenced code blocks: 3+ backticks on their own line, opening through the
+ *    matching close on its own line (or end of string)
+ *  - C-style block comments: `/* ... *​/`
+ *
+ * Conservative fail-safe: unclosed fences and unclosed block comments are left
+ * as-is (no partial strip), so the regex still matches any embedded pattern
+ * rather than silently hiding it. This helper is pure; no side effects.
+ */
+export declare function stripMetaForGrep(content: string): string;
 export type EvaluateGateOptions = {
     allowCommands?: boolean;
     commandTimeoutMs?: number;

package/dist/src/services/sop/sop-check-service.js

@@ -40,7 +40,7 @@ function evaluateFileExists(projectRoot, path) {
     }
     return existsSync(resolved) ? { result: 'pass' } : { result: 'fail', reason: `file "${path}" does not exist` };
 }
-function evaluateGrep(projectRoot, file, pattern, absent) {
+function evaluateGrep(projectRoot, file, pattern, absent, stripMeta) {
     const resolved = resolveInsideProject(projectRoot, file);
     if (resolved === null) {
         return { result: 'blocked', reason: `file "${file}" escapes the project root` };
@@ -62,6 +62,9 @@ function evaluateGrep(projectRoot, file, pattern, absent) {
     catch {
         return { result: 'blocked', reason: `file "${file}" cannot be read` };
     }
+    if (stripMeta === true) {
+        content = stripMetaForGrep(content);
+    }
     const found = regex.test(content);
     // absent gate: pass when the pattern is NOT present ("must not contain X").
     const pass = absent ? !found : found;
@@ -72,6 +75,36 @@ function evaluateGrep(projectRoot, file, pattern, absent) {
         ? { result: 'fail', reason: `pattern "${pattern}" must be absent but was found in "${file}"` }
         : { result: 'fail', reason: `pattern "${pattern}" not found in "${file}"` };
 }
+/**
+ * Strip meta content from a string for grep evaluation. The grep gate's
+ * `stripMeta:true` opt-in lets content-publishing SOPs avoid the "literal-word
+ * trap" (the author discussing the gate's pattern in the post would itself
+ * trigger the gate). Three classes of meta are removed:
+ *
+ *  - HTML comments: `<!-- ... -->`
+ *  - Fenced code blocks: 3+ backticks on their own line, opening through the
+ *    matching close on its own line (or end of string)
+ *  - C-style block comments: `/* ... *​/`
+ *
+ * Conservative fail-safe: unclosed fences and unclosed block comments are left
+ * as-is (no partial strip), so the regex still matches any embedded pattern
+ * rather than silently hiding it. This helper is pure; no side effects.
+ */
+export function stripMetaForGrep(content) {
+    // HTML comments: from `<!--` through the next `-->`. Multi-line.
+    let result = content.replace(/<!--[\s\S]*?-->/g, '');
+    // C-style block comments: from `/*` through the next `*/`. Multi-line. Run
+    // before the fence regex because code comments often appear inside code
+    // blocks and we want them gone from the rendered view too.
+    result = result.replace(/\/\*[\s\S]*?\*\//g, '');
+    // Fenced code blocks: `^````<lang?>\\n...<closing line>`. Match only if a
+    // closing `^```` line exists within the content; unclosed fences fall
+    // through un-stripped (the unclosed-`\n?$` branch from the previous version
+    // over-matched by eating the rest of the file, which silently hides
+    // embedded patterns; we prefer the conservative fail-safe).
+    result = result.replace(/^```[^\n]*\n[\s\S]*?\n```[^\n]*\n?/gm, '');
+    return result;
+}
 function evaluateCommand(projectRoot, run, expectExitZero, allowCommands, timeoutMs) {
     if (!allowCommands) {
         return { result: 'blocked', reason: 'command checks require --allow-commands' };
@@ -110,7 +143,7 @@ function evaluateCheck(projectRoot, check, allowCommands, timeoutMs) {
         case 'file-exists':
             return evaluateFileExists(projectRoot, check.path);
         case 'grep':
-            return evaluateGrep(projectRoot, check.file, check.pattern, check.absent === true);
+            return evaluateGrep(projectRoot, check.file, check.pattern, check.absent === true, check.stripMeta === true);
         case 'command':
             return evaluateCommand(projectRoot, check.run, check.expectExitZero !== false, allowCommands, timeoutMs);
         default:

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

@@ -29,6 +29,14 @@ export type SopLintResult = {
     gateCount: number;
     gateIds: string[];
     findings: SopLintFinding[];
+    /**
+     * Non-blocking hints surfaced alongside the lint verdict. Currently used to
+     * flag gates that declared `stripMeta: true` so authors can confirm the
+     * opt-in. Empty array for manifests that do not opt in to any new behavior;
+     * this is a stable, machine-readable field distinct from `findings` (which
+     * are errors that block lint).
+     */
+    warnings: string[];
 };
 export type SopLintOptions = {
     id: string;

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

@@ -164,13 +164,14 @@ export async function lintSop(options) {
         return null;
     }
     const findings = [];
+    const warnings = [];
     let manifest = null;
     try {
         manifest = JSON.parse(await readFile(manifestPath, 'utf8'));
     }
     catch (error) {
         pushError(findings, 'INVALID_JSON', `Manifest is not valid JSON: ${error instanceof Error ? error.message : 'parse error'}`);
-        return { ok: false, id: options.id, manifestPath, gateCount: 0, gateIds: [], findings };
+        return { ok: false, id: options.id, manifestPath, gateCount: 0, gateIds: [], findings, warnings };
     }
     if (typeof manifest.id !== 'string' || !SOP_ID_PATTERN.test(manifest.id)) {
         pushError(findings, 'INVALID_ID', `Manifest id "${String(manifest.id)}" is invalid (expected lowercase kebab)`);
@@ -200,12 +201,22 @@ export async function lintSop(options) {
     gates.forEach((gate, index) => lintGate(gate, index, phaseSet, seenGateIds, options.allowCommands === true, findings));
     const guards = Array.isArray(manifest.guards) ? manifest.guards : [];
     guards.forEach((guard, index) => lintGuard(guard, index, phaseSet, findings));
+    // Non-blocking hints: surface `stripMeta: true` opt-ins so the author can
+    // confirm the meta-strip behavior. Distinct from `findings` (which block
+    // lint). Per PRD 006 AC6, only gates that declared `stripMeta` warn.
+    for (const gate of gates) {
+        if (gate?.check?.type === 'grep' && gate.check.stripMeta === true) {
+            const label = typeof gate.id === 'string' && gate.id.length > 0 ? gate.id : '?';
+            warnings.push(`Gate "${label}" declares stripMeta: true — meta content (HTML comments / fenced code / block comments) is excluded from grep evaluation`);
+        }
+    }
     return {
         ok: findings.every((finding) => finding.severity !== 'error'),
         id: options.id,
         manifestPath,
         gateCount: gates.length,
         gateIds: [...seenGateIds],
-        findings
+        findings,
+        warnings
     };
 }

package/dist/src/services/sop/sop-types.d.ts

@@ -16,12 +16,19 @@ export type SopGateCheck = {
  * to invert — pass when the pattern is NOT found. `absent` expresses "must not
  * contain X" (e.g. no leftover TODO) as a pure-text check, with no command gate
  * and no `--allow-commands` escalation.
+ *
+ * Set `stripMeta: true` to evaluate the regex on a meta-stripped copy of the
+ * file (HTML comments + fenced code blocks + `/* … *​/` block comments
+ * removed). This lets content-publishing SOPs avoid the "literal-word trap"
+ * where the author discussing the gate's behavior in the post would itself
+ * trigger the gate. Default `false` preserves byte-identical behavior.
  */
  | {
     type: 'grep';
     file: string;
     pattern: string;
     absent?: boolean;
+    stripMeta?: boolean;
 } | {
     type: 'command';
     run: string[];

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

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

package/dist/src/shared/version.js

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

package/package.json

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

package/skills/peaks-qa/SKILL.md

@@ -147,6 +147,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 project memories:extract --session-id <session-id> --project <repo> --json  # extract durable memories
 peaks skill presence:clear --project <repo>                      # QA complete, remove presence indicator
 ```
 

package/skills/peaks-rd/SKILL.md

@@ -89,6 +89,20 @@ peaks codegraph affected --project <repo> <changed-files...> --json
 #   - component library (antd, MUI, shadcn, etc.) and version
 #   - CSS solution (Less, Sass, TailwindCSS, CSS-in-JS) and conflicts
 #   - state management, routing, data fetching libraries
+#
+# After writing project-scan, embed durable memory markers for stable project facts.
+# Append one <!-- peaks-memory:start --> block per fact at the end of project-scan.md:
+#
+#   <!-- peaks-memory:start -->
+#   title: <component library>
+#   kind: module
+#   ---
+#   <Library> <version> — detected from package.json and source imports.
+#   <!-- peaks-memory:end -->
+#
+# Embed markers for: component library, CSS solution, build tool, state management,
+# routing, data fetching, and any legacy constraints. These facts are session-invariant
+# and valuable for future sessions. Do NOT embed secrets, credentials, or transient state.
 
 # 4.2 component library detection — verify against package.json, not assumptions
 # WRONG: "looks like a React project, let me use shadcn/ui"
@@ -151,6 +165,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 project memories:extract --session-id <session-id> --project <repo> --json  # extract durable memories
 peaks skill presence:clear --project <repo>                      # handoff complete, remove presence indicator
 ```
 

package/skills/peaks-solo/SKILL.md

@@ -761,8 +761,11 @@ peaks sc boundary --slice-id <rid> --artifact <artifact> --code <file> --json
 peaks openspec validate <cid> --project <repo> --json
 peaks openspec archive <cid> --project <repo> --apply --json
 
-# 10. Peaks-Cli TXT handoff
-peaks memory extract --project <repo> --artifact <qa-artifact> --dry-run --json
+# 10. Peaks-Cli TXT handoff — invoke peaks-txt which embeds memory markers and extracts
+#     peaks-txt writes the handoff capsule to .peaks/<id>/txt/handoff.md with embedded
+#     <!-- peaks-memory:start --> blocks, then runs memory extract on it.
+#     --apply is REQUIRED to write .peaks/memory; without it the command only previews.
+peaks memory extract --project <repo> --artifact .peaks/<id>/txt/handoff.md --apply --json
 
 # 11. Peaks-Cli Final snapshot
 peaks project dashboard --project <repo> --json
@@ -833,6 +836,11 @@ Use Peaks-Cli TXT for the compact handoff capsule: mode, validated decisions, ar
 
 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.
 
+Before ending, extract durable memories from this session:
+```bash
+peaks project memories:extract --session-id <session-id> --project <repo> --json
+```
+
 ## Peaks-Cli External references and lifecycle
 
 **Codegraph**: Optional project-analysis before RD handoff. Use `peaks codegraph affected --project <path> <changed-files...> --json` for regression-surface hints. Output as untrusted supporting evidence only; never commit `.codegraph/` artifacts.

package/skills/peaks-sop/SKILL.md

@@ -97,6 +97,22 @@ The three gate primitives are domain-neutral, so the same engine governs very di
 
 The one boundary to explain: a gate must reduce to **a file existing, text matching in a file, or a command's exit code**. A purely human-judgment gate ("did the editor approve?") is expressed by reifying it into a signal — e.g. require an `approved.md` file, or that a status file contains "approved". The `command` gate is the universal adapter for anything scriptable.
 
+### Literal-word trap and `stripMeta` (added by PRD 006 on 2026-06-02)
+
+A naive `grep` gate for a content-publishing SOP has a self-referential failure mode: the author writing *about* the gate's pattern ("we use a `grep absent: "TODO"` gate to block leftover T-O-D-O") ends up triggering the gate they just described. This is rare in code-review SOPs and very common in content/publishing SOPs.
+
+**Opt-in workaround**: add `stripMeta: true` to the gate's check. The evaluator strips HTML comments (`<!-- … -->`), fenced code blocks (` ``` … ``` `), and C-style block comments (`/* … */`) from the file content *before* applying the regex. The author's discussion of the gate in those areas is no longer counted.
+
+```json
+{
+  "id": "no-todo",
+  "phase": "publish",
+  "check": { "type": "grep", "file": "post.md", "pattern": "TODO", "absent": true, "stripMeta": true }
+}
+```
+
+Default `false` preserves byte-identical behavior for existing SOPs. The stripper is conservative on malformed input (unclosed fences / block comments fall through un-stripped). Not covered by this slice: inline code (`` `TODO` ``) and blockquotes (`> TODO`) — both are content the author explicitly chose to render, so they remain subject to the regex. If a future dogfood surfaces a need to strip those too, open a follow-up PRD.
+
 ## Un-bypassable enforcement (optional, opt-in)
 
 By default a SOP gate only blocks the `peaks sop advance` command — nothing forces the agent through it. To make a gate **physically un-bypassable**, a SOP can declare **guards** that bind a concrete irreversible Bash action to a phase, and the user installs a PreToolUse hook:
@@ -162,6 +178,7 @@ peaks hooks status --project <repo>
 peaks gate bypass --sop <sop-id> --phase <phase> --reason "<why>" --project <repo>
 
 # 9. hand the SOP to the user; clear presence when done
+peaks project memories:extract --session-id <session-id> --project <repo> --json  # extract durable memories
 peaks skill presence:clear --project <repo>
 ```
 

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

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

package/skills/peaks-txt/SKILL.md

@@ -118,7 +118,7 @@ Stable memory body.
 <!-- peaks-memory:end -->
 ```
 
-The primary write target is the target project's `.peaks/memory`. Use `peaks memory extract --project <path> --artifact <artifact>` to write durable project memories; pass `--dry-run` to preview without writing.
+The primary write target is the target project's `.peaks/memory`. Use `peaks memory extract --project <path> --artifact <artifact> --apply` to write durable project memories; omit `--apply` to preview without writing.
 
 ## Matt Pocock skills integration
 
@@ -190,13 +190,28 @@ peaks understand show --project <repo> --json
 # 4. Discover external capabilities before recommending memory or context tools
 peaks capabilities --json
 
-# 5. Memory extraction — writes by default, use --dry-run to preview
-peaks memory extract --project <repo> --artifact <artifact-path> --json
-peaks memory extract --project <repo> --artifact <artifact-path> --dry-run --json   # preview only
+# 5. Write the handoff capsule (see template above), then embed memory markers
+#    For each stable project fact, decision, rule, or convention discovered this session,
+#    append a <!-- peaks-memory:start --> block inside the capsule body:
+#
+#    <!-- peaks-memory:start -->
+#    title: Short project memory title
+#    kind: project | decision | convention | rule | reference | module
+#    ---
+#    Stable memory body. Concrete facts only — no secrets, no transient state.
+#    <!-- peaks-memory:end -->
+#
+#    Mark ONLY facts that survive the session: architectural decisions, stack constraints,
+#    naming conventions, API patterns, approved refactors. Do NOT embed: secrets, credentials,
+#    transient debugging notes, or session-specific context.
+
+# 6. Memory extraction — --apply is REQUIRED to write .peaks/memory
+#    (without --apply the command only previews; the directory will NOT be created)
+peaks memory extract --project <repo> --artifact .peaks/<id>/txt/handoff.md --apply --json
 peaks skill presence:clear --project <repo>                      # handoff capsule complete, remove presence indicator
 ```
 
-The default `peaks memory extract` call writes to `.peaks/memory`. Pass `--dry-run` to preview without writing.
+`peaks memory extract --apply` writes to `.peaks/memory` (without `--apply` it only previews). The handoff capsule `.peaks/<id>/txt/handoff.md` is the primary artifact for extraction — embed `<!-- peaks-memory:start -->` blocks in it for stable project facts before running extract.
 
 ### Transition verification gates (MANDATORY — run the command, see the output)