peaks-loop 4.0.0-beta.8 → 4.0.1

package/dist/services/skills/skill-conformance-service.js

@@ -0,0 +1,139 @@
+/**
+ * Skill-conformance audit (Slice #12) — checks every peaks-* SKILL.md
+ * against the 5 standards from the L1+L2+L3 redesign §5.4 Slice #12:
+ *
+ *   1. task-level frontmatter (all 12 skills must declare one)
+ *   2. CLI-back 注解 coverage (each skill body must document which
+ *      `peaks <cmd>` commands it composes; the absence is a SKILL.md
+ *      anti-pattern — it means the LLM has to discover the CLI
+ *      primitives by accident)
+ *   3. loadStrategy on-demand 标注 (skills should declare when they
+ *      load — `eager` for always-loaded, `on-demand` for invoked)
+ *   4. 800-line cap (Karpathy limit per spec §2.3)
+ *   5. outputStyle: peaks-concise-v1 frontmatter (peak-cli display
+ *      style for the skill's user-visible output)
+ *
+ * Plus 1 derived check:
+ *   6. CLI primitives declared in references/audit/ (Skill must
+ *      surface every peaks <cmd> it composes in the references/ subdir;
+ *      this is the "CLI-back 注解 100% 覆盖" check)
+ */
+import { readFileSync, statSync } from 'node:fs';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+const SKILL_NAMES = [
+    'peaks-ide',
+    'peaks-prd',
+    'peaks-ui',
+    'peaks-rd',
+    'peaks-qa',
+    'peaks-sc',
+    'peaks-code',
+    'peaks-resume',
+    'peaks-status',
+    'peaks-test',
+    'peaks-sop',
+    'peaks-txt',
+    'peaks-doctor'
+];
+const REQUIRED_FRONTMATTER_FIELDS = ['name', 'description'];
+const OPTIONAL_FRONTMATTER_FIELDS = ['task-level', 'loadStrategy', 'outputStyle'];
+const MAX_LINE_COUNT = 800;
+const CLI_BACK_PATTERNS = [
+    /`peaks\s+[a-z][a-z0-9-]+(?:\s+[a-z][a-z0-9-]+)*`/g,
+    /`peaks\s+[a-z][a-z0-9-]+/g,
+];
+function readSkillFrontmatter(skillPath) {
+    if (!existsSync(skillPath))
+        return null;
+    const content = readFileSync(skillPath, 'utf-8');
+    const match = /^---\n([\s\S]*?)\n---\n/.exec(content);
+    if (match === null)
+        return { raw: content, fields: {} };
+    const raw = match[1] ?? '';
+    const fields = {};
+    for (const line of raw.split('\n')) {
+        const colonIdx = line.indexOf(':');
+        if (colonIdx === -1)
+            continue;
+        const key = line.slice(0, colonIdx).trim();
+        const value = line.slice(colonIdx + 1).trim();
+        if (key.length > 0)
+            fields[key] = value;
+    }
+    return { raw, fields };
+}
+function lineCount(filePath) {
+    try {
+        return statSync(filePath).size > 0 ? readFileSync(filePath, 'utf-8').split(/\r?\n/).length : 0;
+    }
+    catch {
+        return 0;
+    }
+}
+function countCliBackReferences(content) {
+    let count = 0;
+    for (const pattern of CLI_BACK_PATTERNS) {
+        pattern.lastIndex = 0;
+        const matches = content.match(pattern);
+        if (matches)
+            count += matches.length;
+    }
+    return count;
+}
+export function auditSkillConformance(input) {
+    const skillsDir = join(input.projectRoot, 'skills');
+    const checks = [];
+    for (const skillName of SKILL_NAMES) {
+        // LLM-internal skills live under `skills/bee/<name>/` per spec 2026-07-05.
+        const topPath = join(skillsDir, skillName, 'SKILL.md');
+        const beePath = join(skillsDir, 'bee', skillName, 'SKILL.md');
+        const skillPath = existsSync(topPath) ? topPath : beePath;
+        const fm = readSkillFrontmatter(skillPath);
+        // 1. task-level frontmatter
+        if (fm === null) {
+            checks.push({ id: 'frontmatter:present', skill: skillName, level: 'fail', message: 'SKILL.md missing' });
+        }
+        else {
+            for (const required of REQUIRED_FRONTMATTER_FIELDS) {
+                if (fm.fields[required] === undefined) {
+                    checks.push({ id: `frontmatter:${required}`, skill: skillName, level: 'fail', message: `frontmatter missing required field "${required}"` });
+                }
+            }
+        }
+        // 2. CLI-back annotation
+        if (fm !== null) {
+            const content = readFileSync(skillPath, 'utf-8');
+            const cliCount = countCliBackReferences(content);
+            if (cliCount === 0) {
+                checks.push({ id: 'cli-back:present', skill: skillName, level: 'warn', message: 'no `peaks <cmd>` references in SKILL.md body; consider documenting which CLI primitives the skill composes' });
+            }
+        }
+        // 3. loadStrategy on-demand 标注
+        if (fm !== null && fm.fields['loadStrategy'] === undefined) {
+            checks.push({ id: 'loadStrategy:declared', skill: skillName, level: 'warn', message: 'loadStrategy not declared in frontmatter (eager | on-demand)' });
+        }
+        // 4. 800-line cap
+        if (fm !== null) {
+            const lines = lineCount(skillPath);
+            if (lines > MAX_LINE_COUNT) {
+                checks.push({ id: 'line-count:cap', skill: skillName, level: 'fail', message: `${lines} lines > ${MAX_LINE_COUNT} cap (Karpathy)` });
+            }
+        }
+        // 5. outputStyle: peaks-concise-v1
+        if (fm !== null && fm.fields['outputStyle'] === undefined) {
+            checks.push({ id: 'outputStyle:declared', skill: skillName, level: 'warn', message: 'outputStyle not declared in frontmatter' });
+        }
+    }
+    const failed = checks.filter((c) => c.level === 'fail').length;
+    const warned = checks.filter((c) => c.level === 'warn').length;
+    const passed = checks.filter((c) => c.level === 'pass').length;
+    return {
+        checked: checks.length,
+        passed,
+        warned,
+        failed,
+        checks,
+        summary: failed === 0 ? 'all hard checks pass; warnings are advisory' : `${failed} hard failure(s); fix before shipping`,
+    };
+}

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

@@ -0,0 +1,158 @@
+export type SkillPresenceMode = 'full-auto' | 'assisted' | 'swarm' | 'strict';
+export declare const VALID_SKILL_PRESENCE_MODES: ReadonlyArray<SkillPresenceMode>;
+export declare function isSkillPresenceMode(value: string): value is SkillPresenceMode;
+export type SkillPresence = {
+    skill: string;
+    mode?: SkillPresenceMode;
+    gate?: string;
+    sessionId?: string;
+    /**
+     * Identifier of the *outer* session — the Claude Code / Cursor /
+     * VSCode-plugin / other harness session that is currently driving
+     * the LLM. Sourced from the `PEAKS_OUTER_SESSION_ID` environment
+     * variable when set, with `CLAUDE_CODE_SESSION_ID` as a fallback for
+     * Claude Code. Stamped onto the presence file so the status line
+     * can tell whether the recorded skill belongs to the live outer
+     * session (show it) or a previous one (render idle), and so
+     * `setSkillPresence` can detect a session swap and AskUserQuestion
+     * the user about rolling a new peaks session.
+     */
+    outerSessionId?: string;
+    /**
+     * Set by `setSkillPresence` when the outer session id changed
+     * between the last presence write and this one AND the bound
+     * peaks session has a different (or no) recorded outer session id.
+     *
+     * As of slice 018 (auto-roll on outer-mismatch), the field is
+     * informational only — it tells the statusline and any log /
+     * observability consumer that an outer-session swap was observed
+     * on the previous heartbeat. The actual binding rotation is
+     * performed by `ensureSessionWithRotation` (slice 018), not by
+     * `setSkillPresence`. `peaks-code`'s Step 0 used to read this
+     * field and turn it into an AskUserQuestion; that ask is no
+     * longer needed because the rotation already happened by the time
+     * the skill is invoked.
+     */
+    outerSessionMismatch?: {
+        previous?: string;
+        current: string;
+        boundSessionId: string;
+        boundOuterSessionId?: string;
+    };
+    setAt: string;
+    lastHeartbeat?: string;
+};
+/**
+ * Resolve the active peaks session id from
+ * `.peaks/_runtime/session.json` (legacy: `.peaks/.session.json`).
+ * Returns `null` when no session is bound.
+ *
+ * Public export: callers like `peaks sub-agent dispatch` use this
+ * to auto-resolve `--session-id` when the LLM driver forgets to
+ * pass the flag, so dispatch records land in the right
+ * `.peaks/_sub_agents/<sid>/` tree instead of an `unknown-sid`
+ * fallback (slice 2026-06-26-unknown-sid-fallback-fix).
+ */
+export declare function getCurrentSessionId(projectRootOverride?: string): string | null;
+export declare function exportSkillPresence(projectRootOverride?: string): string;
+/**
+ * Write the per-caller active-skill marker to
+ * `.peaks/_runtime/<peakSid>/active-skill-<callerId>.json` (D6). Returns
+ * the written presence with the `callerId` field set.
+ *
+ * The caller is responsible for resolving the `callerId` (via
+ * `resolveCallerId` from `src/services/session/resolve-caller-id.ts`)
+ * and the `peakSessionId` (via `getCallerBinding` then reading
+ * `peakSessionId`, OR via `ensureSession` for the first-time case).
+ */
+export declare function setSkillPresenceForCaller(projectRootOverride: string, callerId: string, peakSessionId: string, skill: string, mode?: string, gate?: string): SkillPresence;
+export declare function setSkillPresence(skill: string, mode?: string, gate?: string, projectRootOverride?: string): SkillPresence;
+export declare function getSkillPresence(projectRootOverride?: string): SkillPresence | null;
+/**
+ * Slice 002 (v2.15.0) — presence staleness detection (AC-1).
+ *
+ * Compare the *outer* session id stamped onto the current presence
+ * marker against the *current* outer session id (from
+ * `PEAKS_OUTER_SESSION_ID` / `CLAUDE_CODE_SESSION_ID`).
+ *
+ * Stale reasons (in priority order):
+ *
+ *   - `'outer-session-mismatch'` — the presence was stamped by a
+ *     different outer (Claude / harness) session than the one that
+ *     is now driving peaks. Most common cause: the LLM closed the
+ *     previous Claude session, the next session boots and finds a
+ *     presence leftover from the old one. peaks-code Step 1 must
+ *     AskUserQuestion to confirm the user wants the old mode.
+ *
+ *   - `'no-presence'`            — there is no presence file on disk.
+ *     Not strictly "stale", but callers (peaks-code Step 1, `peaks
+ *     code should-pause --step step-1-mode-select`) want to treat
+ *     this case as "no opinion yet — must ask". Surfaced as
+ *     `stale: true` with reason `'no-presence'` so the ask path is
+ *     uniform.
+ *
+ *   - `null`                     — the presence exists AND its outer
+ *     session id matches the current outer session id. Not stale.
+ *     Caller may safely reuse the recorded mode.
+ *
+ * Pure read-only: never deletes the presence file (the rotation
+ * auto-clear path is a separate concern; see
+ * `clearStalePresenceOnRotation`). Test seam: `--current-outer` lets
+ * tests inject a deterministic current outer id without touching env
+ * vars.
+ */
+export type StaleReason = 'outer-session-mismatch' | 'no-presence';
+export type StalenessCheck = {
+    stale: boolean;
+    reason: StaleReason | null;
+    /** What was on disk; null when no presence was found. */
+    presence: SkillPresence | null;
+    /** Current outer session id (env-driven). Undefined when no signal. */
+    currentOuterSessionId: string | undefined;
+    /** Outer session id recorded on the presence marker. Undefined when no signal. */
+    recordedOuterSessionId: string | undefined;
+};
+export declare function checkStalePresence(opts?: {
+    projectRootOverride?: string | undefined;
+    /**
+     * Override the *current* outer session id. Test seam only.
+     *   - `undefined` (omitted): read from `PEAKS_OUTER_SESSION_ID` /
+     *     `CLAUDE_CODE_SESSION_ID` env vars.
+     *   - explicit `string`: use the value verbatim (empty string means
+     *     "no signal", same as a missing env var).
+     */
+    currentOuter?: string | undefined;
+}): StalenessCheck;
+/**
+ * Slice 002 (v2.15.0) — auto-clear stale presence on session
+ * rotation (AC-1).
+ *
+ * Called from `peaks workspace init` immediately after a successful
+ * `outer-session-mismatch` rotation. When the previous session's
+ * presence is still on disk under the OLD outer session id,
+ * clearing it prevents peaks-code Step 1 from picking up a stale
+ * `mode` field that the user never explicitly chose.
+ *
+ * Only clears when:
+ *   - the recorded outer session id does NOT match the current outer
+ *     session id (i.e. the presence IS stale), AND
+ *   - the recorded outer session id matches the just-rotated-out
+ *     session id (i.e. we're clearing exactly the old binding, not a
+ *     user-explicitly-set mode from another live outer session).
+ *
+ * Returns `{ cleared, reason }` so callers can surface the outcome
+ * in the JSON envelope and audit log. Pure: no env-var reads, all
+ * inputs are passed explicitly so the call site (init command) can
+ * decide what the "rotated-out" id was.
+ */
+export declare function clearStalePresenceOnRotation(opts: {
+    projectRootOverride?: string;
+    currentOuterSessionId: string | undefined;
+    rotatedOutSessionId: string | null;
+}): {
+    cleared: boolean;
+    reason: string | null;
+    recordedOuter?: string;
+};
+export declare function touchSkillHeartbeat(projectRootOverride?: string): SkillPresence | null;
+export declare function clearSkillPresence(projectRootOverride?: string): boolean;