peaks-loop 4.0.0-beta → 4.0.0-beta.10

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;

package/dist/services/standards/ide-aware-standards-service.js

@@ -0,0 +1,91 @@
+import { detectAllResourceTargets, getStandardsProfile, } from '../ide/resource-profile.js';
+import { executeProjectStandardsInit, executeProjectStandardsUpdate, } from './project-standards-service.js';
+import { detectInstalledIde } from '../ide/ide-detector.js';
+function warnUnregisteredIde(ideId, projectRoot) {
+    process.stderr.write(`peaks standards: IDE '${ideId}' has no standardsProfile declared; ` +
+        `falling back to the legacy Claude Code path (CLAUDE.md + .claude/rules/**) ` +
+        `for project '${projectRoot}'. This is a slice #011 follow-up gap; ` +
+        `see .peaks/memory/ide-adapter-resource-profile-framework.md.\n`);
+}
+function warnNoIdeDetected(projectRoot) {
+    process.stderr.write(`peaks standards: no IDE detected in '${projectRoot}'; ` +
+        `writing to the 2.0 canonical path (CLAUDE.md + .peaks/standards/**). ` +
+        `Projects with a legacy 1.x thick .claude/rules/ tree keep that layout ` +
+        `(use \`peaks standards migrate --from-claude-rules\` to converge to 2.0). ` +
+        `Pass --ide <id> to bypass detection.\n`);
+}
+/**
+ * Resolve the active IDE id for a standards call. Order of precedence:
+ *   1. explicit `options.ideId`
+ *   2. `IdeRegistry.detect()` from `options.projectRoot`
+ *   3. `null` (no detected IDE — caller falls back to legacy)
+ */
+export function resolveStandardsIdeId(options) {
+    if (options.ideId !== undefined) {
+        return options.ideId;
+    }
+    return detectInstalledIde(options.projectRoot);
+}
+/**
+ * Run `peaks standards init` with IDE-aware dispatch.
+ *
+ * When the resolved IDE has a `standardsProfile`, the call still
+ * delegates to the existing `executeProjectStandardsInit` (the
+ * profile maps to the Claude Code path; future per-IDE writers
+ * plug in here). When the IDE is unregistered for the standards
+ * profile, the call delegates to the legacy path + emits a stderr
+ * warning.
+ */
+export function executeProjectStandardsInitIdeAware(options) {
+    const ideId = resolveStandardsIdeId(options);
+    if (ideId === null) {
+        warnNoIdeDetected(options.projectRoot);
+        return executeProjectStandardsInit(options);
+    }
+    const profile = getStandardsProfile(ideId);
+    if (profile === null) {
+        warnUnregisteredIde(ideId, options.projectRoot);
+        return executeProjectStandardsInit(options);
+    }
+    // Claude Code path: profile matches the legacy writer. Future per-IDE
+    // writers (markdown+frontmatter, multiple rule roots, etc.) plug in
+    // here by branching on `profile.format` / `profile.rulesDir`.
+    return executeProjectStandardsInit(options);
+}
+/**
+ * Run `peaks standards update` with IDE-aware dispatch.
+ *
+ * Same dispatch rules as `executeProjectStandardsInitIdeAware`.
+ */
+export function executeProjectStandardsUpdateIdeAware(options) {
+    const ideId = resolveStandardsIdeId(options);
+    if (ideId === null) {
+        warnNoIdeDetected(options.projectRoot);
+        return executeProjectStandardsUpdate(options);
+    }
+    const profile = getStandardsProfile(ideId);
+    if (profile === null) {
+        warnUnregisteredIde(ideId, options.projectRoot);
+        return executeProjectStandardsUpdate(options);
+    }
+    return executeProjectStandardsUpdate(options);
+}
+/**
+ * Test seam + integration-test helper: returns the resolved IDE id
+ * for the call, plus the active standards profile. Exported for
+ * the integration test in `tests/unit/standards/ide-aware-standards-service.test.ts`
+ * to assert the dispatch decision without running the full write.
+ */
+export function inspectStandardsDispatch(options) {
+    const ideId = resolveStandardsIdeId(options);
+    if (ideId === null) {
+        return { ideId: null, profile: null };
+    }
+    return { ideId, profile: getStandardsProfile(ideId) };
+}
+/**
+ * Test seam: the resource-profile accessor exposes
+ * `detectAllResourceTargets` for callers that need to enumerate
+ * across all registered IDEs. Re-exported here for convenience.
+ */
+export { detectAllResourceTargets };

package/dist/services/standards/loop-engineering-lint.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Loop Engineering guidelines linter (M0).
+ *
+ * Pure function: takes the raw markdown text of
+ * `.peaks/standards/loop-engineering-guidelines.md` and returns either
+ * `{ ok: true, redLines: [...] }` or `{ ok: false, findings: [...] }`.
+ *
+ * The four required sections per red line (karpathy-style form) are:
+ *   - Failure modes
+ *   - Rewrite
+ *   - Self-check
+ *   - Out-of-scope
+ *
+ * Each red line is identified by a heading like `## RL-0 — ...`.
+ *
+ * The lint intentionally does NOT touch any application-level code; it
+ * only parses the guideline file. The peaks CLI command
+ * `peaks standards lint --category loop-engineering` (registered in M0's
+ * plan) will read this file from disk and call this function.
+ */
+export declare const EXPECTED_RED_LINE_IDS: readonly ["RL-0", "RL-1", "RL-2", "RL-3", "RL-4", "RL-5", "RL-6", "RL-7", "RL-8", "RL-9"];
+export type RedLineId = (typeof EXPECTED_RED_LINE_IDS)[number];
+export declare const REQUIRED_SECTIONS: readonly ["Failure modes", "Rewrite", "Self-check", "Out-of-scope"];
+export type RedLineSection = (typeof REQUIRED_SECTIONS)[number];
+export interface RedLineReport {
+    id: RedLineId;
+    title: string;
+    sections: Partial<Record<RedLineSection, string>>;
+}
+export type LintResult = {
+    ok: true;
+    redLines: RedLineReport[];
+} | {
+    ok: false;
+    findings: string[];
+    redLines: RedLineReport[];
+};
+export declare function lintLoopEngineeringGuidelines(raw: string): LintResult;

package/dist/services/standards/loop-engineering-lint.js

@@ -0,0 +1,101 @@
+/**
+ * Loop Engineering guidelines linter (M0).
+ *
+ * Pure function: takes the raw markdown text of
+ * `.peaks/standards/loop-engineering-guidelines.md` and returns either
+ * `{ ok: true, redLines: [...] }` or `{ ok: false, findings: [...] }`.
+ *
+ * The four required sections per red line (karpathy-style form) are:
+ *   - Failure modes
+ *   - Rewrite
+ *   - Self-check
+ *   - Out-of-scope
+ *
+ * Each red line is identified by a heading like `## RL-0 — ...`.
+ *
+ * The lint intentionally does NOT touch any application-level code; it
+ * only parses the guideline file. The peaks CLI command
+ * `peaks standards lint --category loop-engineering` (registered in M0's
+ * plan) will read this file from disk and call this function.
+ */
+export const EXPECTED_RED_LINE_IDS = [
+    'RL-0',
+    'RL-1',
+    'RL-2',
+    'RL-3',
+    'RL-4',
+    'RL-5',
+    'RL-6',
+    'RL-7',
+    'RL-8',
+    'RL-9',
+];
+export const REQUIRED_SECTIONS = [
+    'Failure modes',
+    'Rewrite',
+    'Self-check',
+    'Out-of-scope',
+];
+const RED_LINE_HEADING = /^##\s+(RL-\d+)\s+[—-]\s+(.+?)\s*$/gm;
+const SECTION_HEADING = /^##\s+(Failure modes|Rewrite|Self-check|Out-of-scope)\s*$/gm;
+export function lintLoopEngineeringGuidelines(raw) {
+    const findings = [];
+    if (!raw || raw.trim().length === 0) {
+        return { ok: false, findings: ['guideline file is empty'], redLines: [] };
+    }
+    const redLines = parseRedLines(raw);
+    if (redLines.length === 0) {
+        findings.push('no red line headings (`## RL-N — ...`) found');
+    }
+    for (const id of EXPECTED_RED_LINE_IDS) {
+        const rl = redLines.find((r) => r.id === id);
+        if (!rl) {
+            findings.push(`missing red line: ${id}`);
+            continue;
+        }
+        for (const section of REQUIRED_SECTIONS) {
+            if (!rl.sections[section] || rl.sections[section].trim().length === 0) {
+                findings.push(`${id} is missing section "${section}"`);
+            }
+        }
+    }
+    if (findings.length > 0) {
+        return { ok: false, findings, redLines };
+    }
+    return { ok: true, redLines };
+}
+function parseRedLines(raw) {
+    const headingRegex = new RegExp(RED_LINE_HEADING.source, RED_LINE_HEADING.flags);
+    const sectionRegex = new RegExp(SECTION_HEADING.source, SECTION_HEADING.flags);
+    const headings = [];
+    let m;
+    while ((m = headingRegex.exec(raw)) !== null) {
+        headings.push({ id: m[1] ?? '', title: m[2] ?? '', start: m.index + m[0].length, end: raw.length });
+    }
+    for (let i = 0; i < headings.length - 1; i++) {
+        headings[i].end = headings[i + 1].start;
+    }
+    if (headings.length > 0) {
+        headings[headings.length - 1].end = raw.length;
+    }
+    return headings.map((h) => {
+        const body = raw.slice(h.start, h.end);
+        const sections = {};
+        const sectionMatches = [];
+        let sm;
+        while ((sm = sectionRegex.exec(body)) !== null) {
+            sectionMatches.push({ name: sm[1], start: sm.index + sm[0].length });
+        }
+        for (let i = 0; i < sectionMatches.length; i++) {
+            const start = sectionMatches[i].start;
+            const end = i + 1 < sectionMatches.length ? sectionMatches[i + 1].start - sectionMatches[i].start : body.length - start;
+            const text = body.slice(start, start + end);
+            sections[sectionMatches[i].name] = text;
+        }
+        return {
+            id: h.id,
+            title: h.title,
+            sections,
+        };
+    });
+}

package/dist/services/standards/loop-engineering-readiness-lint.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Loop Engineering Readiness linter (M6 — peak-spec §7.5 + §8.4).
+ *
+ * Pure function: takes the raw markdown text of a peaks-* SKILL.md
+ * file and returns either
+ *   { ok: true, findings: [] }
+ * or
+ *   { ok: false, findings: string[] }.
+ *
+ * The lint asserts three structural properties the spec binds every
+ * Loop-Engineering-participating peaks-* skill to:
+ *
+ *   1. The skill references the shared guideline file
+ *      `.peaks/standards/loop-engineering-guidelines.md` (or its
+ *      alias `.peaks/standards/loop-engineering-guidelines.md`).
+ *      Reference may appear anywhere in the body — code fence,
+ *      plain prose, or list item — as long as the literal token is
+ *      present.
+ *
+ *   2. The skill does NOT introduce a CLI verb that bypasses the
+ *      LLM-coordinated model. We flag lines that look like
+ *      "Run `peaks <verb>` to …" where `<verb>` is not in the
+ *      allowlist of LLM-owned sediment / asset / evolution verbs.
+ *      The user types NL; the LLM runs the CLI on the user's behalf
+ *      (RL-1 / Human-NL-Choice-Only).
+ *
+ *   3. The skill does NOT introduce a JSON / manifest
+ *      hand-authoring surface. We flag lines containing phrases
+ *      like "Edit the manifest", "write the JSON", "fill the JSON
+ *      file", etc., when they are not part of an explicit allowlist
+ *      (allowlist only references; never an instructional phrase).
+ *
+ * Each finding is a single line of the form:
+ *   "<rule>: <offending excerpt>"
+ * so a downstream CLI can render it directly without further
+ * parsing.
+ *
+ * The lint intentionally does NOT touch any application-level
+ * code; it only parses a SKILL.md text. The peaks CLI command
+ * `peaks skill lint --category loop-engineering-readiness
+ *   --path <skill-dir>`
+ * (registered in src/cli/commands/skill-loop-engineering-readiness.ts)
+ * reads the SKILL.md from disk and calls this function.
+ *
+ * Per RL-1 / Human-NL-Choice-Only and
+ * `.peaks/memory/two-forms-only-rule.md`, the user only ever picks
+ * via AskUserQuestion or describes in NL; the LLM runs the CLI.
+ * This lint is what stops a future peaks-* skill from regressing
+ * that rule at the textual layer.
+ */
+export type LintFinding = string;
+export type ReadinessLintResult = {
+    ok: true;
+    findings: [];
+} | {
+    ok: false;
+    findings: LintFinding[];
+};
+/**
+ * The shared guideline file that every Loop-Engineering-participating
+ * peaks-* skill must reference. Both the canonical path and the
+ * common alias are accepted.
+ *
+ * The alias is intentionally identical to the canonical path here:
+ * the spec sometimes renders it as
+ *   `.peaks/standards/loop-engineering-guidelines.md`
+ * with a slash prefix and sometimes without. We accept both.
+ */
+export declare const LOOP_ENGINEERING_GUIDELINE_PATHS: readonly [".peaks/standards/loop-engineering-guidelines.md"];
+/**
+ * The allowlist of CLI verbs that a peaks-* SKILL.md may legitimately
+ * instruct an LLM to invoke on the user's behalf. These are the
+ * sediment / asset / evolution surface verbs introduced in
+ * 2026-07-07-loop-engineering-crystallization-design §7.4 plus the
+ * 18-verb sediment pool from 2026-07-04-peaks-maker-dynamic-skill-
+ * sediment-design §4.2.
+ *
+ * Any other `peaks <verb>` token that appears in the form
+ *   "Run `peaks <verb>` to …"
+ * is treated as a CLI-verb-bypass attempt and flagged.
+ */
+export declare const ALLOWED_CLI_VERBS: Set<string>;
+/**
+ * Phrases that constitute a JSON / manifest hand-authoring surface.
+ * If a SKILL.md instructs the user to perform one of these actions,
+ * it violates RL-1 / Human-NL-Choice-Only and is flagged.
+ *
+ * Each entry is a lowercase substring matched against each line of
+ * the SKILL.md. The match is case-insensitive; the surrounding
+ * `<verb>` placeholders in the original spec are matched literally.
+ */
+export declare const JSON_HAND_AUTHORING_PHRASES: ReadonlyArray<string>;
+/**
+ * Phrases that explicitly reference a JSON / manifest surface but
+ * in an ALLOWED way — e.g. "the manifest is written by the CLI" or
+ * "see manifest schema for details". A line that contains one of
+ * these allowlisted phrases is NOT flagged even if it contains a
+ * JSON-hand-authoring phrase elsewhere on the same line.
+ *
+ * The allowlist is intentionally narrow; it must mention either
+ * the CLI as the writer OR a schema reference, NOT an instructional
+ * verb targeting the user.
+ */
+export declare const JSON_REFERENCE_ALLOWLIST: ReadonlyArray<string>;
+/**
+ * Lint a SKILL.md text for Loop Engineering readiness.
+ *
+ * @param skillMdText raw markdown text of a peaks-* SKILL.md
+ * @returns a ReadinessLintResult
+ */
+export declare function lintSkillLoopEngineeringReadiness(skillMdText: string): ReadinessLintResult;