peaks-cli 1.3.8 → 1.4.0

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

@@ -270,6 +270,121 @@ function findDestructiveApplyLines(section) {
     const lines = section.split(/\r?\n/);
     return lines.filter((line) => DESTRUCTIVE_APPLY_PATTERNS.some((pattern) => pattern.test(line)));
 }
+// ---------------------------------------------------------------------------
+// 2026-06-10 — gateguard-fact-force integration check (NOT a peaks-cli hook).
+//
+// The `gateguard-fact-force` hook is a third-party PreToolUse hook that
+// fires on Edit / Write / MultiEdit and demands a 4-fact questionnaire
+// before allowing the edit. It is unrelated to peaks-cli, but when the
+// LLM is in a peaks-qa flow and edits `.peaks/_runtime/<sid>/qa/requests/
+// *.md`, the questionnaire demands facts that do not apply (no
+// importers, no public API, no data files, user instruction already
+// in the conversation context). The check below detects the hook in
+// `~/.claude/settings.json` and the project `.claude/settings.json`,
+// and warns when no `.peaks/**` skip is configured.
+//
+// Probing is split out of the check so the check itself stays a pure
+// mapping over `GateguardProbeResult`. Tests inject the probe to keep
+// `~/.claude/settings.json` from leaking into test fixtures.
+// ---------------------------------------------------------------------------
+/** Hook command fragments that identify the gateguard-fact-force hook. */
+const GATEGUARD_HOOK_NEEDLES = ['gateguard', 'fact-force', 'fact_force'];
+/** Token the gateguard hook exposes for "skip these paths" — the check
+ *  treats any match against `.peaks` (path or globs) as a routed
+ *  configuration. We accept a few common spellings because the third-
+ *  party hook's CLI surface is not part of peaks-cli's contract. */
+const GATEGUARD_PEAKS_SKIP_NEEDLES = [
+    '.peaks',
+    'peaks-skip',
+    'skip-glob',
+    '--skip',
+    'skip_paths'
+];
+function commandMentionsGateguard(command) {
+    if (typeof command !== 'string' || command.length === 0)
+        return false;
+    const lower = command.toLowerCase();
+    return GATEGUARD_HOOK_NEEDLES.some((needle) => lower.includes(needle));
+}
+function entrySkipsPeaks(entry) {
+    const matcher = typeof entry.matcher === 'string' ? entry.matcher : '';
+    const matcherMentionsPeaks = matcher.toLowerCase().includes('.peaks');
+    if (matcherMentionsPeaks)
+        return true;
+    for (const hook of entry.hooks) {
+        const command = typeof hook.command === 'string' ? hook.command : '';
+        const lower = command.toLowerCase();
+        if (GATEGUARD_PEAKS_SKIP_NEEDLES.some((needle) => lower.includes(needle))) {
+            return true;
+        }
+    }
+    return false;
+}
+function extractGateguardEntries(source, sourcePath, settings) {
+    if (settings === null || typeof settings !== 'object')
+        return [];
+    const hooks = settings.hooks;
+    if (hooks === null || typeof hooks !== 'object')
+        return [];
+    const preToolUse = hooks.PreToolUse;
+    if (!Array.isArray(preToolUse))
+        return [];
+    const out = [];
+    for (const rawEntry of preToolUse) {
+        if (rawEntry === null || typeof rawEntry !== 'object')
+            continue;
+        const entry = rawEntry;
+        if (!Array.isArray(entry.hooks))
+            continue;
+        const hooks = [];
+        for (const rawHook of entry.hooks) {
+            if (rawHook === null || typeof rawHook !== 'object')
+                continue;
+            const h = rawHook;
+            const hookEntry = {};
+            if (typeof h.type === 'string')
+                hookEntry.type = h.type;
+            if (typeof h.command === 'string')
+                hookEntry.command = h.command;
+            hooks.push(hookEntry);
+        }
+        if (!hooks.some((h) => commandMentionsGateguard(h.command)))
+            continue;
+        const outEntry = { hooks };
+        if (typeof entry.matcher === 'string')
+            outEntry.matcher = entry.matcher;
+        out.push({ source, sourcePath, entry: outEntry });
+    }
+    return out;
+}
+function readSettingsJson(path) {
+    if (!existsSync(path))
+        return null;
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+function defaultGateguardProbe() {
+    const projectRoot = findProjectRoot(process.cwd());
+    const globalPath = join(homedir(), '.claude', 'settings.json');
+    const projectPath = projectRoot === null ? null : join(projectRoot, '.claude', 'settings.json');
+    return {
+        globalSettingsPath: globalPath,
+        globalSettings: readSettingsJson(globalPath),
+        projectSettingsPath: projectPath,
+        projectSettings: projectPath === null ? null : readSettingsJson(projectPath)
+    };
+}
+export function collectGateguardEntries(probe) {
+    const fromGlobal = extractGateguardEntries('global', probe.globalSettingsPath ?? '~/.claude/settings.json', probe.globalSettings);
+    const fromProject = probe.projectSettingsPath === null
+        ? []
+        : extractGateguardEntries('project', probe.projectSettingsPath, probe.projectSettings);
+    return [...fromGlobal, ...fromProject];
+}
 export async function runDoctor(options = {}) {
     const checks = [];
     const registry = await loadSkillRegistry(options.skillsBaseDir);
@@ -619,6 +734,51 @@ export async function runDoctor(options = {}) {
             message: `Workspace layout check failed: ${getErrorMessage(error)}`
         });
     }
+    // 2026-06-10 — gateguard-fact-force integration check. The hook is a
+    // third-party PreToolUse that fires on Edit / Write and demands a
+    // 4-fact questionnaire; when the LLM is in a peaks-qa flow updating
+    // `.peaks/_runtime/<sid>/qa/requests/*.md` the facts do not apply.
+    // We warn when the hook is installed and no `.peaks/**` skip is
+    // configured. The check stays a pure mapping over the probe result
+    // so tests can drive it without touching the real `~/.claude/`.
+    const gateguardProbe = options.gateguardProbe ?? defaultGateguardProbe;
+    try {
+        const probe = gateguardProbe();
+        const offending = collectGateguardEntries(probe);
+        if (offending.length === 0) {
+            checks.push({
+                id: 'integration:gateguard-peaks-conflict',
+                ok: true,
+                message: 'No gateguard-fact-force PreToolUse hook detected in ~/.claude/settings.json or project .claude/settings.json; the Edit/Write fact-forcing flow will not interfere with peaks-qa .peaks/ artifact writes'
+            });
+        }
+        else {
+            const unrouted = offending.filter((location) => !entrySkipsPeaks(location.entry));
+            if (unrouted.length === 0) {
+                checks.push({
+                    id: 'integration:gateguard-peaks-conflict',
+                    ok: true,
+                    message: `gateguard-fact-force hook is installed in ${offending.map((l) => l.source).join(' + ')} but a .peaks/** skip pattern is configured; peaks-qa .peaks/ artifact writes are not blocked`
+                });
+            }
+            else {
+                const sources = Array.from(new Set(unrouted.map((u) => u.sourcePath))).join(' + ');
+                const matchers = unrouted.map((u) => u.entry.matcher ?? '*').join(', ');
+                checks.push({
+                    id: 'integration:gateguard-peaks-conflict',
+                    ok: false,
+                    message: `gateguard-fact-force PreToolUse hook is installed (${sources}, matcher: ${matchers}) with no .peaks/** skip pattern; every Edit/Write of a peaks-qa envelope (.peaks/_runtime/<sid>/qa/requests/*.md) will be intercepted and demand a 4-fact questionnaire that does not apply to QA templates. Workaround: set \`ECC_DISABLED_HOOKS=pre:edit-write:gateguard-fact-force\` for the session, OR add a paired PreToolUse entry whose matcher restricts the hook to non-.peaks paths. peaks-cli is NOT the source of this hook.`
+                });
+            }
+        }
+    }
+    catch (error) {
+        checks.push({
+            id: 'integration:gateguard-peaks-conflict',
+            ok: true,
+            message: `gateguard probe failed (${getErrorMessage(error)}); skipping check`
+        });
+    }
     try {
         const schemaText = await readText(join(schemaRoot, 'doctor-report.schema.json'));
         const schema = JSON.parse(schemaText);

package/dist/src/services/hooks/presence-marker-detector.d.ts

@@ -0,0 +1,16 @@
+export type DetectPresenceMarkerInput = {
+    project: string;
+    latestAssistantMessage: string;
+};
+export type DetectPresenceMarkerResult = {
+    active: boolean;
+    skill?: string;
+    markerFound: boolean;
+    warning?: string;
+};
+export type PresenceMarkerWarning = (typeof PRESENCE_MARKER_WARNING)[number];
+export declare const PRESENCE_MARKER_WARNING: readonly ["Peaks skill context may have been lost from this conversation; please re-invoke /peaks-<skill>."];
+/**
+ * Pure read-only presence-marker detection. No I/O side effects.
+ */
+export declare function detectPresenceMarker(input: DetectPresenceMarkerInput): DetectPresenceMarkerResult;

package/dist/src/services/hooks/presence-marker-detector.js

@@ -0,0 +1,105 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+/**
+ * Slice 028 (Q1=A): hook-based skill-presence marker detection.
+ *
+ * Background: the consumer-facing CLAUDE.md template (rendered by
+ * `peaks standards init` / `peaks standards update`) instructs the LLM
+ * to display a compact status header
+ *   `Peaks-Cli Skill: <skill> | Peaks-Cli Gate: <gate> | Next: <one short action>`
+ * on every turn while a peaks skill is active. If the LLM forgets (e.g.
+ * because of context compaction or a fresh session), the user is left
+ * without an at-a-glance signal that peaks is orchestrating the work.
+ *
+ * This service is the read-only side of the slice-028 detection
+ * mechanism. The PostToolUse hook (or any other consumer, e.g.
+ * `peaks skill detect-marker-loss`) calls
+ * `detectPresenceMarker({ project, latestAssistantMessage })`
+ * and gets back:
+ *
+ *   - `active`:      whether an active-skill marker was found on disk.
+ *   - `skill?`:      the active skill name, if any.
+ *   - `markerFound`: whether the latest assistant message carries the
+ *                    expected `Peaks-Cli Skill:` / `Peaks-Cli Gate:`
+ *                    marker. Always `false` when `active` is `false`.
+ *   - `warning?`:    a human-readable warning emitted when the marker
+ *                    is missing while the presence is active.
+ *
+ * The function is pure: it does not write to disk, does not clear the
+ * presence file, and does not depend on `process.cwd()`. The caller is
+ * expected to provide the absolute project root (peaks-cli convention
+ * from the standards-commands family — see dev-preference rule
+ * `project-option-is-canonical-project-root-source`).
+ */
+const PRESENCE_CANONICAL_PATH = '.peaks/_runtime/active-skill.json';
+const PRESENCE_LEGACY_PATH = '.peaks/.active-skill.json';
+const MARKER_PRIMARY = 'Peaks-Cli Skill:';
+const MARKER_SECONDARY = 'Peaks-Cli Gate:';
+const SKILL_NAME_RE = /"skill"\s*:\s*"([^"\\]*(?:\\.[^"\\]*)*)"/;
+export const PRESENCE_MARKER_WARNING = [
+    'Peaks skill context may have been lost from this conversation; please re-invoke /peaks-<skill>.'
+];
+function readPresenceFile(absolutePath) {
+    if (!existsSync(absolutePath))
+        return null;
+    let raw;
+    try {
+        raw = readFileSync(absolutePath, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (parsed === null || typeof parsed !== 'object')
+        return null;
+    const skillMatch = SKILL_NAME_RE.exec(JSON.stringify(parsed));
+    if (skillMatch === null)
+        return null;
+    if (typeof skillMatch[1] !== 'string' || skillMatch[1].length === 0)
+        return null;
+    return { skill: skillMatch[1] };
+}
+function readPresenceBackCompat(project) {
+    const projectRoot = resolve(project);
+    const canonicalPath = resolve(projectRoot, PRESENCE_CANONICAL_PATH);
+    const legacyPath = resolve(projectRoot, PRESENCE_LEGACY_PATH);
+    for (const candidate of [canonicalPath, legacyPath]) {
+        const parsed = readPresenceFile(candidate);
+        if (parsed === null)
+            continue;
+        return { skill: parsed.skill, path: candidate };
+    }
+    return null;
+}
+function messageHasMarker(message) {
+    if (message.length === 0)
+        return false;
+    return message.includes(MARKER_PRIMARY) || message.includes(MARKER_SECONDARY);
+}
+/**
+ * Pure read-only presence-marker detection. No I/O side effects.
+ */
+export function detectPresenceMarker(input) {
+    const project = input.project;
+    const message = input.latestAssistantMessage ?? '';
+    const presence = readPresenceBackCompat(project);
+    if (presence === null) {
+        return { active: false, markerFound: false };
+    }
+    const markerFound = messageHasMarker(message);
+    if (markerFound) {
+        return { active: true, skill: presence.skill, markerFound: true };
+    }
+    return {
+        active: true,
+        skill: presence.skill,
+        markerFound: false,
+        warning: PRESENCE_MARKER_WARNING[0]
+    };
+}

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

@@ -142,4 +142,23 @@ export declare function summarizeProjectMemoryBackupResult(result: ProjectMemory
  */
 export declare function ensureMemoryBootstrap(projectRoot: string): boolean;
 export declare function readProjectMemories(projectRoot: string): ProjectMemoryReadResult;
+export interface ProjectMemoryShowResult {
+    projectRoot: string;
+    memoryDir: string;
+    name: string;
+    body: string;
+    filePath: string;
+    updatedAt: string | null;
+    kind: ProjectMemoryKind | null;
+    title: string;
+    /** Whether the on-disk body bytes are returned (true) or a compact form (false). */
+    pretty: boolean;
+}
+/**
+ * Read a single project memory's full body by name. Returns null when
+ * the memory does not exist. The on-disk body is returned verbatim
+ * (pretty). The CLI layer applies `formatMdCompact` when `format: 'compact'`
+ * is requested. Slice 023 (R3).
+ */
+export declare function readProjectMemoryBody(projectRoot: string, name: string): ProjectMemoryShowResult | null;
 export {};

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

@@ -779,3 +779,36 @@ export function readProjectMemories(projectRoot) {
         memories
     };
 }
+/**
+ * Read a single project memory's full body by name. Returns null when
+ * the memory does not exist. The on-disk body is returned verbatim
+ * (pretty). The CLI layer applies `formatMdCompact` when `format: 'compact'`
+ * is requested. Slice 023 (R3).
+ */
+export function readProjectMemoryBody(projectRoot, name) {
+    const normalizedRoot = normalizeRoot(projectRoot);
+    const memoryDir = assertSafeProjectMemoryDir(normalizedRoot);
+    if (!existsSync(memoryDir)) {
+        ensureMemoryBootstrap(normalizedRoot);
+    }
+    for (const filePath of listMarkdownFiles(memoryDir)) {
+        if (basename(filePath, '.md') !== name)
+            continue;
+        const parsed = parseStoredMemoryFile(readFileSync(filePath, 'utf8'), filePath);
+        if (parsed === null)
+            continue;
+        const updatedAt = readMemoryFileMtime(filePath);
+        return {
+            projectRoot: normalizedRoot,
+            memoryDir,
+            name: parsed.name,
+            body: parsed.body,
+            filePath,
+            updatedAt,
+            kind: parsed.kind,
+            title: parsed.title,
+            pretty: true
+        };
+    }
+    return null;
+}

package/dist/src/services/retrospective/migrate-from-md.d.ts

@@ -0,0 +1,37 @@
+/**
+ * migrate-from-md — one-time migration from `.peaks/retrospective/<id>/*.md`
+ * per-workflow MD dirs to a single `.peaks/retrospective/index.json` plus a
+ * `.peaks/_archive/retrospective-2026-06-09-pre-r3.tar.gz` archive.
+ *
+ * Slice 023 (R3) G9. Idempotent: re-run is a no-op when `index.json` has
+ * 88 entries with matching `updatedAt`.
+ *
+ * The legacy MDs in this repo use a *bullet-list* metadata format (no YAML
+ * frontmatter). The fields we need are extracted from the leading bullet
+ * block: `session:`, `rid:`, `type:`, `sliceId:`, plus the first `# Title`
+ * heading.
+ */
+export interface MigrateOptions {
+    projectRoot: string;
+    apply?: boolean;
+    includeFailed?: boolean;
+    expectedEntries?: number;
+}
+export interface MigrateResult {
+    apply: boolean;
+    projectRoot: string;
+    indexPath: string;
+    archivePath: string | null;
+    sourceDir: string;
+    totalLegacyDirs: number;
+    totalLegacyMds: number;
+    parsedEntries: number;
+    failedEntries: Array<{
+        id: string;
+        reason: string;
+    }>;
+    archiveVerified: boolean;
+    status: 'applied' | 'no-op' | 'partial' | 'failed';
+    warnings: string[];
+}
+export declare function migrateRetrospectiveFromMd(options: MigrateOptions): MigrateResult;