peaks-cli 1.3.9 → 1.4.0

package/dist/src/services/skill-scope/source-of-truth.js

@@ -0,0 +1,118 @@
+/**
+ * Source-of-truth helpers for `peaks skill scope`.
+ *
+ * The source-of-truth file `.peaks/scope/skills.json` is the canonical
+ * record of the user's scope intent. Adapters translate it to their
+ * IDE-native config; the CLI always reads back from this file on `--show`.
+ *
+ * Atomicity: every write goes through `.peaks-tmp` first, then `rename`
+ * (POSIX-atomic; on Windows `rename` is atomic for files on the same volume).
+ * See tech-doc-025 §3.1.
+ */
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+/** File name for the canonical source-of-truth. */
+export const SCOPE_FILE_NAME = 'skills.json';
+/** Resolve the canonical source-of-truth path for a project root. */
+export function scopeFilePath(projectRoot) {
+    return join(projectRoot, '.peaks', 'scope', SCOPE_FILE_NAME);
+}
+/** Resolve the per-IDE companion file path (kebab-case). */
+export function ideCompanionFilePath(projectRoot, ide) {
+    return join(projectRoot, '.peaks', 'scope', `${ide}-skills.json`);
+}
+/** Resolve the `.peaks/scope/` directory for a project root. */
+export function scopeDir(projectRoot) {
+    return join(projectRoot, '.peaks', 'scope');
+}
+/**
+ * Read the source-of-truth scope config, or null if it does not exist.
+ * Returns null on parse error too — the caller decides whether to surface.
+ */
+export async function readSourceOfTruth(projectRoot) {
+    const file = scopeFilePath(projectRoot);
+    if (!existsSync(file))
+        return null;
+    try {
+        const raw = await readFile(file, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Read the per-IDE companion file (`.peaks/scope/<ide>-skills.json`), or
+ * null if it does not exist or is unparseable.
+ */
+export async function readIdeCompanion(projectRoot, ide) {
+    const file = ideCompanionFilePath(projectRoot, ide);
+    if (!existsSync(file))
+        return null;
+    try {
+        const raw = await readFile(file, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Write the canonical source-of-truth atomically. The `.peaks-tmp` file
+ * is cleaned up in a finally block on partial failure.
+ */
+export async function writeSourceOfTruth(projectRoot, config) {
+    const file = scopeFilePath(projectRoot);
+    await mkdir(scopeDir(projectRoot), { recursive: true });
+    const tmp = `${file}.peaks-tmp`;
+    try {
+        await writeFile(tmp, JSON.stringify(config, null, 2) + '\n', 'utf8');
+        await rename(tmp, file);
+        return file;
+    }
+    catch (error) {
+        if (existsSync(tmp)) {
+            try {
+                await rm(tmp, { force: true });
+            }
+            catch { /* best-effort */ }
+        }
+        throw error;
+    }
+}
+/**
+ * Write a generic JSON document atomically. Used by stub adapters for
+ * their `<ide>-skills.json` companion file (G3 §4.1).
+ */
+export async function writeJsonAtomic(file, data) {
+    await mkdir(dirname(file), { recursive: true });
+    const tmp = `${file}.peaks-tmp`;
+    try {
+        await writeFile(tmp, JSON.stringify(data, null, 2) + '\n', 'utf8');
+        await rename(tmp, file);
+    }
+    catch (error) {
+        if (existsSync(tmp)) {
+            try {
+                await rm(tmp, { force: true });
+            }
+            catch { /* best-effort */ }
+        }
+        throw error;
+    }
+}
+/**
+ * Remove a file if it exists. Returns true if it was removed.
+ */
+export async function removeIfExists(file) {
+    if (!existsSync(file))
+        return false;
+    try {
+        await rm(file, { force: true });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/src/services/skill-scope/types.d.ts

@@ -0,0 +1,176 @@
+/**
+ * `peaks skill scope` — slice 025 multi-IDE skill scoping types.
+ *
+ * This file is the single source of truth for the `SkillScopeAdapter`
+ * interface (G1). It is consumed by every per-IDE adapter (Claude Code
+ * full impl, 5 stub adapters) and by the detection algorithm + CLI.
+ *
+ * Design notes (see tech-doc-025 §2):
+ * - The interface is deliberately small: only the four operations the CLI
+ *   actually needs (detect / apply / show / reset).
+ * - `detect()` returns a confidence score in [0, 1] so the registry can
+ *   pick the best match when several adapters are partially active.
+ * - Errors are typed (NotSupportedError / ScopeApplyError), not strings.
+ *   The CLI maps `ScopeApplyError.code` to exit codes (see tech-doc §6.3).
+ */
+import type { IdeId } from '../ide/ide-types.js';
+/** Detection bucket for a single installed skill (G5). */
+export type SkillRelevance = 'relevant' | 'borderline' | 'irrelevant';
+/** Skill category — used for the JSON envelope's `kind` field (AC1). */
+export type SkillKind = 'peaks-family' | 'generic-ai' | 'language-specific' | 'other';
+/** Per-skill detail emitted by the detect algorithm. */
+export interface SkillScopeRecord {
+    /** Skill directory name (e.g. "peaks-rd", "tdd-guide"). */
+    readonly name: string;
+    /** Category — peaks-family, generic-ai, language-specific, other. */
+    readonly kind: SkillKind;
+    /** Detection bucket. */
+    readonly relevance: SkillRelevance;
+    /** Human-readable reasons that produced the bucket; stable for fixtures. */
+    readonly reasons: readonly string[];
+}
+/** Counts of skills per bucket, for the JSON envelope (AC1). */
+export interface SkillScopeCounts {
+    readonly relevant: number;
+    readonly borderline: number;
+    readonly irrelevant: number;
+}
+/** Project signals extracted from package.json + tsconfig + file tree (G5). */
+export interface ProjectSignals {
+    /** True when the project's root package.json exists. */
+    readonly hasPackageJson: boolean;
+    readonly isTypeScript: boolean;
+    readonly isTypeScriptESM: boolean;
+    readonly isReact: boolean;
+    readonly isVue: boolean;
+    readonly isSvelte: boolean;
+    readonly isNext: boolean;
+    readonly isNestJS: boolean;
+    readonly isExpress: boolean;
+    readonly isFastify: boolean;
+    readonly isPostgres: boolean;
+    readonly isMysql: boolean;
+    readonly isMongo: boolean;
+    readonly isRedis: boolean;
+    readonly isDocker: boolean;
+    readonly isK8s: boolean;
+    readonly isCommander: boolean;
+    readonly isCodegraph: boolean;
+    readonly isHeadroom: boolean;
+    /** True when the project is a Python project (no package.json / has pyproject). */
+    readonly isPython: boolean;
+    /** Major version of Node engine requirement, or null. */
+    readonly nodeEngineMajor: number | null;
+    /** Top file extensions under src/ (max 50, lexicographically sorted, unique). */
+    readonly topExtensions: readonly string[];
+    /** Per-extension presence flags derived from topExtensions. */
+    readonly hasFileExtension: Readonly<Record<string, boolean>>;
+}
+/** The shape of the always-written source-of-truth file. */
+export interface ScopeConfig {
+    /** ISO-8601 UTC timestamp at which this scope was last applied. */
+    readonly generatedAt: string;
+    /** Detected or explicitly-selected IDE id. */
+    readonly ide: IdeId;
+    /** Strictness mode (drives borderline handling). */
+    readonly strict: boolean;
+    /** Skills the user wants available (LLM-invokable). Always includes all peaks-*. */
+    readonly allowlist: readonly string[];
+    /** Skills the user wants hidden. */
+    readonly denylist: readonly string[];
+    /** Per-skill reasons (mirrored from detect, for audit). */
+    readonly skills: readonly SkillScopeRecord[];
+    /** Project signals that drove the classification. */
+    readonly signals: ProjectSignals;
+}
+/** Returned from `applyScope`. */
+export interface ApplyResult {
+    /** Adapter id that handled the apply. */
+    readonly ide: IdeId;
+    /** Whether the apply succeeded (false = NOT_SUPPORTED or hard failure). */
+    readonly ok: boolean;
+    /** Absolute paths the adapter wrote or removed. */
+    readonly writtenFiles: readonly string[];
+    /** Whether shadow stubs were used (Claude Code fallback path). */
+    readonly usedShadowStub: boolean;
+    /** Whether the adapter returned NOT_SUPPORTED and only wrote the source-of-truth. */
+    readonly notSupported: boolean;
+    /** Peaks-* skills the adapter stripped from the denylist (G6 enforcement report). */
+    readonly strippedFromDenylist?: readonly string[];
+    /** Optional error code when ok=false. */
+    readonly error?: {
+        readonly code: string;
+        readonly message: string;
+    };
+}
+/** Returned from `showScope`. */
+export interface ShowScopeResult {
+    /** The source-of-truth config, or null if no scope has been applied. */
+    readonly source: ScopeConfig | null;
+    /** Whatever the adapter can read back from its native config. Null if not supported. */
+    readonly native: unknown;
+    /** Adapter id. */
+    readonly ide: IdeId;
+}
+/** Reset output mirrors apply but without the lists. */
+export interface ResetScopeResult {
+    readonly ide: IdeId;
+    readonly removedFiles: readonly string[];
+}
+/** Sentinel error type for stub adapters (G3). */
+export declare class NotSupportedError extends Error {
+    readonly code: "NOT_SUPPORTED";
+    readonly ide: IdeId;
+    constructor(ide: IdeId, message: string);
+}
+/** Errors emitted by adapters (validated by runtime probe in claude-code §3.4). */
+export type ScopeApplyErrorCode = 'NOT_SUPPORTED' | 'IO_ERROR' | 'MALFORMED_CONFIG' | 'WRITE_FAILED' | 'PARTIAL_FAILURE';
+export declare class ScopeApplyError extends Error {
+    readonly code: ScopeApplyErrorCode;
+    readonly ide: IdeId;
+    constructor(code: ScopeApplyErrorCode, message: string, ide: IdeId);
+}
+/** Input to `applyScope`. */
+export interface ApplyScopeInput {
+    /** Final allowlist (the CLI guarantees peaks-* is in here before calling). */
+    readonly allowlist: readonly string[];
+    /** Final denylist. */
+    readonly denylist: readonly string[];
+    /** Strictness mode. */
+    readonly strict: boolean;
+    /** Project root for resolving relative paths. */
+    readonly projectRoot: string;
+    /** Source-of-truth config that the adapter MAY re-derive fields from. */
+    readonly sourceConfig: ScopeConfig;
+    /** When true, prefer shadow-stub fallback over the native config. */
+    readonly shadowFallback: boolean;
+    /** Test seam: simulate an adapter write failure (returns the partial path written before failure). */
+    readonly simulateWriteFailure?: boolean;
+}
+/** Reset input mirrors apply but without the lists. */
+export interface ResetScopeInput {
+    readonly projectRoot: string;
+}
+/** The interface every adapter implements. */
+export interface SkillScopeAdapter {
+    /** Adapter id; matches the IdeId it pairs with. */
+    readonly ide: IdeId;
+    /** Whether this adapter supports a real (non-stub) implementation. */
+    readonly supported: boolean;
+    /** Detect this adapter's IDE is active in the given project root. Returns a confidence score in [0,1]. */
+    detect(projectRoot: string): Promise<number>;
+    /** Write the IDE-specific scope config. */
+    applyScope(input: ApplyScopeInput): Promise<ApplyResult>;
+    /** Read the current scope config. */
+    showScope(projectRoot: string): Promise<ShowScopeResult>;
+    /** Remove the IDE-specific scope config. */
+    resetScope(input: ResetScopeInput): Promise<ResetScopeResult>;
+}
+/** Helper: build a NOT_SUPPORTED ApplyResult (for stub adapters that pre-write source-of-truth). */
+export declare function makeNotSupportedResult(ide: IdeId, message: string, writtenFiles?: readonly string[]): ApplyResult;
+/** Hard-coded allowlist of peaks-* skills (G6 + generic AI-engineering skills per AC2). */
+export declare const ALWAYS_RELEVANT_SKILLS: readonly string[];
+/** Hard-coded denylist prefixes: non-TS language families (G5 §5.4). */
+export declare const NON_TS_SKILL_PREFIXES: readonly string[];
+/** File extensions the file-tree walker looks for (top-50 limit per tech-doc §5.1). */
+export declare const TRACKED_EXTENSIONS: readonly string[];

package/dist/src/services/skill-scope/types.js

@@ -0,0 +1,74 @@
+/**
+ * `peaks skill scope` — slice 025 multi-IDE skill scoping types.
+ *
+ * This file is the single source of truth for the `SkillScopeAdapter`
+ * interface (G1). It is consumed by every per-IDE adapter (Claude Code
+ * full impl, 5 stub adapters) and by the detection algorithm + CLI.
+ *
+ * Design notes (see tech-doc-025 §2):
+ * - The interface is deliberately small: only the four operations the CLI
+ *   actually needs (detect / apply / show / reset).
+ * - `detect()` returns a confidence score in [0, 1] so the registry can
+ *   pick the best match when several adapters are partially active.
+ * - Errors are typed (NotSupportedError / ScopeApplyError), not strings.
+ *   The CLI maps `ScopeApplyError.code` to exit codes (see tech-doc §6.3).
+ */
+/** Sentinel error type for stub adapters (G3). */
+export class NotSupportedError extends Error {
+    code = 'NOT_SUPPORTED';
+    ide;
+    constructor(ide, message) {
+        super(`${ide}: ${message}`);
+        this.name = 'NotSupportedError';
+        this.ide = ide;
+    }
+}
+export class ScopeApplyError extends Error {
+    code;
+    ide;
+    constructor(code, message, ide) {
+        super(`${ide}: ${message}`);
+        this.name = 'ScopeApplyError';
+        this.code = code;
+        this.ide = ide;
+    }
+}
+/** Helper: build a NOT_SUPPORTED ApplyResult (for stub adapters that pre-write source-of-truth). */
+export function makeNotSupportedResult(ide, message, writtenFiles = []) {
+    return {
+        ide,
+        ok: false,
+        writtenFiles: [...writtenFiles],
+        usedShadowStub: false,
+        notSupported: true,
+        error: { code: 'NOT_SUPPORTED', message },
+    };
+}
+/** Hard-coded allowlist of peaks-* skills (G6 + generic AI-engineering skills per AC2). */
+export const ALWAYS_RELEVANT_SKILLS = [
+    // peaks-* family (G6 hard constraint)
+    'peaks-rd', 'peaks-qa', 'peaks-solo', 'peaks-prd', 'peaks-sc',
+    'peaks-txt', 'peaks-sop', 'peaks-solo-resume', 'peaks-solo-status',
+    'peaks-solo-test', 'peaks-ui', 'peaks-ide',
+    // generic AI-engineering skills (per AC2)
+    'tdd-guide', 'coding-standards', 'karpathy-guidelines',
+    'continuous-learning', 'code-tour', 'agent-harness-construction',
+    'security-review', 'code-review',
+];
+/** Hard-coded denylist prefixes: non-TS language families (G5 §5.4). */
+export const NON_TS_SKILL_PREFIXES = [
+    'kotlin-', 'python-', 'java-', 'rust-', 'go-', 'ruby-',
+    'swift-', 'csharp-', 'cpp-',
+];
+/** File extensions the file-tree walker looks for (top-50 limit per tech-doc §5.1). */
+export const TRACKED_EXTENSIONS = [
+    '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs',
+    '.swift', '.kt', '.kts', '.java', '.scala',
+    '.py', '.pyx', '.go', '.rs',
+    '.rb', '.php', '.cs', '.cpp', '.c', '.h', '.hpp',
+    '.vue', '.svelte', '.html', '.css', '.scss',
+    '.json', '.yaml', '.yml', '.toml', '.md',
+    '.sql', '.sh', '.bash', '.ps1',
+    '.dockerfile', '.dockerignore', '.lua', '.ex', '.exs', '.erl', '.hs',
+    '.dart', '.r', '.jl', '.clj',
+];

package/dist/src/services/standards/migrate-service.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Slice 028 (Q2=A): `peaks standards migrate` rewrites a consumer
+ * project's `CLAUDE.md` to drop the legacy heartbeat block.
+ *
+ * The legacy block (rendered by `peaks standards init` / `peaks
+ * standards update` before slice 028) contained instructions that:
+ *   1. pointed the LLM at the legacy `.peaks/.active-skill.json` path;
+ *   2. required the LLM to invoke `peaks skill heartbeat:touch` and
+ *      `peaks skill presence:clear` on every turn;
+ *   3. ended with an `External reference: https://github.com/affaan-m/...`
+ *      line that was peaks-cli-internal, not consumer-facing.
+ *
+ * The replacement text matches the post-slice-025 peaks-cli repo's own
+ * `CLAUDE.md`: route the LLM through `peaks skill presence --json` and
+ * render a compact status header when a valid skill is active. This
+ * service is the deterministic in-place rewriter that brings existing
+ * consumer trees in line with the new template.
+ *
+ * Behavior:
+ *   - `migrateStandards({ project, apply: true })`     — rewrites the
+ *     file when the legacy block is present, returns
+ *     `applied: true`.
+ *   - `migrateStandards({ project, dryRun: true })`    — returns the
+ *     would-change preview, no write.
+ *   - `migrateStandards({ project })`                  — defaults to a
+ *     dry-run. `--apply` is the only opt-in for a destructive write.
+ *   - File missing → `file: null`, no throw.
+ *   - Legacy block not present → `foundOldBlock: false`, no write.
+ */
+export declare const NEW_TEMPLATE_TEXT = "Active Peaks-Cli skill presence: at the start of every response, run `peaks skill presence --json` to read the active skill marker. The CLI handles canonical-path resolution (`.peaks/_runtime/active-skill.json` with back-compat fallback to `.peaks/.active-skill.json`); do not read those files directly. When the response includes a valid skill name, display the compact status header: `Peaks-Cli Skill: <skill> | Peaks-Cli Gate: <gate> | Next: <one short action>`. Display the header on every turn while the CLI returns an active skill; omit when the CLI returns no active skill.";
+export type MigrateStandardsInput = {
+    project: string;
+    apply?: boolean;
+    dryRun?: boolean;
+};
+export type MigrateStandardsData = {
+    file: string | null;
+    foundOldBlock: boolean;
+    wouldChange: boolean;
+    applied: boolean;
+    before: {
+        lines: number;
+    } | null;
+    after: {
+        lines: number;
+    } | null;
+    nextActions: string[];
+};
+export type MigrateStandardsResult = {
+    ok: true;
+    data: MigrateStandardsData;
+    warnings: string[];
+};
+export declare function detectLegacyBlock(content: string): {
+    found: boolean;
+    start: number;
+    end: number;
+};
+export declare function rewriteLegacyBlock(content: string, newText?: string): {
+    rewritten: string;
+    replaced: boolean;
+};
+export declare function migrateStandards(input: MigrateStandardsInput): MigrateStandardsResult;

package/dist/src/services/standards/migrate-service.js

@@ -0,0 +1,193 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { isAbsolute, resolve } from 'node:path';
+/**
+ * Slice 028 (Q2=A): `peaks standards migrate` rewrites a consumer
+ * project's `CLAUDE.md` to drop the legacy heartbeat block.
+ *
+ * The legacy block (rendered by `peaks standards init` / `peaks
+ * standards update` before slice 028) contained instructions that:
+ *   1. pointed the LLM at the legacy `.peaks/.active-skill.json` path;
+ *   2. required the LLM to invoke `peaks skill heartbeat:touch` and
+ *      `peaks skill presence:clear` on every turn;
+ *   3. ended with an `External reference: https://github.com/affaan-m/...`
+ *      line that was peaks-cli-internal, not consumer-facing.
+ *
+ * The replacement text matches the post-slice-025 peaks-cli repo's own
+ * `CLAUDE.md`: route the LLM through `peaks skill presence --json` and
+ * render a compact status header when a valid skill is active. This
+ * service is the deterministic in-place rewriter that brings existing
+ * consumer trees in line with the new template.
+ *
+ * Behavior:
+ *   - `migrateStandards({ project, apply: true })`     — rewrites the
+ *     file when the legacy block is present, returns
+ *     `applied: true`.
+ *   - `migrateStandards({ project, dryRun: true })`    — returns the
+ *     would-change preview, no write.
+ *   - `migrateStandards({ project })`                  — defaults to a
+ *     dry-run. `--apply` is the only opt-in for a destructive write.
+ *   - File missing → `file: null`, no throw.
+ *   - Legacy block not present → `foundOldBlock: false`, no write.
+ */
+export const NEW_TEMPLATE_TEXT = 'Active Peaks-Cli skill presence: at the start of every response, run `peaks skill presence --json` to read the active skill marker. The CLI handles canonical-path resolution (`.peaks/_runtime/active-skill.json` with back-compat fallback to `.peaks/.active-skill.json`); do not read those files directly. When the response includes a valid skill name, display the compact status header: `Peaks-Cli Skill: <skill> | Peaks-Cli Gate: <gate> | Next: <one short action>`. Display the header on every turn while the CLI returns an active skill; omit when the CLI returns no active skill.';
+const LEGACY_BLOCK_OPENER_LINE = 'Peaks-Cli 心跳检测 (heartbeat check)';
+const LEGACY_BLOCK_CLOSER = 'External reference: https://github.com/affaan-m/everything-claude-code';
+const LEGACY_MARKER_FALLBACK = 'Do NOT skip step 3-5. The CLI heartbeat:touch command';
+const FORBIDDEN_LEGACY_STRINGS = [
+    'heartbeat:touch',
+    'presence:clear',
+    'Default runbook',
+    'Startup sequence',
+    'Swarm parallel phase'
+];
+const NEW_TEMPLATE_FINGERPRINT = 'peaks skill presence --json';
+export function detectLegacyBlock(content) {
+    const openerIndex = content.indexOf(LEGACY_BLOCK_OPENER_LINE);
+    if (openerIndex >= 0) {
+        // Walk back to the start of the `<!--` line. The opener text is
+        // typically indented on the line after `<!--` (the legacy block
+        // is a multi-line HTML comment), so we cut from the most recent
+        // `<!--` line above. If no `<!--` is found in the surrounding
+        // 4 lines, fall back to the start of the opener's own line.
+        const htmlCommentIndex = content.lastIndexOf('<!--', openerIndex);
+        const previousNewlineBeforeOpener = content.lastIndexOf('\n', openerIndex);
+        let start;
+        if (htmlCommentIndex < 0 || htmlCommentIndex < previousNewlineBeforeOpener - 200) {
+            // No `<!--` line within a reasonable distance — start of the
+            // opener's own line.
+            start = previousNewlineBeforeOpener + 1;
+        }
+        else {
+            start = content.lastIndexOf('\n', htmlCommentIndex) + 1;
+        }
+        const closerIndex = content.indexOf(LEGACY_BLOCK_CLOSER, openerIndex);
+        let endIndex;
+        if (closerIndex < 0) {
+            const tailIndex = content.indexOf(LEGACY_MARKER_FALLBACK, openerIndex);
+            if (tailIndex < 0) {
+                endIndex = content.length;
+            }
+            else {
+                endIndex = content.indexOf('\n', tailIndex);
+                if (endIndex < 0)
+                    endIndex = content.length;
+            }
+        }
+        else {
+            endIndex = content.indexOf('\n', closerIndex);
+            if (endIndex < 0)
+                endIndex = content.length;
+        }
+        return { found: true, start, end: endIndex };
+    }
+    // Fallback: opener stripped by editor / re-format. Detect by the
+    // first forbidden string that survives the rewrite, then walk back
+    // to the start of the line.
+    for (const marker of FORBIDDEN_LEGACY_STRINGS) {
+        const idx = content.indexOf(marker);
+        if (idx >= 0) {
+            const start = content.lastIndexOf('\n', idx) + 1;
+            return { found: true, start, end: content.length };
+        }
+    }
+    return { found: false, start: -1, end: -1 };
+}
+export function rewriteLegacyBlock(content, newText = NEW_TEMPLATE_TEXT) {
+    const detection = detectLegacyBlock(content);
+    if (!detection.found) {
+        return { rewritten: content, replaced: false };
+    }
+    const before = content.slice(0, detection.start);
+    const after = content.slice(detection.end);
+    const trimmedBefore = before.replace(/\s+$/u, '\n');
+    const cleanedAfter = after.replace(/^\n+/u, '\n');
+    const rewritten = `${trimmedBefore}${newText}${cleanedAfter}`;
+    return { rewritten, replaced: true };
+}
+export function migrateStandards(input) {
+    const project = input.project;
+    const projectRoot = isAbsolute(project) ? project : resolve(project);
+    const filePath = resolve(projectRoot, 'CLAUDE.md');
+    const apply = input.apply === true;
+    const dryRun = input.dryRun === true || apply === false;
+    if (!existsSync(filePath)) {
+        return {
+            ok: true,
+            data: {
+                file: null,
+                foundOldBlock: false,
+                wouldChange: false,
+                applied: false,
+                before: null,
+                after: null,
+                nextActions: ['CLAUDE.md does not exist; nothing to migrate']
+            },
+            warnings: []
+        };
+    }
+    const original = readFileSync(filePath, 'utf8');
+    const detection = detectLegacyBlock(original);
+    if (!detection.found) {
+        if (original.includes(NEW_TEMPLATE_FINGERPRINT)) {
+            return {
+                ok: true,
+                data: {
+                    file: filePath,
+                    foundOldBlock: false,
+                    wouldChange: false,
+                    applied: false,
+                    before: { lines: original.split('\n').length },
+                    after: null,
+                    nextActions: ['CLAUDE.md is already up to date']
+                },
+                warnings: []
+            };
+        }
+        return {
+            ok: true,
+            data: {
+                file: filePath,
+                foundOldBlock: false,
+                wouldChange: false,
+                applied: false,
+                before: { lines: original.split('\n').length },
+                after: null,
+                nextActions: ['CLAUDE.md has no peaks-cli block; nothing to migrate']
+            },
+            warnings: []
+        };
+    }
+    const { rewritten } = rewriteLegacyBlock(original);
+    const nextActions = [];
+    if (dryRun) {
+        nextActions.push('Re-run with --apply to perform the rewrite');
+        return {
+            ok: true,
+            data: {
+                file: filePath,
+                foundOldBlock: true,
+                wouldChange: true,
+                applied: false,
+                before: { lines: original.split('\n').length },
+                after: { lines: rewritten.split('\n').length },
+                nextActions
+            },
+            warnings: []
+        };
+    }
+    writeFileSync(filePath, rewritten, 'utf8');
+    nextActions.push('CLAUDE.md rewritten; no further action required');
+    return {
+        ok: true,
+        data: {
+            file: filePath,
+            foundOldBlock: true,
+            wouldChange: true,
+            applied: true,
+            before: { lines: original.split('\n').length },
+            after: { lines: rewritten.split('\n').length },
+            nextActions
+        },
+        warnings: []
+    };
+}

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

@@ -134,29 +134,7 @@ function renderClaudeMd(language, ctx) {
         '- Read `.claude/rules/common/security.md` before touching filesystem, user input, external calls, auth, or secrets.',
         `- Read .claude/rules/${language}/coding-style.md for language-specific standards when applicable.`,
         '',
-        '<!--',
-        '  Peaks-Cli 心跳检测 (heartbeat check)',
-        '  LLM 每轮回复前必须执行以下步骤，由 CLI 命令强制执行:',
-        '  1. 读取 .peaks/.active-skill.json → 存在则显示 status header',
-        '  2. 扫描当前上下文查找 peaks 技能标记',
-        '     ("Peaks-Cli Gate", "Peaks-Cli Default runbook", "Peaks-Cli Startup sequence")',
-        '  3. 标记存在 → 调用 `peaks skill heartbeat:touch` 记录心跳',
-        '  4. 标记不存在 → 显示警告 + 调用 `peaks skill presence:clear` 关闭心跳',
-        '-->',
-        'Active Peaks-Cli skill presence: at the start of EVERY response, run these steps in order:',
-        '',
-        '1. Read `.peaks/.active-skill.json`. If missing or invalid, skip all remaining steps.',
-        '2. Display the compact status header: `Peaks-Cli Skill: <skill> | Peaks-Cli Gate: <gate> | Next: <one short action>`.',
-        '3. Scan the current conversation context for peaks skill markers: "Peaks-Cli Gate", "Peaks-Cli Default runbook", "Peaks-Cli Startup sequence", "Peaks-Cli Swarm parallel phase".',
-        '4. If at least one marker IS found → run `peaks skill heartbeat:touch` to record a successful heartbeat. The CLI command writes the timestamp and returns JSON — verify it succeeded.',
-        '5. If NO markers are found → the skill context has been lost (context compaction). Run `peaks skill presence:clear` to close the heartbeat, then display this warning:',
-        '',
-        '> ⚠ Peaks-Cli: skill presence file was active but skill context has been lost from the conversation. The workflow can no longer run correctly. Please re-invoke the relevant /peaks-* skill to reload the full skill instructions.',
-        '',
-        'Do NOT skip step 3-5. The CLI heartbeat:touch command is the mechanism that makes heartbeat auditable — failing to call it means the heartbeat is broken.',
-        '',
-        'External reference: https://github.com/affaan-m/everything-claude-code is used as a curated reference only. Do not execute or install external content without explicit approval.',
-        ''
+        'Active Peaks-Cli skill presence: at the start of every response, run `peaks skill presence --json` to read the active skill marker. The CLI handles canonical-path resolution (`.peaks/_runtime/active-skill.json` with back-compat fallback to `.peaks/.active-skill.json`); do not read those files directly. When the response includes a valid skill name, display the compact status header: `Peaks-Cli Skill: <skill> | Peaks-Cli Gate: <gate> | Next: <one short action>`. Display the header on every turn while the CLI returns an active skill; omit when the CLI returns no active skill.'
     ].join('\n');
     const stack = renderProjectStackSection(ctx);
     return stack === '' ? head : `${head}\n${stack}`;