peaks-loop 4.1.1 → 4.1.3

package/dist/services/readonly-surface/readonly-whitelist.d.ts

@@ -0,0 +1,147 @@
+import { z } from 'zod';
+/** Where the generator writes the artifact, relative to the package root. */
+export declare const READONLY_WHITELIST_RELATIVE_PATH = "contracts/readonly-argv-whitelist.json";
+declare const PlaceholderSpecSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        enum: "enum";
+        path: "path";
+        token: "token";
+        slug: "slug";
+        integer: "integer";
+    }>;
+    pattern: z.ZodOptional<z.ZodString>;
+    values: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    min: z.ZodOptional<z.ZodNumber>;
+    max: z.ZodOptional<z.ZodNumber>;
+    default: z.ZodOptional<z.ZodNumber>;
+    binding: z.ZodObject<{
+        kind: z.ZodEnum<{
+            option: "option";
+            positional: "positional";
+        }>;
+        token: z.ZodString;
+        required: z.ZodBoolean;
+    }, z.core.$strip>;
+    constraintSource: z.ZodEnum<{
+        introspected: "introspected";
+        handwritten: "handwritten";
+    }>;
+}, z.core.$strip>;
+declare const EntrySchema: z.ZodObject<{
+    id: z.ZodString;
+    tool: z.ZodString;
+    commandPath: z.ZodArray<z.ZodString>;
+    argv: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+        kind: z.ZodLiteral<"literal">;
+        value: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"param">;
+        name: z.ZodString;
+    }, z.core.$strip>]>>;
+    params: z.ZodRecord<z.ZodString, z.ZodObject<{
+        type: z.ZodEnum<{
+            enum: "enum";
+            path: "path";
+            token: "token";
+            slug: "slug";
+            integer: "integer";
+        }>;
+        pattern: z.ZodOptional<z.ZodString>;
+        values: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        min: z.ZodOptional<z.ZodNumber>;
+        max: z.ZodOptional<z.ZodNumber>;
+        default: z.ZodOptional<z.ZodNumber>;
+        binding: z.ZodObject<{
+            kind: z.ZodEnum<{
+                option: "option";
+                positional: "positional";
+            }>;
+            token: z.ZodString;
+            required: z.ZodBoolean;
+        }, z.core.$strip>;
+        constraintSource: z.ZodEnum<{
+            introspected: "introspected";
+            handwritten: "handwritten";
+        }>;
+    }, z.core.$strip>>;
+    introspection: z.ZodObject<{
+        optionTokens: z.ZodArray<z.ZodString>;
+        positionalCount: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+declare const WhitelistSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    source: z.ZodString;
+    readOnlyDefinition: z.ZodString;
+    entries: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        tool: z.ZodString;
+        commandPath: z.ZodArray<z.ZodString>;
+        argv: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+            kind: z.ZodLiteral<"literal">;
+            value: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"param">;
+            name: z.ZodString;
+        }, z.core.$strip>]>>;
+        params: z.ZodRecord<z.ZodString, z.ZodObject<{
+            type: z.ZodEnum<{
+                enum: "enum";
+                path: "path";
+                token: "token";
+                slug: "slug";
+                integer: "integer";
+            }>;
+            pattern: z.ZodOptional<z.ZodString>;
+            values: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            min: z.ZodOptional<z.ZodNumber>;
+            max: z.ZodOptional<z.ZodNumber>;
+            default: z.ZodOptional<z.ZodNumber>;
+            binding: z.ZodObject<{
+                kind: z.ZodEnum<{
+                    option: "option";
+                    positional: "positional";
+                }>;
+                token: z.ZodString;
+                required: z.ZodBoolean;
+            }, z.core.$strip>;
+            constraintSource: z.ZodEnum<{
+                introspected: "introspected";
+                handwritten: "handwritten";
+            }>;
+        }, z.core.$strip>>;
+        introspection: z.ZodObject<{
+            optionTokens: z.ZodArray<z.ZodString>;
+            positionalCount: z.ZodNumber;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PlaceholderSpec = z.infer<typeof PlaceholderSpecSchema>;
+export type ReadOnlyWhitelistEntry = z.infer<typeof EntrySchema>;
+export type ReadOnlyWhitelist = z.infer<typeof WhitelistSchema>;
+/** Absolute path of the generated artifact for a package root. */
+export declare function resolveReadOnlyWhitelistPath(root?: string): string;
+/** Parse + validate the artifact text. Throws a zod error when the shape drifts. */
+export declare function parseReadOnlyWhitelist(text: string): ReadOnlyWhitelist;
+/** Read + validate the artifact. The only supported way to obtain it. */
+export declare function loadReadOnlyWhitelist(root?: string): ReadOnlyWhitelist;
+/** The param names an entry expects, in argv order. */
+export declare function paramNamesOf(entry: ReadOnlyWhitelistEntry): string[];
+/**
+ * The tool names the surface declares, in first-appearance order.
+ *
+ * This is the pre-tool interceptor's view of "what may be called", and it is
+ * computed HERE rather than in the MCP module on purpose: the interceptor must
+ * keep working when `src/services/mcp/` is deleted (spec §1), so it cannot reach
+ * into it for the answer. Grouping the entries by their `tool` field is the whole
+ * computation, and both readers do it from the same DATA.
+ */
+export declare function toolIdsOf(whitelist: ReadOnlyWhitelist): string[];
+/**
+ * Match a CONCRETE argv against the entries. A param slot consumes exactly one
+ * token, so `--apply` in a param slot still MATCHES here - refusing it is the
+ * validator's job (`argv-guard.ts`), not the matcher's. Keeping the two separate
+ * is what stops a rejected value from silently re-routing to another entry.
+ */
+export declare function matchReadOnlyEntry(whitelist: ReadOnlyWhitelist, argv: readonly string[]): ReadOnlyWhitelistEntry | undefined;
+export {};

package/dist/services/readonly-surface/readonly-whitelist.js

@@ -0,0 +1,107 @@
+/**
+ * The read-only argv whitelist, as DATA.
+ *
+ * WHY THIS IS A LOADER AND NOT AN IMPORT. The generated whitelist is read by two
+ * consumers that must survive the removal of the MCP module (spec §1): the
+ * pre-tool interceptor and, later, the MCP server. If either `import`ed the
+ * generated artifact it would become a static edge between them, and deleting
+ * the MCP module would break the gate. So the artifact stays a `.json` file and
+ * every reader goes through the filesystem. `tests/unit/standards/no-mcp-source-import.test.ts`
+ * pins that no module may `import` it.
+ *
+ * The shape is `{ schemaVersion, source, readOnlyDefinition, entries[] }`. Each
+ * entry is a full argv template (flags included) plus typed placeholders - the
+ * key is the WHOLE argv, never the top-level verb, because each named command
+ * family mixes read and write subcommands.
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { repoRoot } from 'peaks-loop-shared/paths';
+/** Where the generator writes the artifact, relative to the package root. */
+export const READONLY_WHITELIST_RELATIVE_PATH = 'contracts/readonly-argv-whitelist.json';
+const PlaceholderBindingSchema = z.object({
+    /** `option` when the value is the argument of a flag, `positional` otherwise. */
+    kind: z.enum(['option', 'positional']),
+    /** The flag token (`--role`) or the positional name (`request-id`). */
+    token: z.string().min(1),
+    required: z.boolean()
+});
+const PlaceholderSpecSchema = z.object({
+    type: z.enum(['slug', 'enum', 'token', 'integer', 'path']),
+    pattern: z.string().min(1).optional(),
+    values: z.array(z.string().min(1)).min(1).optional(),
+    min: z.number().int().optional(),
+    max: z.number().int().optional(),
+    default: z.number().int().optional(),
+    /**
+     * Where the placeholder lives and whether the REGISTRY makes it mandatory.
+     * A placeholder present in the template is always supplied a value; this
+     * field carries the introspected fact, not the template's demand.
+     */
+    binding: PlaceholderBindingSchema,
+    /** `introspected` when the registry supplied the constraint, else `handwritten`. */
+    constraintSource: z.enum(['introspected', 'handwritten'])
+});
+const ArgvSegmentSchema = z.union([
+    z.object({ kind: z.literal('literal'), value: z.string().min(1) }),
+    z.object({ kind: z.literal('param'), name: z.string().min(1) })
+]);
+const EntrySchema = z.object({
+    id: z.string().min(1),
+    tool: z.string().min(1),
+    commandPath: z.array(z.string().min(1)).min(1),
+    argv: z.array(ArgvSegmentSchema).min(1),
+    params: z.record(z.string(), PlaceholderSpecSchema),
+    introspection: z.object({
+        optionTokens: z.array(z.string().min(1)),
+        positionalCount: z.number().int().gte(0)
+    })
+});
+const WhitelistSchema = z.object({
+    schemaVersion: z.literal(1),
+    source: z.string().min(1),
+    readOnlyDefinition: z.string().min(1),
+    entries: z.array(EntrySchema).min(1)
+});
+/** Absolute path of the generated artifact for a package root. */
+export function resolveReadOnlyWhitelistPath(root = repoRoot) {
+    return join(root, READONLY_WHITELIST_RELATIVE_PATH);
+}
+/** Parse + validate the artifact text. Throws a zod error when the shape drifts. */
+export function parseReadOnlyWhitelist(text) {
+    return WhitelistSchema.parse(JSON.parse(text));
+}
+/** Read + validate the artifact. The only supported way to obtain it. */
+export function loadReadOnlyWhitelist(root = repoRoot) {
+    return parseReadOnlyWhitelist(readFileSync(resolveReadOnlyWhitelistPath(root), 'utf8'));
+}
+/** The param names an entry expects, in argv order. */
+export function paramNamesOf(entry) {
+    return entry.argv.flatMap((segment) => (segment.kind === 'param' ? [segment.name] : []));
+}
+/**
+ * The tool names the surface declares, in first-appearance order.
+ *
+ * This is the pre-tool interceptor's view of "what may be called", and it is
+ * computed HERE rather than in the MCP module on purpose: the interceptor must
+ * keep working when `src/services/mcp/` is deleted (spec §1), so it cannot reach
+ * into it for the answer. Grouping the entries by their `tool` field is the whole
+ * computation, and both readers do it from the same DATA.
+ */
+export function toolIdsOf(whitelist) {
+    return [...new Set(whitelist.entries.map((entry) => entry.tool))];
+}
+/**
+ * Match a CONCRETE argv against the entries. A param slot consumes exactly one
+ * token, so `--apply` in a param slot still MATCHES here - refusing it is the
+ * validator's job (`argv-guard.ts`), not the matcher's. Keeping the two separate
+ * is what stops a rejected value from silently re-routing to another entry.
+ */
+export function matchReadOnlyEntry(whitelist, argv) {
+    return whitelist.entries.find((entry) => {
+        if (entry.argv.length !== argv.length)
+            return false;
+        return entry.argv.every((segment, index) => segment.kind === 'literal' ? segment.value === argv[index] : true);
+    });
+}

package/dist/services/readonly-surface/whitelist-generator.d.ts

@@ -0,0 +1,64 @@
+import type { Command } from 'commander';
+import { z } from 'zod';
+import { type ReadOnlyWhitelist } from './readonly-whitelist.js';
+/** The hand-authored input, relative to the package root. */
+export declare const READONLY_SURFACE_RELATIVE_PATH = "contracts/readonly-surface.json";
+/** The schema version of the artifact this module emits. */
+export declare const READONLY_WHITELIST_SCHEMA_VERSION = 1;
+declare const SurfaceEntrySchema: z.ZodObject<{
+    id: z.ZodString;
+    commandPath: z.ZodArray<z.ZodString>;
+    argv: z.ZodArray<z.ZodString>;
+    params: z.ZodRecord<z.ZodString, z.ZodObject<{
+        type: z.ZodEnum<{
+            enum: "enum";
+            path: "path";
+            token: "token";
+            slug: "slug";
+            integer: "integer";
+        }>;
+        pattern: z.ZodOptional<z.ZodString>;
+        values: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        min: z.ZodOptional<z.ZodNumber>;
+        max: z.ZodOptional<z.ZodNumber>;
+        default: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const ReadOnlySurfaceSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    readOnlyDefinition: z.ZodString;
+    note: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    tools: z.ZodArray<z.ZodObject<{
+        tool: z.ZodString;
+        entries: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            commandPath: z.ZodArray<z.ZodString>;
+            argv: z.ZodArray<z.ZodString>;
+            params: z.ZodRecord<z.ZodString, z.ZodObject<{
+                type: z.ZodEnum<{
+                    enum: "enum";
+                    path: "path";
+                    token: "token";
+                    slug: "slug";
+                    integer: "integer";
+                }>;
+                pattern: z.ZodOptional<z.ZodString>;
+                values: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                min: z.ZodOptional<z.ZodNumber>;
+                max: z.ZodOptional<z.ZodNumber>;
+                default: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ReadOnlySurface = z.infer<typeof ReadOnlySurfaceSchema>;
+export type ReadOnlySurfaceEntry = z.infer<typeof SurfaceEntrySchema>;
+/** Build the artifact object from a surface declaration and a live program. */
+export declare function generateReadOnlyWhitelist(surface: ReadOnlySurface, program: Command): ReadOnlyWhitelist;
+/** Byte-stable serialization: two runs over the same input MUST match. */
+export declare function serializeReadOnlyWhitelist(whitelist: ReadOnlyWhitelist): string;
+/** Read + validate the hand-authored surface declaration. */
+export declare function loadReadOnlySurface(root?: string): ReadOnlySurface;
+/** Absolute path of the generated artifact. */
+export declare function readonlyWhitelistPath(root?: string): string;
+export {};

package/dist/services/readonly-surface/whitelist-generator.js

@@ -0,0 +1,212 @@
+/**
+ * The schema introspector (spec §3 row 2): turns the hand-authored surface
+ * declaration into the generated whitelist artifact by READING the live Commander
+ * registry - never by restating it.
+ *
+ * Everything the registry can answer is taken from it:
+ *   - does the command path exist,
+ *   - does each `--flag` in the template exist on that command,
+ *   - is that flag mandatory, and does it take a value,
+ *   - which positionals does the command declare, and are they required.
+ * A template that disagrees with the registry is a BUILD FAILURE, not a warning:
+ * that is the whole point of generating the artifact instead of typing it.
+ *
+ * What the registry CANNOT answer is the constraint on a placeholder's value
+ * (`^[a-z0-9-]+$` for a request id). Those constraints come from the surface file
+ * and are marked `constraintSource: 'handwritten'`, so the one place drift can
+ * enter is visible in the artifact. When a command later declares `.choices()`,
+ * the same field flips to `introspected` with no artifact edit.
+ *
+ * DETERMINISM: no timestamps, no `Date`, no unordered iteration. Record
+ * keys follow argv order and entries follow the surface file's order, so two
+ * consecutive runs are byte-identical.
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { repoRoot } from 'peaks-loop-shared/paths';
+import { READONLY_WHITELIST_RELATIVE_PATH } from './readonly-whitelist.js';
+/** The hand-authored input, relative to the package root. */
+export const READONLY_SURFACE_RELATIVE_PATH = 'contracts/readonly-surface.json';
+/** The schema version of the artifact this module emits. */
+export const READONLY_WHITELIST_SCHEMA_VERSION = 1;
+const SurfaceParamSchema = z.object({
+    type: z.enum(['slug', 'enum', 'token', 'integer', 'path']),
+    pattern: z.string().min(1).optional(),
+    values: z.array(z.string().min(1)).min(1).optional(),
+    min: z.number().int().optional(),
+    max: z.number().int().optional(),
+    default: z.number().int().optional()
+});
+const SurfaceEntrySchema = z.object({
+    id: z.string().min(1),
+    commandPath: z.array(z.string().min(1)).min(1),
+    argv: z.array(z.string().min(1)).min(1),
+    params: z.record(z.string(), SurfaceParamSchema)
+});
+export const ReadOnlySurfaceSchema = z.object({
+    schemaVersion: z.literal(1),
+    readOnlyDefinition: z.string().min(1),
+    note: z.array(z.string()).default([]),
+    tools: z.array(z.object({ tool: z.string().min(1), entries: z.array(SurfaceEntrySchema).min(1) }))
+});
+/** `<name>` marks a placeholder token in a surface `argv` element. */
+const PLACEHOLDER_TOKEN = /^<([a-z][a-z0-9-]*)>$/;
+class SurfaceDriftError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'SurfaceDriftError';
+    }
+}
+function resolveCommand(program, path) {
+    let current = program;
+    for (const name of path) {
+        current = current.commands.find((candidate) => candidate.name() === name);
+        if (current === undefined) {
+            throw new SurfaceDriftError(`No command registered at path: ${path.join(' ')}`);
+        }
+    }
+    return current;
+}
+function hasOption(command, token) {
+    return command.options.some((option) => option.long === token || option.short === token);
+}
+function optionTakingValue(command, token) {
+    return command.options.find((option) => {
+        if (option.long !== token && option.short !== token)
+            return false;
+        return /[<[].+[>\]]/.test(option.flags);
+    });
+}
+/** Placeholders the registry supplies a constraint for are marked as such. */
+function constraintSourceOf(declared, option) {
+    if (declared.type === 'enum' && option?.argChoices !== undefined)
+        return 'introspected';
+    if (option?.defaultValue !== undefined && declared.default !== undefined)
+        return 'introspected';
+    return 'handwritten';
+}
+/** The constraint fields the surface declares, copied without inventing absent ones. */
+function constraintsOf(declared) {
+    return {
+        type: declared.type,
+        ...(declared.pattern === undefined ? {} : { pattern: declared.pattern }),
+        ...(declared.values === undefined ? {} : { values: declared.values }),
+        ...(declared.min === undefined ? {} : { min: declared.min }),
+        ...(declared.max === undefined ? {} : { max: declared.max }),
+        ...(declared.default === undefined ? {} : { default: declared.default })
+    };
+}
+/**
+ * Bind one placeholder either to the value-taking flag before it or to the next
+ * positional the command declares. Membership in the template is what makes a
+ * value required; `binding.required` carries the REGISTRY's opinion, which is a
+ * different fact (`--limit` is not mandatory, yet the template pins it).
+ */
+function bindPlaceholder(slot) {
+    const { entryId, name, declared, command, previousToken, cursor } = slot;
+    if (declared === undefined) {
+        throw new SurfaceDriftError(`Entry ${entryId}: placeholder <${name}> has no params spec`);
+    }
+    const boundOption = previousToken === undefined ? undefined : optionTakingValue(command, previousToken);
+    if (boundOption !== undefined && previousToken !== undefined) {
+        return {
+            ...constraintsOf(declared),
+            binding: { kind: 'option', token: previousToken, required: boundOption.mandatory },
+            constraintSource: constraintSourceOf(declared, boundOption)
+        };
+    }
+    const registered = command.registeredArguments[cursor.positionalIndex];
+    if (registered === undefined) {
+        throw new SurfaceDriftError(`Entry ${entryId}: <${name}> is positional ${cursor.positionalIndex + 1} but the command declares ${command.registeredArguments.length}`);
+    }
+    cursor.positionalIndex += 1;
+    cursor.positionalNames.push(registered.name());
+    return {
+        ...constraintsOf(declared),
+        binding: { kind: 'positional', token: registered.name(), required: registered.required },
+        constraintSource: 'handwritten'
+    };
+}
+/** The non-flag words a template opens with, which must be the command path. */
+function leadingLiteralsOf(argv) {
+    return argv.flatMap((segment) => segment.kind === 'literal' && !segment.value.startsWith('-') ? [segment.value] : []);
+}
+function assertTemplateDrivesCommand(surface, command, argv, cursor) {
+    const leading = leadingLiteralsOf(argv);
+    if (leading.join('\u0000') !== surface.commandPath.join('\u0000')) {
+        throw new SurfaceDriftError(`Entry ${surface.id}: argv opens with [${leading.join(', ')}] but commandPath is [${surface.commandPath.join(', ')}]`);
+    }
+    if (cursor.positionalIndex !== command.registeredArguments.length) {
+        throw new SurfaceDriftError(`Entry ${surface.id}: template fills ${cursor.positionalIndex} positional(s); ${surface.commandPath.join(' ')} declares ${command.registeredArguments.length}`);
+    }
+}
+function buildEntry(program, tool, surface) {
+    const command = resolveCommand(program, surface.commandPath);
+    const optionTokens = [];
+    const argv = [];
+    const params = {};
+    const cursor = { positionalIndex: 0, positionalNames: [] };
+    for (let index = 0; index < surface.argv.length; index += 1) {
+        const token = surface.argv[index];
+        if (token === undefined)
+            continue;
+        const placeholder = PLACEHOLDER_TOKEN.exec(token);
+        const name = placeholder?.[1];
+        if (placeholder !== null && name !== undefined) {
+            params[name] = bindPlaceholder({
+                entryId: surface.id,
+                name,
+                declared: surface.params[name],
+                command,
+                previousToken: index > 0 ? surface.argv[index - 1] : undefined,
+                cursor
+            });
+            argv.push({ kind: 'param', name });
+            continue;
+        }
+        if (token.startsWith('-')) {
+            if (!hasOption(command, token)) {
+                throw new SurfaceDriftError(`Entry ${surface.id}: no such option ${token} on ${surface.commandPath.join(' ')}`);
+            }
+            optionTokens.push(token);
+        }
+        argv.push({ kind: 'literal', value: token });
+    }
+    assertTemplateDrivesCommand(surface, command, argv, cursor);
+    return {
+        id: surface.id,
+        tool,
+        commandPath: [...surface.commandPath],
+        argv,
+        params,
+        introspection: { optionTokens, positionalCount: cursor.positionalNames.length }
+    };
+}
+/** Build the artifact object from a surface declaration and a live program. */
+export function generateReadOnlyWhitelist(surface, program) {
+    const entries = surface.tools.flatMap((group) => group.entries.map((entry) => buildEntry(program, group.tool, entry)));
+    const ids = new Set(entries.map((entry) => entry.id));
+    if (ids.size !== entries.length) {
+        throw new SurfaceDriftError('Entry ids must be unique across the whole surface');
+    }
+    return {
+        schemaVersion: READONLY_WHITELIST_SCHEMA_VERSION,
+        source: READONLY_SURFACE_RELATIVE_PATH,
+        readOnlyDefinition: surface.readOnlyDefinition,
+        entries
+    };
+}
+/** Byte-stable serialization: two runs over the same input MUST match. */
+export function serializeReadOnlyWhitelist(whitelist) {
+    return `${JSON.stringify(whitelist, null, 2)}\n`;
+}
+/** Read + validate the hand-authored surface declaration. */
+export function loadReadOnlySurface(root = repoRoot) {
+    const text = readFileSync(join(root, READONLY_SURFACE_RELATIVE_PATH), 'utf8');
+    return ReadOnlySurfaceSchema.parse(JSON.parse(text));
+}
+/** Absolute path of the generated artifact. */
+export function readonlyWhitelistPath(root = repoRoot) {
+    return join(root, READONLY_WHITELIST_RELATIVE_PATH);
+}

package/dist/services/recommendations/installed-capability-detector.d.ts

@@ -3,7 +3,6 @@
  * detector for the capability catalog (`peaks capability status` /
  * `peaks capabilities --source ...`).
  *
- * Slice B1 of 2026-09-09-ecc-dynamic-and-cleanup: the previous
  * `getInstalledCapabilityIds()` returned `[]` unconditionally, so the
  * catalog could never report anything as installed. This module answers
  * the question from evidence that already exists on disk — no install

package/dist/services/recommendations/installed-capability-detector.js

@@ -3,7 +3,6 @@
  * detector for the capability catalog (`peaks capability status` /
  * `peaks capabilities --source ...`).
  *
- * Slice B1 of 2026-09-09-ecc-dynamic-and-cleanup: the previous
  * `getInstalledCapabilityIds()` returned `[]` unconditionally, so the
  * catalog could never report anything as installed. This module answers
  * the question from evidence that already exists on disk — no install

package/dist/services/release/version-precheck-service.d.ts

@@ -1,12 +1,10 @@
 /**
- * rid-010 — peaks release precheck (Phase 4 slice 1).
  *
  * Module path: src/services/release/version-precheck-service.ts
  * Mirrors publish.yml gate-cli-version §(A) — verified in code 2026-10-03, not
  * just per the old comment: `runRootVsShared` covers §(A)'s shared-dist check;
  * §(A′) (runtime RUNTIME_VERSION) has no layer here, and the §(B)
  * tarball-content gate (Layer 5 of the 5-layer root cause) stays CI-only —
- * AC-7 grep test pins publish.yml so §(B) cannot drift silently.
  *
  * 4-layer version precheck. Designed to run BEFORE `peaks release canary` so
  * developers catch CLI_VERSION lag / tag collision / changeset staged /

package/dist/services/release/version-precheck-service.js

@@ -1,12 +1,10 @@
 /**
- * rid-010 — peaks release precheck (Phase 4 slice 1).
  *
  * Module path: src/services/release/version-precheck-service.ts
  * Mirrors publish.yml gate-cli-version §(A) — verified in code 2026-10-03, not
  * just per the old comment: `runRootVsShared` covers §(A)'s shared-dist check;
  * §(A′) (runtime RUNTIME_VERSION) has no layer here, and the §(B)
  * tarball-content gate (Layer 5 of the 5-layer root cause) stays CI-only —
- * AC-7 grep test pins publish.yml so §(B) cannot drift silently.
  *
  * 4-layer version precheck. Designed to run BEFORE `peaks release canary` so
  * developers catch CLI_VERSION lag / tag collision / changeset staged /
@@ -54,7 +52,6 @@ export function runRootVsShared(opts) {
     try {
         const raw = readFileSync(sharedDist, 'utf8');
         // Quote-tolerant: the old double-quote-only regex blanked on prettier's
-        // single-quoted emit (rid 2026-10-03-release-gate-quote-brittle).
         const match = raw.match(/CLI_VERSION\s*=\s*(?:"([^"]+)"|'([^']+)'|`([^`]+)`)/);
         const captured = match?.[1] ?? match?.[2] ?? match?.[3];
         if (captured !== undefined) {

package/dist/services/retrospective/retrospective-index.d.ts

@@ -2,7 +2,6 @@
  * retrospective-index — load `.peaks/retrospective/index.json`, parse to
  * `RetrospectiveEntry[]`, return the index envelope.
  *
- * Slice 023 (R3). Pure read on the hot path: a single `fs.readFile` of
  * the index, no MD-tree fallback. The migration script (G9) is the only
  * writer; this loader is read-only.
  */

package/dist/services/retrospective/retrospective-index.js

@@ -2,7 +2,6 @@
  * retrospective-index — load `.peaks/retrospective/index.json`, parse to
  * `RetrospectiveEntry[]`, return the index envelope.
  *
- * Slice 023 (R3). Pure read on the hot path: a single `fs.readFile` of
  * the index, no MD-tree fallback. The migration script (G9) is the only
  * writer; this loader is read-only.
  */

package/dist/services/retrospective/retrospective-show.d.ts

@@ -3,7 +3,6 @@
  * body on-demand from `artifactPaths` (concatenate with `---` separator),
  * apply `formatMdCompact` by default, return the JSON envelope.
  *
- * Slice 023 (R3). The on-disk MD form is gone after the G9 migration; the
  * body is re-hydrated from the source PRD / RD / QA / TXT artifacts. If
  * a referenced artifact is missing on disk, `show` returns a
  * `ARTIFACT_MISSING` envelope (PRD R3) and does not crash.

package/dist/services/retrospective/retrospective-show.js

@@ -3,7 +3,6 @@
  * body on-demand from `artifactPaths` (concatenate with `---` separator),
  * apply `formatMdCompact` by default, return the JSON envelope.
  *
- * Slice 023 (R3). The on-disk MD form is gone after the G9 migration; the
  * body is re-hydrated from the source PRD / RD / QA / TXT artifacts. If
  * a referenced artifact is missing on disk, `show` returns a
  * `ARTIFACT_MISSING` envelope (PRD R3) and does not crash.

package/dist/services/reviewer/model-family.js

@@ -1,6 +1,5 @@
 /**
  * model-family.ts — derive `modelFamily` from a `modelId` for the G4
- * third-party reviewer. AC-4.4 requires that
  * `third-party-review.json.modelFamily !== karpathy-review.json.modelFamily`,
  * so the family bucket must be stable, provider-distinguishing, and
  * version-tolerant (e.g. `claude-opus-4-8` and `claude-haiku-4-5` both

package/dist/services/reviewer/reviewer-config.js

@@ -1,6 +1,5 @@
 /**
  * reviewer-config.ts — load the `reviewer` section from
- * `~/.peaks/config.json`. AC-4.1 mandates:
  *   - providers[] (>=2 entries; ollama / anthropic / openai supported)
  *   - selection: 'round-robin' | 'hash(rid)' | 'random'
  *   - rdProviderName: string | null

package/dist/services/reviewer/reviewer-service.d.ts

@@ -16,7 +16,6 @@ export declare function extractFirstJsonObject(text: string): unknown | null;
 export declare function runReviewer(input: ReviewerRunInput): Promise<ReviewerRunOutput>;
 /**
  * Compute the distinctness verdict: returns true when the third-party
- * reviewer's modelFamily differs from the karpathy reviewer's. AC-4.4
  * mandates this is a CI gate — equality fails the build.
  */
 export declare function distinctFromKarpathy(thirdPartyFamily: string, karpathyFamily: string): boolean;

package/dist/services/reviewer/reviewer-service.js

@@ -1,7 +1,6 @@
 /**
  * reviewer-service.ts — orchestrator for the G4 third-party reviewer.
  *
- * Flow (per AC-4.1 .. AC-4.6):
  *   1. Load `reviewer` section from `~/.peaks/config.json` (reviewer-config).
  *      Missing section => `{ ok: false, reason: 'no-reviewer-config' }`.
  *   2. Pick a provider by selection mode (round-robin / hash / random).
@@ -243,7 +242,6 @@ export async function runReviewer(input) {
         };
     }
     // Stamp modelFamily from the actual modelId we called — prevents the LLM
-    // from lying about its family and bypassing AC-4.4.
     const stamped = {
         ...validated,
         modelId: result.provider.model,
@@ -254,7 +252,6 @@ export async function runReviewer(input) {
 }
 /**
  * Compute the distinctness verdict: returns true when the third-party
- * reviewer's modelFamily differs from the karpathy reviewer's. AC-4.4
  * mandates this is a CI gate — equality fails the build.
  */
 export function distinctFromKarpathy(thirdPartyFamily, karpathyFamily) {