peaks-loop 3.1.2 → 4.0.0-beta.10

package/dist/services/slice/slice-decompose-types.d.ts

@@ -0,0 +1,263 @@
+/**
+ * Type envelope for `peaks slice decompose` and its outputs.
+ *
+ * The slice-decomposition algorithm is a 6-stage deterministic function
+ * (see `peaks-code/references/slice-algorithm.md` for the full spec):
+ *
+ *   1. workUnitResolution  -- codegraph.query + knowledge_graph.grep
+ *   2. buildDependencyDAG  -- real import edges + codegraph.affected fallback
+ *   3. scc + criticalPath  -- Tarjan + longest_path on the condensation
+ *   4. minCut              -- Stoer-Wagner with semantic-preference weights
+ *   5. estimateWork        -- calibration-store (LoC+test heuristic v1)
+ *   6. emit                -- serialise DecompositionResult to JSON
+ *
+ * The pure function is `decomposeSlices(rid, prdMarkdown, projectRoot, options)`
+ * (exported from `slice-decompose-service.ts`). All types in this file are
+ * stable input/output contracts; do not change field names without a
+ * migration path because the JSON envelope is consumed by:
+ *
+ *   - `peaks slice pick` (reads candidates, spawns fzf)
+ *   - `peaks slice plan` (reads picked batch, calls peaks request init)
+ *   - `peaks-rd` and `peaks-qa` in unit tests
+ *   - user inspection via `cat .peaks/sc/slice-decomposition/<rid>.json`
+ *
+ * Codegraph is local project-analysis evidence; its output is
+ * **untrusted supporting evidence**, never authoritative for QA verdict.
+ * DecompositionResult fields derived from codegraph are tagged with
+ * `confidence: 'semantic' | 'structural'` so downstream consumers can
+ * discount structural-only cuts.
+ */
+export type EdgeKind = 'imports' | 'depends_on' | 'calls' | 'contains_flow' | 'flow_step';
+export interface WorkUnit {
+    /** Stable id within the decomposition; usually "W1".."Wn". */
+    id: string;
+    /** Human-readable label; shown in `peaks slice pick` fzf list. */
+    label: string;
+    /** Primary files this work unit touches (1-N). */
+    files: readonly string[];
+    /** Total LoC across all `files`. */
+    loc: number;
+    /** Number of test files this work unit adds (0 if none). */
+    testsAdded: number;
+    /** If any file in `files` pre-existed, the sum of delta-LoC; undefined if all files are new. */
+    deltaLoc?: number;
+    /** The primary file path; the algorithm picks the largest file as primary. */
+    filePath: string;
+    /** Graph node ids (file:<path> | function:<path>:<name>) that resolved this work unit. */
+    candidates: readonly string[];
+}
+export interface DependencyEdge {
+    from: string;
+    to: string;
+    kind: EdgeKind;
+    /**
+     * Edge weight for Stoer-Wagner. Lower weight = prefer to cut here.
+     * Locked values: flow_step=0.05, contains_flow=0.1, depends_on=5.0, calls=8.0, imports=10.0.
+     */
+    weight: number;
+    /** Human-readable evidence: the actual import statement or graph edge. */
+    evidence: string;
+    /** True iff kind is contains_flow or flow_step (i.e. from understand-anything). */
+    isSemantic: boolean;
+    /** 'semantic' if the edge came from understand-anything; 'structural' if from import-grep or codegraph. */
+    confidence: 'semantic' | 'structural';
+}
+export interface WorkEstimate {
+    complexitySum: number;
+    testCount: number;
+    locSum: number;
+    minutesP50: number;
+    minutesP90: number;
+    confidence: 'low' | 'medium' | 'high';
+    rationale: string;
+}
+export interface SliceCandidate {
+    rid: string;
+    label: string;
+    files: readonly string[];
+    testsAdded?: readonly string[];
+    estimate: WorkEstimate;
+    /** Domain anchor; "domain:<name>" if understand-anything indexed, else "file:<path>". */
+    semanticAnchor: string;
+}
+export interface ParallelBatch {
+    batch: number;
+    dependsOn: readonly number[];
+    slices: readonly SliceCandidate[];
+    parallelizableWithinBatch: boolean;
+}
+export interface SccAnalysis {
+    sccCount: number;
+    trivialSCCs: readonly string[];
+    nonTrivialSCCs: readonly string[];
+    condensationEdges: number;
+}
+export interface CriticalPath {
+    nodes: readonly string[];
+    edges: readonly string[];
+    totalLoc: number;
+    totalDeltaLoc: number;
+    rationale: string;
+}
+export interface MinCutEdge {
+    from: string;
+    to: string;
+    kind: EdgeKind;
+    weight: number;
+    isSemantic: boolean;
+    confidence: 'semantic' | 'structural';
+}
+export interface MinCutPartition {
+    name: string;
+    nodes: readonly string[];
+}
+export interface MinCutResult {
+    algorithm: string;
+    cutEdges: readonly MinCutEdge[];
+    partitions: readonly MinCutPartition[];
+}
+export interface CodegraphEnvelope {
+    nodes: number;
+    edges: number;
+    dbMB: number;
+    /** Git commit SHA at which the codegraph index was built, or 'unindexed'. */
+    freshness: string;
+    /** True iff codegraph.affected returned > 0 cross-file dependents. */
+    affectedCrossFile: boolean;
+    note: string;
+}
+export interface UnderstandAnythingEnvelope {
+    kgNodes: number;
+    kgEdges: number;
+    available: boolean;
+    fallback: 'semantic' | 'structural-only';
+    note: string;
+}
+export interface DecompositionResult {
+    rid: string;
+    /** ISO 8601 UTC, e.g. "2026-06-13T12:00:00.000Z". */
+    generatedAt: string;
+    codegraph: CodegraphEnvelope;
+    understandAnything: UnderstandAnythingEnvelope;
+    workUnits: readonly WorkUnit[];
+    dependencyDAG: {
+        edges: readonly DependencyEdge[];
+    };
+    sccAnalysis: SccAnalysis;
+    criticalPath: CriticalPath;
+    minCutResult: MinCutResult;
+    parallelBatches: readonly ParallelBatch[];
+    /** Free-form operator hint; e.g. "split into multiple pick sessions" when N > 10. */
+    pickHint?: string;
+}
+/**
+ * Per-run metrics for the 2.1.1 algorithm. Emitted only when
+ * `peaks slice decompose --benchmark` is passed. The shape is stable
+ * across algorithm versions so it can be diffed across runs.
+ */
+export interface SliceBenchmark {
+    rid: string;
+    totalMs: number;
+    /** Codegraph calls observed during the run (query + status + affected). */
+    codegraphQueries: number;
+    /** Distribution of slice estimate.confidence across all batches. */
+    p50ConfidenceDistribution: {
+        low: number;
+        mid: number;
+        high: number;
+    };
+    /** Approximate input bytes (PRD body + work-units + codegraph hits, post-load). */
+    inputApproxBytes: {
+        prd: number;
+    };
+    /** Bytes of the serialized decomposition JSON. */
+    outputJsonBytes: number;
+    capturedAt: string;
+}
+export interface DecomposeOptions {
+    /** When true, re-run `peaks codegraph index` before reading. */
+    refresh?: boolean;
+    /**
+     * Inject a codegraph-shell replacement. The default uses `peaks codegraph` CLI.
+     * Tests pass a function-returning-promise fake.
+     */
+    codegraphRunner?: CodegraphRunner;
+    /**
+     * Inject an understand-anything shell replacement. Default reads
+     * `.understand-anything/knowledge-graph.json` if present.
+     */
+    understandRunner?: UnderstandRunner;
+    /**
+     * Inject a function that returns the real import-edge set for a list of files.
+     * Default: spawns `git grep` + parses output. Tests pass a synchronous fake.
+     */
+    importEdgeRunner?: ImportEdgeRunner;
+}
+export interface CodegraphRunner {
+    query(text: string, projectRoot: string): Promise<readonly CodegraphQueryHit[]>;
+    affected(files: readonly string[], projectRoot: string): Promise<CodegraphAffectedResult>;
+    status(projectRoot: string): Promise<{
+        indexed: boolean;
+        nodes: number;
+        edges: number;
+        dbMB: number;
+        freshness: string;
+    }>;
+}
+export interface CodegraphQueryHit {
+    id: string;
+    kind: string;
+    name: string;
+    filePath: string;
+    score: number;
+    /** Optional LoC, when codegraph can report it; used for work estimates. */
+    loc?: number;
+}
+export interface CodegraphAffectedResult {
+    changedFiles: readonly string[];
+    affectedTests: readonly string[];
+    totalDependentsTraversed: number;
+}
+export interface UnderstandRunner {
+    /** Returns the parsed knowledge graph, or null if not indexed. */
+    read(projectRoot: string): Promise<KnowledgeGraph | null>;
+}
+export interface KnowledgeGraph {
+    nodes: readonly KgNode[];
+    edges: readonly KgEdge[];
+    layers: readonly {
+        id: string;
+        name: string;
+        nodeIds: readonly string[];
+    }[];
+}
+export type KgNodeType = 'file' | 'function' | 'class' | 'module' | 'concept' | 'config' | 'document' | 'service' | 'table' | 'endpoint' | 'pipeline' | 'schema' | 'resource' | 'domain' | 'flow' | 'step';
+export interface KgNode {
+    id: string;
+    type: KgNodeType;
+    name: string;
+    filePath?: string;
+    summary?: string;
+    tags: readonly string[];
+    complexity?: number;
+}
+export interface KgEdge {
+    source: string;
+    target: string;
+    type: string;
+    weight?: number;
+}
+export interface ImportEdgeRunner {
+    /**
+     * Returns real static import edges for the given file paths.
+     * For each file, parses the `import ... from '...'` statements and resolves
+     * relative paths to project-relative paths.
+     * Output: array of {from, to, evidence} where `evidence` is the import line.
+     */
+    importsOf(projectRoot: string, files: readonly string[]): Promise<readonly ImportEdge[]>;
+}
+export interface ImportEdge {
+    from: string;
+    to: string;
+    evidence: string;
+}

package/dist/services/slice/slice-decompose-types.js

@@ -0,0 +1,30 @@
+/**
+ * Type envelope for `peaks slice decompose` and its outputs.
+ *
+ * The slice-decomposition algorithm is a 6-stage deterministic function
+ * (see `peaks-code/references/slice-algorithm.md` for the full spec):
+ *
+ *   1. workUnitResolution  -- codegraph.query + knowledge_graph.grep
+ *   2. buildDependencyDAG  -- real import edges + codegraph.affected fallback
+ *   3. scc + criticalPath  -- Tarjan + longest_path on the condensation
+ *   4. minCut              -- Stoer-Wagner with semantic-preference weights
+ *   5. estimateWork        -- calibration-store (LoC+test heuristic v1)
+ *   6. emit                -- serialise DecompositionResult to JSON
+ *
+ * The pure function is `decomposeSlices(rid, prdMarkdown, projectRoot, options)`
+ * (exported from `slice-decompose-service.ts`). All types in this file are
+ * stable input/output contracts; do not change field names without a
+ * migration path because the JSON envelope is consumed by:
+ *
+ *   - `peaks slice pick` (reads candidates, spawns fzf)
+ *   - `peaks slice plan` (reads picked batch, calls peaks request init)
+ *   - `peaks-rd` and `peaks-qa` in unit tests
+ *   - user inspection via `cat .peaks/sc/slice-decomposition/<rid>.json`
+ *
+ * Codegraph is local project-analysis evidence; its output is
+ * **untrusted supporting evidence**, never authoritative for QA verdict.
+ * DecompositionResult fields derived from codegraph are tagged with
+ * `confidence: 'semantic' | 'structural'` so downstream consumers can
+ * discount structural-only cuts.
+ */
+export {};

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;