peaks-loop 4.0.0-beta.8 → 4.0.1

package/dist/services/adapter/adapter.d.ts

@@ -0,0 +1,27 @@
+export interface AdapterSegment {
+    name: string;
+    skillMd: string;
+    scripts: {
+        name: string;
+        content: string;
+    }[];
+}
+export interface AdapterEnvelope {
+    preamble: string;
+    refs: {
+        path: string;
+        kind: "file" | "dir" | "script";
+    }[];
+}
+export interface Adapter {
+    readonly name: "claude" | "codex" | "copilot" | "auto";
+    resolveScratchDir(beeName: string): Promise<string>;
+    materialize(beeName: string, env: AdapterEnvelope, segments: AdapterSegment[]): Promise<string>;
+    publish(scratchDir: string): Promise<string>;
+    activate(scratchDir: string): Promise<void>;
+    cleanup(scratchDir: string): Promise<void>;
+    detect(): Promise<boolean>;
+}
+export declare class ADAPTER_NOT_IMPLEMENTED extends Error {
+    constructor(adapter: string, method: string);
+}

package/dist/services/adapter/adapter.js

@@ -0,0 +1,5 @@
+export class ADAPTER_NOT_IMPLEMENTED extends Error {
+    constructor(adapter, method) {
+        super(`ADAPTER_NOT_IMPLEMENTED: ${adapter}.${method} — stub until later slice`);
+    }
+}

package/dist/services/adapter/auto-adapter.d.ts

@@ -0,0 +1,11 @@
+import { Adapter } from "./adapter.js";
+type Detectable = Pick<Adapter, "name" | "detect">;
+export declare class AutoAdapter {
+    private readonly _o;
+    private readonly _adapters;
+    constructor(_o: {
+        home: string;
+    }, _adapters: Detectable[]);
+    detectAndPick(): Promise<Detectable>;
+}
+export {};

package/dist/services/adapter/auto-adapter.js

@@ -0,0 +1,15 @@
+export class AutoAdapter {
+    _o;
+    _adapters;
+    constructor(_o, _adapters) {
+        this._o = _o;
+        this._adapters = _adapters;
+    }
+    async detectAndPick() {
+        for (const a of this._adapters) {
+            if (await a.detect())
+                return a;
+        }
+        throw new Error("No adapter detected. Use `peaks skill adapter set-active <name>` to force one.");
+    }
+}

package/dist/services/adapter/claude-adapter.d.ts

@@ -0,0 +1,14 @@
+import { Adapter, AdapterEnvelope, AdapterSegment } from "./adapter.js";
+export declare class ClaudeAdapter implements Adapter {
+    private readonly opts;
+    readonly name: "claude";
+    constructor(opts: {
+        home: string;
+    });
+    detect(): Promise<boolean>;
+    resolveScratchDir(beeName: string): Promise<string>;
+    materialize(beeName: string, env: AdapterEnvelope, segments: AdapterSegment[]): Promise<string>;
+    publish(scratchDir: string): Promise<string>;
+    activate(_scratchDir: string): Promise<void>;
+    cleanup(scratchDir: string): Promise<void>;
+}

package/dist/services/adapter/claude-adapter.js

@@ -0,0 +1,40 @@
+import { writeFileSync, mkdirSync, rmSync, existsSync } from "node:fs";
+import { join } from "node:path";
+export class ClaudeAdapter {
+    opts;
+    name = "claude";
+    constructor(opts) {
+        this.opts = opts;
+    }
+    async detect() {
+        return true; /* Claude is the default; ship this slice first */
+    }
+    async resolveScratchDir(beeName) {
+        return join(this.opts.home, ".claude", "skills", `peaks-bee-${beeName}.peaks-generated`);
+    }
+    async materialize(beeName, env, segments) {
+        const dir = await this.resolveScratchDir(beeName);
+        if (existsSync(dir))
+            rmSync(dir, { recursive: true, force: true });
+        mkdirSync(dir, { recursive: true });
+        const frontmatter = `---\nname: peaks-bee-${beeName}\ndescription: peaks-loop generated bee ${beeName} — see local SkillHub for source\n---\n\n`;
+        const body = `${env.preamble}\n\n` + segments.map((s) => s.skillMd).join("\n\n");
+        writeFileSync(join(dir, "SKILL.md"), frontmatter + body);
+        mkdirSync(join(dir, "scripts"), { recursive: true });
+        for (const s of segments) {
+            for (const sc of s.scripts)
+                writeFileSync(join(dir, "scripts", sc.name), sc.content);
+        }
+        return dir;
+    }
+    async publish(scratchDir) {
+        return scratchDir;
+    }
+    async activate(_scratchDir) {
+        /* no-op; runtime picks up by convention */
+    }
+    async cleanup(scratchDir) {
+        if (existsSync(scratchDir))
+            rmSync(scratchDir, { recursive: true, force: true });
+    }
+}

package/dist/services/adapter/codex-adapter.d.ts

@@ -0,0 +1,14 @@
+import { Adapter } from "./adapter.js";
+export declare class CodexAdapter implements Pick<Adapter, "name"> {
+    private readonly _o;
+    readonly name: "codex";
+    constructor(_o: {
+        home: string;
+    });
+    detect(): Promise<boolean>;
+    resolveScratchDir(): Promise<void>;
+    materialize(): Promise<void>;
+    publish(): Promise<void>;
+    activate(): Promise<void>;
+    cleanup(): Promise<void>;
+}

package/dist/services/adapter/codex-adapter.js

@@ -0,0 +1,14 @@
+import { ADAPTER_NOT_IMPLEMENTED } from "./adapter.js";
+export class CodexAdapter {
+    _o;
+    name = "codex";
+    constructor(_o) {
+        this._o = _o;
+    }
+    async detect() { return false; }
+    async resolveScratchDir() { throw new ADAPTER_NOT_IMPLEMENTED("codex", "resolveScratchDir"); }
+    async materialize() { throw new ADAPTER_NOT_IMPLEMENTED("codex", "materialize"); }
+    async publish() { throw new ADAPTER_NOT_IMPLEMENTED("codex", "publish"); }
+    async activate() { throw new ADAPTER_NOT_IMPLEMENTED("codex", "activate"); }
+    async cleanup() { throw new ADAPTER_NOT_IMPLEMENTED("codex", "cleanup"); }
+}

package/dist/services/adapter/copilot-adapter.d.ts

@@ -0,0 +1,14 @@
+import { Adapter } from "./adapter.js";
+export declare class CopilotAdapter implements Pick<Adapter, "name"> {
+    private readonly _o;
+    readonly name: "copilot";
+    constructor(_o: {
+        home: string;
+    });
+    detect(): Promise<boolean>;
+    resolveScratchDir(): Promise<void>;
+    materialize(): Promise<void>;
+    publish(): Promise<void>;
+    activate(): Promise<void>;
+    cleanup(): Promise<void>;
+}

package/dist/services/adapter/copilot-adapter.js

@@ -0,0 +1,14 @@
+import { ADAPTER_NOT_IMPLEMENTED } from "./adapter.js";
+export class CopilotAdapter {
+    _o;
+    name = "copilot";
+    constructor(_o) {
+        this._o = _o;
+    }
+    async detect() { return false; }
+    async resolveScratchDir() { throw new ADAPTER_NOT_IMPLEMENTED("copilot", "resolveScratchDir"); }
+    async materialize() { throw new ADAPTER_NOT_IMPLEMENTED("copilot", "materialize"); }
+    async publish() { throw new ADAPTER_NOT_IMPLEMENTED("copilot", "publish"); }
+    async activate() { throw new ADAPTER_NOT_IMPLEMENTED("copilot", "activate"); }
+    async cleanup() { throw new ADAPTER_NOT_IMPLEMENTED("copilot", "cleanup"); }
+}

package/dist/services/artifacts/artifact-lint-service.d.ts

@@ -0,0 +1,23 @@
+import { type RequestArtifactRole } from './request-artifact-service.js';
+export type ArtifactLintSeverity = 'error' | 'warning';
+export type ArtifactLintFinding = {
+    line: number;
+    text: string;
+    reason: string;
+    severity: ArtifactLintSeverity;
+};
+export type ArtifactLintReport = {
+    ok: boolean;
+    role: RequestArtifactRole;
+    requestId: string;
+    path: string;
+    totalLines: number;
+    findings: ArtifactLintFinding[];
+};
+export type LintArtifactOptions = {
+    projectRoot: string;
+    role: RequestArtifactRole;
+    requestId: string;
+    sessionId?: string;
+};
+export declare function lintRequestArtifact(options: LintArtifactOptions): Promise<ArtifactLintReport | null>;

package/dist/services/artifacts/artifact-lint-service.js

@@ -0,0 +1,99 @@
+import { showRequestArtifact } from './request-artifact-service.js';
+const RULES = [
+    {
+        test: (line) => /<[A-Za-z][^>]*>/.test(line.trim()) && !/^\s*-?\s*linked-/i.test(line),
+        reason: 'Contains an unfilled <placeholder> token',
+        severity: 'error'
+    },
+    {
+        test: (line) => /^\s*-\s*\.\.\.\s*$/.test(line),
+        reason: 'Bullet point is only "..." — replace with real content',
+        severity: 'error'
+    },
+    {
+        test: (line) => /\bTBD\b|\bTODO\b|\bFIXME\b|\bXXX\b/.test(line),
+        reason: 'Contains TBD/TODO/FIXME/XXX marker',
+        severity: 'warning'
+    },
+    {
+        test: (line) => /^\s*-\s*$/.test(line),
+        reason: 'Empty bullet point — replace with real content or remove',
+        severity: 'warning'
+    }
+];
+// Lines that should never be flagged even if they match a rule (template scaffolding).
+const ALLOWLIST_PATTERNS = [
+    /^#+\s/, // markdown headers
+    /^\s*```/, // code fences
+    /^\s*-\s*last update:/i, // metadata
+    /^\s*-\s*created:/i,
+    /^\s*-\s*state:/i,
+    /^\s*-\s*type:\s*(feature|bugfix|refactor|docs|config|chore)\s*$/i,
+    /^\s*-\s*session:\s*[a-z0-9-]+/i,
+    /^\s*-\s*transition note/i // bypass / repair notes are not placeholders
+];
+function isAllowlisted(line) {
+    return ALLOWLIST_PATTERNS.some((pattern) => pattern.test(line));
+}
+/**
+ * Remove inline code spans (`...`) before applying placeholder rules. Content
+ * inside backticks is literal example text — e.g. a documented command syntax
+ * `peaks sop init <id>` — not an unfilled prose placeholder. Lint checks prose,
+ * not code, so a `<...>` token only counts when it appears outside code spans.
+ */
+function stripInlineCode(line) {
+    return line.replace(/`[^`]*`/g, '');
+}
+export async function lintRequestArtifact(options) {
+    const showOptions = {
+        projectRoot: options.projectRoot,
+        role: options.role,
+        requestId: options.requestId
+    };
+    if (options.sessionId !== undefined) {
+        showOptions.sessionId = options.sessionId;
+    }
+    const artifact = await showRequestArtifact(showOptions);
+    if (artifact === null) {
+        return null;
+    }
+    const lines = artifact.content.split(/\r?\n/);
+    const findings = [];
+    let insideFence = false;
+    for (let index = 0; index < lines.length; index += 1) {
+        const rawLine = lines[index];
+        if (rawLine === undefined)
+            continue;
+        // Fenced code blocks hold literal examples, not prose to fill; skip their
+        // contents entirely (the fence delimiters themselves toggle the state).
+        if (/^\s*```/.test(rawLine)) {
+            insideFence = !insideFence;
+            continue;
+        }
+        if (insideFence)
+            continue;
+        if (isAllowlisted(rawLine))
+            continue;
+        const testLine = stripInlineCode(rawLine);
+        for (const rule of RULES) {
+            if (rule.test(testLine)) {
+                findings.push({
+                    line: index + 1,
+                    text: rawLine.trim(),
+                    reason: rule.reason,
+                    severity: rule.severity
+                });
+                break;
+            }
+        }
+    }
+    const hasError = findings.some((finding) => finding.severity === 'error');
+    return {
+        ok: !hasError,
+        role: options.role,
+        requestId: options.requestId,
+        path: artifact.path,
+        totalLines: lines.length,
+        findings
+    };
+}

package/dist/services/artifacts/artifact-prerequisites.d.ts

@@ -0,0 +1,78 @@
+import type { RequestArtifactRole, RequestArtifactState } from './request-artifact-service.js';
+export type RequestType = 'feature' | 'bugfix' | 'refactor' | 'docs' | 'config' | 'chore';
+export declare const VALID_REQUEST_TYPES: ReadonlyArray<RequestType>;
+export declare const DEFAULT_REQUEST_TYPE: RequestType;
+export declare function isRequestType(value: string): value is RequestType;
+export type ArtifactPrerequisite = {
+    /** Relative path under `.peaks/_runtime/<session-id>/`. May contain `<rid>` placeholder. */
+    relativePath: string;
+    /** Human-readable description of what this artifact represents. */
+    description: string;
+    /** Optional content markers — when set, the file must contain ALL of these (case-insensitive substring). */
+    mustContain?: ReadonlyArray<string>;
+    /**
+     * Optional content markers — when set, the file must contain AT LEAST ONE of
+     * these (case-insensitive substring). Use this for escape-hatch patterns
+     * (e.g. perf-baseline's "Results table" OR "N/A — no perf surface" stub).
+     * `mustContain` and `mustContainAny` are independent: when both are set,
+     * `mustContain` markers must all be present AND at least one `mustContainAny`
+     * marker must be present.
+     */
+    mustContainAny?: ReadonlyArray<string>;
+    /**
+     * Slice 2.6.1.F: structural heading markers — when set, the file must
+     * contain ALL of these as markdown headings (line beginning with `#`–`###`
+     * followed by the marker, case-insensitive). This prevents a file from
+     * passing the gate by simply mentioning the marker as prose. Use this for
+     * section-anchored gates like the karpathy 4-guideline review.
+     * Independent of `mustContain` / `mustContainAny`.
+     */
+    headingMustContain?: ReadonlyArray<string>;
+    /**
+     * Slice v2.12.0 Group B Tier 5: optional legacy path that satisfies
+     * the same gate. When `relativePath` does not resolve on disk, the
+     * resolver tries this fallback path before reporting the prereq as
+     * missing. Use this for 1-minor-release back-compat windows where
+     * an old artifact location is still accepted alongside the new one.
+     * v2.13.0 should remove all `legacyRelativePath` entries.
+     *
+     * Body checks (`mustContain` / `mustContainAny` /
+     * `headingMustContain`) apply to whichever path resolved — the
+     * gate does not distinguish which path served the file.
+     */
+    legacyRelativePath?: string;
+};
+export type PrerequisiteCheckResult = {
+    ok: boolean;
+    missing: Array<{
+        path: string;
+        description: string;
+    }>;
+    /**
+     * v2.13.2 AC-5 — soft-block warnings. Each entry is a prereq
+     * path that is currently missing but is in a 1-minor-release
+     * back-compat window. The transition gate does not throw on
+     * `missing`-only (so legacy callers keep working) but surfaces the
+     * warning to the operator so they can plan the v2.14.0 hard cut.
+     */
+    warnings: Array<{
+        path: string;
+        code: string;
+        message: string;
+    }>;
+};
+export type CheckPrerequisitesOptions = {
+    projectRoot: string;
+    /**
+     * Durable scope of the artifact (the `.peaks/_runtime/<sessionId>/` directory
+     * the file lives in). The gate scans under `.peaks/_runtime/<sessionId>/<role>/`
+     * for prerequisite artifacts.
+     */
+    sessionId: string;
+    role: RequestArtifactRole;
+    newState: RequestArtifactState;
+    requestId: string;
+    requestType?: RequestType;
+};
+export declare function getPrerequisitesFor(role: RequestArtifactRole, newState: RequestArtifactState, requestType?: RequestType): ReadonlyArray<ArtifactPrerequisite>;
+export declare function checkPrerequisites(options: CheckPrerequisitesOptions): Promise<PrerequisiteCheckResult>;