peaks-loop 3.0.0

package/dist/src/services/context/context-guard.js

@@ -0,0 +1,91 @@
+/**
+ * G9 — forced compression gate (RL-27..RL-32).
+ *
+ * The CLI 兜底 layer. Validates prompt size against the threshold
+ * table in `threshold.ts` and returns a decision. The PreToolUse hook
+ * layer (`peaks sub-agent-dispatch-guard`) re-runs the same logic
+ * without `--force` (RL-30 strict).
+ *
+ * Decision codes:
+ *   - `OK`                          — under 50%
+ *   - `CONTEXT_SOFT_WARN`           — 50-75%, suggest --use-headroom
+ *   - `CONTEXT_NEAR_LIMIT`          — 75-80%, mandatory --use-headroom suggestion
+ *   - `PROMPT_TOO_LARGE`            — 80-90%, hard reject (allow = false)
+ *   - `PROMPT_EMERGENCY`            — ≥ 90%, hard reject + emergency
+ *   - `FORCED_OVER_THRESHOLD`       — user passed --force at CLI; allow = true
+ *
+ * See: `.peaks/memory/sub-agent-headroom-forced-compression-gate.md`.
+ */
+import { CONTEXT_CAPACITY_DEFAULT_BYTES, evaluateThresholdTier, tierToCode } from './threshold.js';
+const NEAR_LIMIT_SUGGEST = 'Consider --use-headroom to compress prompt.';
+const SOFT_WARN_SUGGEST = 'Use --use-headroom to compress prompt proactively.';
+const HARD_REJECT_SUGGEST = 'Trim prompt to < 80% of context capacity. Pass --force at CLI to override (NOT allowed at hook layer).';
+const EMERGENCY_SUGGEST = 'Prompt exceeds 90% of context. Trim aggressively or split into multiple dispatches.';
+/**
+ * Evaluate a prompt size against the G9.3 threshold table.
+ *
+ * The `force` option is the **only** path that lets a ≥ 80% prompt
+ * through. The hook layer (PreToolUse) MUST NOT accept this option;
+ * it is enforced by the `peaks sub-agent-dispatch-guard` atom's
+ * command-line parser, which does not declare a `--force` flag.
+ */
+export function evaluatePromptSize(promptSize, opts = {}) {
+    const capacity = opts.capacityBytes ?? CONTEXT_CAPACITY_DEFAULT_BYTES;
+    const evaluation = evaluateThresholdTier(promptSize, capacity);
+    const tier = evaluation.tier;
+    let allow;
+    let code;
+    let suggest;
+    let forcedAt = null;
+    switch (tier) {
+        case 'ok':
+            allow = true;
+            code = 'OK';
+            suggest = null;
+            break;
+        case 'soft-warn':
+            allow = true;
+            code = 'CONTEXT_SOFT_WARN';
+            suggest = SOFT_WARN_SUGGEST;
+            break;
+        case 'near-limit':
+            allow = true;
+            code = 'CONTEXT_NEAR_LIMIT';
+            suggest = NEAR_LIMIT_SUGGEST;
+            break;
+        case 'hard-reject':
+            allow = false;
+            code = 'PROMPT_TOO_LARGE';
+            suggest = HARD_REJECT_SUGGEST;
+            break;
+        case 'emergency':
+            allow = false;
+            code = 'PROMPT_EMERGENCY';
+            suggest = EMERGENCY_SUGGEST;
+            break;
+    }
+    // --force override (CLI only; hook layer never reaches this branch)
+    if (!allow && opts.force === true) {
+        allow = true;
+        code = 'FORCED_OVER_THRESHOLD';
+        suggest = 'Override applied at CLI. Hook layer will still reject.';
+        forcedAt = new Date().toISOString();
+    }
+    const warnings = [...evaluation.warnings];
+    if (forcedAt !== null && !warnings.includes('FORCED_OVER_THRESHOLD')) {
+        warnings.push('FORCED_OVER_THRESHOLD');
+    }
+    return {
+        allow,
+        code,
+        warnings,
+        suggest,
+        evaluation,
+        forcedAt
+    };
+}
+/**
+ * Re-export of `tierToCode` for callers that want a stable mapping
+ * without depending on the threshold module directly.
+ */
+export { tierToCode };

package/dist/src/services/context/context-schema.d.ts

@@ -0,0 +1,415 @@
+/**
+ * Runtime validator for context.json. Per spec §4.1 + H8 (audit trail
+ * hashable). When this schema changes, version field must bump.
+ */
+import { z } from 'zod';
+export declare const ContextJsonSchema: z.ZodObject<{
+    version: z.ZodLiteral<"1.0">;
+    goal: z.ZodString;
+    generatedAt: z.ZodString;
+    sha256: z.ZodString;
+    collector: z.ZodObject<{
+        files: z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            kind: z.ZodEnum<["source", "test", "config", "doc"]>;
+            lines: z.ZodNumber;
+            hash: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            path: string;
+            kind: "doc" | "source" | "test" | "config";
+            lines: number;
+            hash: string;
+        }, {
+            path: string;
+            kind: "doc" | "source" | "test" | "config";
+            lines: number;
+            hash: string;
+        }>, "many">;
+        gitStatus: z.ZodObject<{
+            branch: z.ZodString;
+            lastCommit: z.ZodString;
+            dirty: z.ZodBoolean;
+        }, "strip", z.ZodTypeAny, {
+            dirty: boolean;
+            branch: string;
+            lastCommit: string;
+        }, {
+            dirty: boolean;
+            branch: string;
+            lastCommit: string;
+        }>;
+        memoryEntries: z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            title: z.ZodString;
+            relevanceScore: z.ZodNumber;
+            excerptHash: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            path: string;
+            title: string;
+            relevanceScore: number;
+            excerptHash: string;
+        }, {
+            path: string;
+            title: string;
+            relevanceScore: number;
+            excerptHash: string;
+        }>, "many">;
+        deps: z.ZodRecord<z.ZodString, z.ZodObject<{
+            version: z.ZodString;
+            source: z.ZodEnum<["package.json", "pnpm-lock.yaml", "yarn.lock"]>;
+            resolved: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            version: string;
+            source: "package.json" | "pnpm-lock.yaml" | "yarn.lock";
+            resolved: string;
+        }, {
+            version: string;
+            source: "package.json" | "pnpm-lock.yaml" | "yarn.lock";
+            resolved: string;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        deps: Record<string, {
+            version: string;
+            source: "package.json" | "pnpm-lock.yaml" | "yarn.lock";
+            resolved: string;
+        }>;
+        gitStatus: {
+            dirty: boolean;
+            branch: string;
+            lastCommit: string;
+        };
+        files: {
+            path: string;
+            kind: "doc" | "source" | "test" | "config";
+            lines: number;
+            hash: string;
+        }[];
+        memoryEntries: {
+            path: string;
+            title: string;
+            relevanceScore: number;
+            excerptHash: string;
+        }[];
+    }, {
+        deps: Record<string, {
+            version: string;
+            source: "package.json" | "pnpm-lock.yaml" | "yarn.lock";
+            resolved: string;
+        }>;
+        gitStatus: {
+            dirty: boolean;
+            branch: string;
+            lastCommit: string;
+        };
+        files: {
+            path: string;
+            kind: "doc" | "source" | "test" | "config";
+            lines: number;
+            hash: string;
+        }[];
+        memoryEntries: {
+            path: string;
+            title: string;
+            relevanceScore: number;
+            excerptHash: string;
+        }[];
+    }>;
+    docRetriever: z.ZodObject<{
+        fetchedDocs: z.ZodArray<z.ZodObject<{
+            dep: z.ZodString;
+            version: z.ZodString;
+            source: z.ZodEnum<["local-cache", "remote-fetch"]>;
+            url: z.ZodOptional<z.ZodString>;
+            fetchedAt: z.ZodString;
+            contentHash: z.ZodString;
+            sections: z.ZodArray<z.ZodObject<{
+                title: z.ZodString;
+                tokenEstimate: z.ZodNumber;
+                excerpt: z.ZodString;
+            }, "strip", z.ZodTypeAny, {
+                title: string;
+                tokenEstimate: number;
+                excerpt: string;
+            }, {
+                title: string;
+                tokenEstimate: number;
+                excerpt: string;
+            }>, "many">;
+            stale: z.ZodBoolean;
+        }, "strip", z.ZodTypeAny, {
+            version: string;
+            source: "local-cache" | "remote-fetch";
+            stale: boolean;
+            dep: string;
+            fetchedAt: string;
+            contentHash: string;
+            sections: {
+                title: string;
+                tokenEstimate: number;
+                excerpt: string;
+            }[];
+            url?: string | undefined;
+        }, {
+            version: string;
+            source: "local-cache" | "remote-fetch";
+            stale: boolean;
+            dep: string;
+            fetchedAt: string;
+            contentHash: string;
+            sections: {
+                title: string;
+                tokenEstimate: number;
+                excerpt: string;
+            }[];
+            url?: string | undefined;
+        }>, "many">;
+        skipped: z.ZodArray<z.ZodObject<{
+            dep: z.ZodString;
+            reason: z.ZodEnum<["unconfigured", "network_error", "version_unknown"]>;
+        }, "strip", z.ZodTypeAny, {
+            dep: string;
+            reason: "unconfigured" | "network_error" | "version_unknown";
+        }, {
+            dep: string;
+            reason: "unconfigured" | "network_error" | "version_unknown";
+        }>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        skipped: {
+            dep: string;
+            reason: "unconfigured" | "network_error" | "version_unknown";
+        }[];
+        fetchedDocs: {
+            version: string;
+            source: "local-cache" | "remote-fetch";
+            stale: boolean;
+            dep: string;
+            fetchedAt: string;
+            contentHash: string;
+            sections: {
+                title: string;
+                tokenEstimate: number;
+                excerpt: string;
+            }[];
+            url?: string | undefined;
+        }[];
+    }, {
+        skipped: {
+            dep: string;
+            reason: "unconfigured" | "network_error" | "version_unknown";
+        }[];
+        fetchedDocs: {
+            version: string;
+            source: "local-cache" | "remote-fetch";
+            stale: boolean;
+            dep: string;
+            fetchedAt: string;
+            contentHash: string;
+            sections: {
+                title: string;
+                tokenEstimate: number;
+                excerpt: string;
+            }[];
+            url?: string | undefined;
+        }[];
+    }>;
+    tokenizer: z.ZodObject<{
+        metadata: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            kind: z.ZodEnum<["doc", "code", "memory", "git"]>;
+            version: z.ZodOptional<z.ZodString>;
+            blastRadius: z.ZodArray<z.ZodString, "many">;
+            conflictScore: z.ZodNumber;
+            timeDecayScore: z.ZodNumber;
+            tags: z.ZodArray<z.ZodString, "many">;
+        }, "strip", z.ZodTypeAny, {
+            kind: "git" | "code" | "doc" | "memory";
+            id: string;
+            blastRadius: string[];
+            conflictScore: number;
+            timeDecayScore: number;
+            tags: string[];
+            version?: string | undefined;
+        }, {
+            kind: "git" | "code" | "doc" | "memory";
+            id: string;
+            blastRadius: string[];
+            conflictScore: number;
+            timeDecayScore: number;
+            tags: string[];
+            version?: string | undefined;
+        }>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        metadata: {
+            kind: "git" | "code" | "doc" | "memory";
+            id: string;
+            blastRadius: string[];
+            conflictScore: number;
+            timeDecayScore: number;
+            tags: string[];
+            version?: string | undefined;
+        }[];
+    }, {
+        metadata: {
+            kind: "git" | "code" | "doc" | "memory";
+            id: string;
+            blastRadius: string[];
+            conflictScore: number;
+            timeDecayScore: number;
+            tags: string[];
+            version?: string | undefined;
+        }[];
+    }>;
+    renderer: z.ZodObject<{
+        audience: z.ZodEnum<["peaks-rd", "peaks-qa", "peaks-mut", "all"]>;
+        renderedAt: z.ZodString;
+        sizeBytes: z.ZodNumber;
+        truncated: z.ZodBoolean;
+        truncatedReason: z.ZodOptional<z.ZodEnum<["doc_budget_exceeded", "section_count_exceeded"]>>;
+    }, "strip", z.ZodTypeAny, {
+        sizeBytes: number;
+        audience: "all" | "peaks-rd" | "peaks-qa" | "peaks-mut";
+        renderedAt: string;
+        truncated: boolean;
+        truncatedReason?: "doc_budget_exceeded" | "section_count_exceeded" | undefined;
+    }, {
+        sizeBytes: number;
+        audience: "all" | "peaks-rd" | "peaks-qa" | "peaks-mut";
+        renderedAt: string;
+        truncated: boolean;
+        truncatedReason?: "doc_budget_exceeded" | "section_count_exceeded" | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    version: "1.0";
+    goal: string;
+    sha256: string;
+    generatedAt: string;
+    collector: {
+        deps: Record<string, {
+            version: string;
+            source: "package.json" | "pnpm-lock.yaml" | "yarn.lock";
+            resolved: string;
+        }>;
+        gitStatus: {
+            dirty: boolean;
+            branch: string;
+            lastCommit: string;
+        };
+        files: {
+            path: string;
+            kind: "doc" | "source" | "test" | "config";
+            lines: number;
+            hash: string;
+        }[];
+        memoryEntries: {
+            path: string;
+            title: string;
+            relevanceScore: number;
+            excerptHash: string;
+        }[];
+    };
+    docRetriever: {
+        skipped: {
+            dep: string;
+            reason: "unconfigured" | "network_error" | "version_unknown";
+        }[];
+        fetchedDocs: {
+            version: string;
+            source: "local-cache" | "remote-fetch";
+            stale: boolean;
+            dep: string;
+            fetchedAt: string;
+            contentHash: string;
+            sections: {
+                title: string;
+                tokenEstimate: number;
+                excerpt: string;
+            }[];
+            url?: string | undefined;
+        }[];
+    };
+    tokenizer: {
+        metadata: {
+            kind: "git" | "code" | "doc" | "memory";
+            id: string;
+            blastRadius: string[];
+            conflictScore: number;
+            timeDecayScore: number;
+            tags: string[];
+            version?: string | undefined;
+        }[];
+    };
+    renderer: {
+        sizeBytes: number;
+        audience: "all" | "peaks-rd" | "peaks-qa" | "peaks-mut";
+        renderedAt: string;
+        truncated: boolean;
+        truncatedReason?: "doc_budget_exceeded" | "section_count_exceeded" | undefined;
+    };
+}, {
+    version: "1.0";
+    goal: string;
+    sha256: string;
+    generatedAt: string;
+    collector: {
+        deps: Record<string, {
+            version: string;
+            source: "package.json" | "pnpm-lock.yaml" | "yarn.lock";
+            resolved: string;
+        }>;
+        gitStatus: {
+            dirty: boolean;
+            branch: string;
+            lastCommit: string;
+        };
+        files: {
+            path: string;
+            kind: "doc" | "source" | "test" | "config";
+            lines: number;
+            hash: string;
+        }[];
+        memoryEntries: {
+            path: string;
+            title: string;
+            relevanceScore: number;
+            excerptHash: string;
+        }[];
+    };
+    docRetriever: {
+        skipped: {
+            dep: string;
+            reason: "unconfigured" | "network_error" | "version_unknown";
+        }[];
+        fetchedDocs: {
+            version: string;
+            source: "local-cache" | "remote-fetch";
+            stale: boolean;
+            dep: string;
+            fetchedAt: string;
+            contentHash: string;
+            sections: {
+                title: string;
+                tokenEstimate: number;
+                excerpt: string;
+            }[];
+            url?: string | undefined;
+        }[];
+    };
+    tokenizer: {
+        metadata: {
+            kind: "git" | "code" | "doc" | "memory";
+            id: string;
+            blastRadius: string[];
+            conflictScore: number;
+            timeDecayScore: number;
+            tags: string[];
+            version?: string | undefined;
+        }[];
+    };
+    renderer: {
+        sizeBytes: number;
+        audience: "all" | "peaks-rd" | "peaks-qa" | "peaks-mut";
+        renderedAt: string;
+        truncated: boolean;
+        truncatedReason?: "doc_budget_exceeded" | "section_count_exceeded" | undefined;
+    };
+}>;

package/dist/src/services/context/context-schema.js

@@ -0,0 +1,73 @@
+/**
+ * Runtime validator for context.json. Per spec §4.1 + H8 (audit trail
+ * hashable). When this schema changes, version field must bump.
+ */
+import { z } from 'zod';
+export const ContextJsonSchema = z.object({
+    version: z.literal('1.0'),
+    goal: z.string().min(1),
+    generatedAt: z.string().datetime(),
+    sha256: z.string().regex(/^[a-f0-9]{64}$/),
+    collector: z.object({
+        files: z.array(z.object({
+            path: z.string(),
+            kind: z.enum(['source', 'test', 'config', 'doc']),
+            lines: z.number().int().nonnegative(),
+            hash: z.string(),
+        })),
+        gitStatus: z.object({
+            branch: z.string(),
+            lastCommit: z.string(),
+            dirty: z.boolean(),
+        }),
+        memoryEntries: z.array(z.object({
+            path: z.string(),
+            title: z.string(),
+            relevanceScore: z.number().min(0).max(1),
+            excerptHash: z.string(),
+        })),
+        deps: z.record(z.string(), z.object({
+            version: z.string(),
+            source: z.enum(['package.json', 'pnpm-lock.yaml', 'yarn.lock']),
+            resolved: z.string(),
+        })),
+    }),
+    docRetriever: z.object({
+        fetchedDocs: z.array(z.object({
+            dep: z.string(),
+            version: z.string(),
+            source: z.enum(['local-cache', 'remote-fetch']),
+            url: z.string().optional(),
+            fetchedAt: z.string().datetime(),
+            contentHash: z.string(),
+            sections: z.array(z.object({
+                title: z.string(),
+                tokenEstimate: z.number().int().nonnegative(),
+                excerpt: z.string(),
+            })),
+            stale: z.boolean(),
+        })),
+        skipped: z.array(z.object({
+            dep: z.string(),
+            reason: z.enum(['unconfigured', 'network_error', 'version_unknown']),
+        })),
+    }),
+    tokenizer: z.object({
+        metadata: z.array(z.object({
+            id: z.string(),
+            kind: z.enum(['doc', 'code', 'memory', 'git']),
+            version: z.string().optional(),
+            blastRadius: z.array(z.string()),
+            conflictScore: z.number().min(0).max(1),
+            timeDecayScore: z.number().min(0).max(1),
+            tags: z.array(z.string()),
+        })),
+    }),
+    renderer: z.object({
+        audience: z.enum(['peaks-rd', 'peaks-qa', 'peaks-mut', 'all']),
+        renderedAt: z.string().datetime(),
+        sizeBytes: z.number().int().nonnegative(),
+        truncated: z.boolean(),
+        truncatedReason: z.enum(['doc_budget_exceeded', 'section_count_exceeded']).optional(),
+    }),
+});

package/dist/src/services/context/dispatch-context-guard.d.ts

@@ -0,0 +1,27 @@
+/** Build the canonical artifact path for a given session/rid/role/idx/ext. */
+export declare function artifactPath(projectRoot: string, sid: string, rid: string, role: string, idx: number, ext?: string): string;
+/** Build the canonical shared channel path. */
+export declare function sharedChannelPath(projectRoot: string, sid: string, rid: string, batchId: string): string;
+/**
+ * Assert that `artifactPath` lives under
+ * `projectRoot/.peaks/_sub_agents/<sid>/artifacts/`. Rejects
+ * symlink/junction escapes and `..` segments.
+ *
+ * Throws an Error with `.code = 'INVALID_ARTIFACT_PATH'` on rejection.
+ */
+export declare function assertSafeArtifactPath(artifactPathInput: string, projectRoot: string): string;
+/**
+ * Assert that `channelPath` lives under
+ * `projectRoot/.peaks/_sub_agents/<sid>/shared/`. Same R-2 logic as
+ * `assertSafeArtifactPath` but with a different canonical subdir.
+ *
+ * Throws an Error with `.code = 'INVALID_SHARED_CHANNEL_PATH'` on rejection.
+ */
+export declare function assertSafeSharedChannelPath(channelPathInput: string, projectRoot: string): string;
+/**
+ * Soft-warn check on the artifact file name pattern. Returns null if
+ * the name matches `<rid>-<role>-<idx>.<ext>`, otherwise returns a
+ * warning string. Does NOT reject (the path is still in the canonical
+ * dir; the warning is for human/audit readability per G7.4.c).
+ */
+export declare function checkArtifactNameConvention(artifactPathInput: string): string | null;