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

package/dist/services/loop/loop-release-types.d.ts

@@ -0,0 +1,250 @@
+import { z } from "zod";
+/**
+ * LoopRelease — spec §4.1 (Loop Engineering Asset).
+ *
+ * M1 scope was the §4.1 fields. M3 (this slice) ADDS the share /
+ * desktop extension fields from §4.1 / §7A:
+ *   - shareable              (boolean, default true)
+ *   - share_excluded_paths   (string[], default [])
+ *   - desktop_visible        (boolean, default true)
+ *   - export_bundle_format   ('peaks.bundle/1', CLI-written constant)
+ *
+ * The four M3 fields are added with `.default(...)` so an in-memory
+ * object built from a pre-M3 snapshot still parses after the
+ * migration runs. NO enforcement on `shareable=false` is added in M3
+ * — the schema-only addition is the contract; full export /
+ * desktop enforcement lands in M7 (see plan
+ * m3-bee-release-extension.md and spec §7A).
+ *
+ * Field semantics — see the spec for full prose. Highlights:
+ *
+ *   - `id` is the stable kebab-case loop id; the storage key.
+ *   - `schema_version` is the constant literal `"peaks.loop/1"`; a
+ *     schema-version bump requires a new table / new enum case and a
+ *     migration — never edit this literal in place.
+ *   - `lifecycle_status` is `candidate` / `stable` / `retired`; the
+ *     default on first crystallization is `candidate`. LLMs cannot
+ *     auto-promote to `stable` (see spec §5.6).
+ *   - `linked_bees` is a denormalized pointer list of bee ids; the
+ *     authoritative loop↔bee relations live in `loop_bee_relation`
+ *     (M2). Keeping it here matches the spec §4.1 row shape and lets
+ *     M1 readers iterate the loop without an extra join.
+ *   - `success_criteria` / `evaluator_policy` are NL strings, not
+ *     machine-checked predicates; the evaluator definitions live in
+ *     the M4 evolution layer.
+ *   - `share_excluded_paths` is a JSON-encoded TEXT column at the
+ *     SQLite layer; the Zod schema accepts a string[] and the store
+ *     does the JSON.stringify/parse boundary work. Matches the
+ *     existing `loop_release` style (success_criteria_json, …).
+ *   - `export_bundle_format` is pinned to the literal
+ *     `"peaks.bundle/1"` per the spec §7A.2 contract — no other
+ *     value is accepted in this schema version.
+ */
+export declare const LoopReleaseLifecycleStatusSchema: z.ZodEnum<["candidate", "stable", "retired"]>;
+export type LoopReleaseLifecycleStatus = z.infer<typeof LoopReleaseLifecycleStatusSchema>;
+/**
+ * The M3 share / desktop extension fields, listed for code-search /
+ * lint discoverability. They are now part of the schema (with safe
+ * defaults) — see `LoopReleaseM3ExtensionSchema` below.
+ *
+ *   - shareable: defaults to true.
+ *   - share_excluded_paths: string[] (defaults to []).
+ *   - desktop_visible: defaults to true.
+ *   - export_bundle_format: constant "peaks.bundle/1" (CLI-written).
+ */
+export declare const LOOP_RELEASE_M3_FIELDS: readonly ["shareable", "share_excluded_paths", "desktop_visible", "export_bundle_format"];
+/**
+ * M3 share / desktop extension schema. Added to `LoopReleaseInputSchema`
+ * via `.extend(...)` so existing callers that omit these fields still
+ * parse — the Zod defaults below supply the spec values
+ * (true / [] / true / "peaks.bundle/1").
+ *
+ * `export_bundle_format` is pinned to a literal per spec §7A.2: the
+ * CLI is the only writer and only `"peaks.bundle/1"` is accepted. A
+ * schema-version bump is required to introduce another value.
+ */
+export declare const LoopReleaseM3ExtensionSchema: z.ZodObject<{
+    shareable: z.ZodDefault<z.ZodBoolean>;
+    share_excluded_paths: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    desktop_visible: z.ZodDefault<z.ZodBoolean>;
+    export_bundle_format: z.ZodDefault<z.ZodLiteral<"peaks.bundle/1">>;
+}, "strip", z.ZodTypeAny, {
+    export_bundle_format: "peaks.bundle/1";
+    shareable: boolean;
+    share_excluded_paths: string[];
+    desktop_visible: boolean;
+}, {
+    export_bundle_format?: "peaks.bundle/1" | undefined;
+    shareable?: boolean | undefined;
+    share_excluded_paths?: string[] | undefined;
+    desktop_visible?: boolean | undefined;
+}>;
+/** Convenience type for the M3 share / desktop subset. */
+export type LoopReleaseM3Extension = z.infer<typeof LoopReleaseM3ExtensionSchema>;
+/**
+ * Zod schema for the create payload (LoopReleaseInput). Mirrors the
+ * §4.1 row shape; `schema_version` is defaulted (clients cannot
+ * override it) and `created_at` is not part of the input — the store
+ * stamps it from the server clock.
+ */
+export declare const LoopReleaseInputSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    scenario: z.ZodString;
+    trigger_policy: z.ZodString;
+    success_criteria: z.ZodArray<z.ZodString, "many">;
+    interaction_policy: z.ZodString;
+    feedback_policy: z.ZodString;
+    evolution_policy: z.ZodString;
+    evaluator_policy: z.ZodArray<z.ZodString, "many">;
+    linked_bees: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    run_history: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    crystallization_evidence: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    lifecycle_status: z.ZodEnum<["candidate", "stable", "retired"]>;
+    version: z.ZodString;
+} & {
+    shareable: z.ZodDefault<z.ZodBoolean>;
+    share_excluded_paths: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    desktop_visible: z.ZodDefault<z.ZodBoolean>;
+    export_bundle_format: z.ZodDefault<z.ZodLiteral<"peaks.bundle/1">>;
+}, "strip", z.ZodTypeAny, {
+    version: string;
+    name: string;
+    id: string;
+    scenario: string;
+    trigger_policy: string;
+    interaction_policy: string;
+    feedback_policy: string;
+    evolution_policy: string;
+    lifecycle_status: "candidate" | "stable" | "retired";
+    export_bundle_format: "peaks.bundle/1";
+    success_criteria: string[];
+    evaluator_policy: string[];
+    linked_bees: string[];
+    run_history: string[];
+    crystallization_evidence: string[];
+    shareable: boolean;
+    share_excluded_paths: string[];
+    desktop_visible: boolean;
+}, {
+    version: string;
+    name: string;
+    id: string;
+    scenario: string;
+    trigger_policy: string;
+    interaction_policy: string;
+    feedback_policy: string;
+    evolution_policy: string;
+    lifecycle_status: "candidate" | "stable" | "retired";
+    success_criteria: string[];
+    evaluator_policy: string[];
+    export_bundle_format?: "peaks.bundle/1" | undefined;
+    linked_bees?: string[] | undefined;
+    run_history?: string[] | undefined;
+    crystallization_evidence?: string[] | undefined;
+    shareable?: boolean | undefined;
+    share_excluded_paths?: string[] | undefined;
+    desktop_visible?: boolean | undefined;
+}>;
+/**
+ * `LoopReleaseInput` is the *input* shape clients supply: defaulted
+ * fields (linked_bees / run_history / crystallization_evidence) are
+ * optional here. We use `z.input` (not `z.infer`) so the inferred
+ * type matches the create-call signature; the parsed output type —
+ * with all defaulted fields filled — is `LoopRelease`.
+ */
+export type LoopReleaseInput = z.input<typeof LoopReleaseInputSchema>;
+/**
+ * Full Zod schema for a LoopRelease row as persisted. Differs from the
+ * input schema only in that `schema_version` is exposed (and defaulted
+ * to the fixed literal). The literal constraint still rejects any
+ * client-supplied value other than `"peaks.loop/1"`; the default
+ * means omitting the key is fine and the output always carries the
+ * constant.
+ *
+ * We expose this as the canonical "row schema" used by lint and
+ * service.create/read paths.
+ */
+export declare const LoopReleaseSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    scenario: z.ZodString;
+    trigger_policy: z.ZodString;
+    success_criteria: z.ZodArray<z.ZodString, "many">;
+    interaction_policy: z.ZodString;
+    feedback_policy: z.ZodString;
+    evolution_policy: z.ZodString;
+    evaluator_policy: z.ZodArray<z.ZodString, "many">;
+    linked_bees: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    run_history: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    crystallization_evidence: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    lifecycle_status: z.ZodEnum<["candidate", "stable", "retired"]>;
+    version: z.ZodString;
+} & {
+    shareable: z.ZodDefault<z.ZodBoolean>;
+    share_excluded_paths: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    desktop_visible: z.ZodDefault<z.ZodBoolean>;
+    export_bundle_format: z.ZodDefault<z.ZodLiteral<"peaks.bundle/1">>;
+} & {
+    schema_version: z.ZodDefault<z.ZodLiteral<"peaks.loop/1">>;
+}, "strip", z.ZodTypeAny, {
+    schema_version: "peaks.loop/1";
+    version: string;
+    name: string;
+    id: string;
+    scenario: string;
+    trigger_policy: string;
+    interaction_policy: string;
+    feedback_policy: string;
+    evolution_policy: string;
+    lifecycle_status: "candidate" | "stable" | "retired";
+    export_bundle_format: "peaks.bundle/1";
+    success_criteria: string[];
+    evaluator_policy: string[];
+    linked_bees: string[];
+    run_history: string[];
+    crystallization_evidence: string[];
+    shareable: boolean;
+    share_excluded_paths: string[];
+    desktop_visible: boolean;
+}, {
+    version: string;
+    name: string;
+    id: string;
+    scenario: string;
+    trigger_policy: string;
+    interaction_policy: string;
+    feedback_policy: string;
+    evolution_policy: string;
+    lifecycle_status: "candidate" | "stable" | "retired";
+    success_criteria: string[];
+    evaluator_policy: string[];
+    schema_version?: "peaks.loop/1" | undefined;
+    export_bundle_format?: "peaks.bundle/1" | undefined;
+    linked_bees?: string[] | undefined;
+    run_history?: string[] | undefined;
+    crystallization_evidence?: string[] | undefined;
+    shareable?: boolean | undefined;
+    share_excluded_paths?: string[] | undefined;
+    desktop_visible?: boolean | undefined;
+}>;
+export type LoopRelease = z.infer<typeof LoopReleaseSchema>;
+/**
+ * Convenience: strict-parse an unknown payload into a LoopRelease row.
+ * Throws ZodError on failure. This is the public validation boundary.
+ */
+export declare function parseLoopRelease(input: unknown): LoopRelease;
+/**
+ * Convenience: safe-parse that returns a Result-like shape so callers
+ * (CLI layer in M5) can render findings without try/catch noise.
+ */
+export declare function safeParseLoopRelease(input: unknown): {
+    ok: true;
+    row: LoopRelease;
+} | {
+    ok: false;
+    findings: Array<{
+        path: string;
+        message: string;
+    }>;
+};

package/dist/services/loop/loop-release-types.js

@@ -0,0 +1,162 @@
+import { z } from "zod";
+/**
+ * LoopRelease — spec §4.1 (Loop Engineering Asset).
+ *
+ * M1 scope was the §4.1 fields. M3 (this slice) ADDS the share /
+ * desktop extension fields from §4.1 / §7A:
+ *   - shareable              (boolean, default true)
+ *   - share_excluded_paths   (string[], default [])
+ *   - desktop_visible        (boolean, default true)
+ *   - export_bundle_format   ('peaks.bundle/1', CLI-written constant)
+ *
+ * The four M3 fields are added with `.default(...)` so an in-memory
+ * object built from a pre-M3 snapshot still parses after the
+ * migration runs. NO enforcement on `shareable=false` is added in M3
+ * — the schema-only addition is the contract; full export /
+ * desktop enforcement lands in M7 (see plan
+ * m3-bee-release-extension.md and spec §7A).
+ *
+ * Field semantics — see the spec for full prose. Highlights:
+ *
+ *   - `id` is the stable kebab-case loop id; the storage key.
+ *   - `schema_version` is the constant literal `"peaks.loop/1"`; a
+ *     schema-version bump requires a new table / new enum case and a
+ *     migration — never edit this literal in place.
+ *   - `lifecycle_status` is `candidate` / `stable` / `retired`; the
+ *     default on first crystallization is `candidate`. LLMs cannot
+ *     auto-promote to `stable` (see spec §5.6).
+ *   - `linked_bees` is a denormalized pointer list of bee ids; the
+ *     authoritative loop↔bee relations live in `loop_bee_relation`
+ *     (M2). Keeping it here matches the spec §4.1 row shape and lets
+ *     M1 readers iterate the loop without an extra join.
+ *   - `success_criteria` / `evaluator_policy` are NL strings, not
+ *     machine-checked predicates; the evaluator definitions live in
+ *     the M4 evolution layer.
+ *   - `share_excluded_paths` is a JSON-encoded TEXT column at the
+ *     SQLite layer; the Zod schema accepts a string[] and the store
+ *     does the JSON.stringify/parse boundary work. Matches the
+ *     existing `loop_release` style (success_criteria_json, …).
+ *   - `export_bundle_format` is pinned to the literal
+ *     `"peaks.bundle/1"` per the spec §7A.2 contract — no other
+ *     value is accepted in this schema version.
+ */
+export const LoopReleaseLifecycleStatusSchema = z.enum([
+    "candidate",
+    "stable",
+    "retired",
+]);
+/**
+ * The M3 share / desktop extension fields, listed for code-search /
+ * lint discoverability. They are now part of the schema (with safe
+ * defaults) — see `LoopReleaseM3ExtensionSchema` below.
+ *
+ *   - shareable: defaults to true.
+ *   - share_excluded_paths: string[] (defaults to []).
+ *   - desktop_visible: defaults to true.
+ *   - export_bundle_format: constant "peaks.bundle/1" (CLI-written).
+ */
+export const LOOP_RELEASE_M3_FIELDS = [
+    "shareable",
+    "share_excluded_paths",
+    "desktop_visible",
+    "export_bundle_format",
+];
+/**
+ * M3 share / desktop extension schema. Added to `LoopReleaseInputSchema`
+ * via `.extend(...)` so existing callers that omit these fields still
+ * parse — the Zod defaults below supply the spec values
+ * (true / [] / true / "peaks.bundle/1").
+ *
+ * `export_bundle_format` is pinned to a literal per spec §7A.2: the
+ * CLI is the only writer and only `"peaks.bundle/1"` is accepted. A
+ * schema-version bump is required to introduce another value.
+ */
+export const LoopReleaseM3ExtensionSchema = z.object({
+    shareable: z.boolean().default(true),
+    share_excluded_paths: z
+        .array(z.string().min(1).max(4096))
+        .default([]),
+    desktop_visible: z.boolean().default(true),
+    export_bundle_format: z
+        .literal("peaks.bundle/1")
+        .default("peaks.bundle/1"),
+});
+/**
+ * Zod schema for the create payload (LoopReleaseInput). Mirrors the
+ * §4.1 row shape; `schema_version` is defaulted (clients cannot
+ * override it) and `created_at` is not part of the input — the store
+ * stamps it from the server clock.
+ */
+export const LoopReleaseInputSchema = z
+    .object({
+    id: z
+        .string()
+        .min(1)
+        .max(64)
+        .regex(/^[a-z][a-z0-9]*(-[a-z0-9]+)*$/, {
+        message: "id must be kebab-case starting with a lowercase letter (e.g. loop-onboarding-research)",
+    }),
+    name: z.string().min(1).max(200),
+    scenario: z.string().trim().min(1).max(4000),
+    trigger_policy: z.string().trim().min(1).max(2000),
+    success_criteria: z
+        .array(z.string().trim().min(1).max(1000))
+        .min(1, "success_criteria must list at least one declarative criterion"),
+    interaction_policy: z
+        .string()
+        .trim()
+        .min(1, "interaction_policy must declare human-NL-choice-only semantics")
+        .max(2000),
+    feedback_policy: z.string().trim().min(1).max(2000),
+    evolution_policy: z.string().trim().min(1).max(2000),
+    evaluator_policy: z.array(z.string().trim().min(1).max(1000)).min(1),
+    linked_bees: z.array(z.string().min(1).max(64)).default([]),
+    run_history: z.array(z.string().min(1).max(128)).default([]),
+    crystallization_evidence: z.array(z.string().min(1).max(128)).default([]),
+    lifecycle_status: LoopReleaseLifecycleStatusSchema,
+    version: z
+        .string()
+        .regex(/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/, {
+        message: "version must be a semver string (e.g. 0.1.0)",
+    }),
+})
+    .extend(LoopReleaseM3ExtensionSchema.shape);
+/**
+ * Full Zod schema for a LoopRelease row as persisted. Differs from the
+ * input schema only in that `schema_version` is exposed (and defaulted
+ * to the fixed literal). The literal constraint still rejects any
+ * client-supplied value other than `"peaks.loop/1"`; the default
+ * means omitting the key is fine and the output always carries the
+ * constant.
+ *
+ * We expose this as the canonical "row schema" used by lint and
+ * service.create/read paths.
+ */
+export const LoopReleaseSchema = LoopReleaseInputSchema.extend({
+    schema_version: z
+        .literal("peaks.loop/1")
+        .default("peaks.loop/1"),
+});
+/**
+ * Convenience: strict-parse an unknown payload into a LoopRelease row.
+ * Throws ZodError on failure. This is the public validation boundary.
+ */
+export function parseLoopRelease(input) {
+    return LoopReleaseSchema.parse(input);
+}
+/**
+ * Convenience: safe-parse that returns a Result-like shape so callers
+ * (CLI layer in M5) can render findings without try/catch noise.
+ */
+export function safeParseLoopRelease(input) {
+    const r = LoopReleaseSchema.safeParse(input);
+    if (r.success)
+        return { ok: true, row: r.data };
+    return {
+        ok: false,
+        findings: r.error.issues.map((i) => ({
+            path: i.path.join("."),
+            message: i.message,
+        })),
+    };
+}

package/dist/services/memory/project-context-service.d.ts

@@ -0,0 +1,21 @@
+import { type BootstrapProjectScanEnvelope } from '../prd/project-scan-bootstrap-service.js';
+export type ProjectContextSection = {
+    heading: string;
+    body: string;
+};
+/**
+ * Slice 2026-07-15-project-scan-bootstrap (G1 + G2):
+ * generateProjectContext now also bootstraps the project-level
+ * `.peaks/project-scan/` artifact set. The envelope is returned
+ * alongside the context so `peaks project context` can surface
+ * `templatesBooted` / `templatesSkipped` / `durationMs` in its JSON.
+ */
+export type ProjectContextEnvelope = {
+    path: string;
+    content: string;
+    sessionCount: number;
+    projectScan: BootstrapProjectScanEnvelope;
+};
+export declare function generateProjectContext(projectRoot: string): Promise<ProjectContextEnvelope>;
+export declare function readProjectContext(projectRoot: string): string | null;
+export declare function getProjectContextPath(projectRoot: string): string;

package/dist/services/memory/project-context-service.js

@@ -0,0 +1,161 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { listSessionMetas } from '../session/session-manager.js';
+import { getSessionDir } from '../session/getSessionDir.js';
+import { bootstrapProjectScan } from '../prd/project-scan-bootstrap-service.js';
+const PROJECT_CONTEXT_FILE = '.peaks/PROJECT.md';
+const CONTEXT_HEADER = `# Peaks Project Context
+
+> Auto-generated project memory. Peaks reads this at the start of each session to understand
+> the project's history, tech stack, conventions, and past decisions.
+> Last updated: `;
+const MANAGED_BLOCK_START = '<!-- peaks-managed:session-history-start -->';
+const MANAGED_BLOCK_END = '<!-- peaks-managed:session-history-end -->';
+function projectName(projectRoot) {
+    const pkgPath = join(projectRoot, 'package.json');
+    if (!existsSync(pkgPath))
+        return projectRoot.split(/[\\/]/).pop() ?? 'unknown';
+    try {
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+        return pkg.name ?? projectRoot.split(/[\\/]/).pop() ?? 'unknown';
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        return projectRoot.split(/[\\/]/).pop() ?? 'unknown';
+    }
+}
+function listMdFiles(dir, maxDepth = 3) {
+    const results = [];
+    if (!existsSync(dir) || maxDepth <= 0)
+        return results;
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return results;
+    }
+    for (const entry of entries) {
+        if (entry.name.startsWith('.'))
+            continue;
+        const full = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            results.push(...listMdFiles(full, maxDepth - 1));
+        }
+        else if (entry.isFile() && entry.name.endsWith('.md')) {
+            results.push(full);
+        }
+    }
+    return results;
+}
+function extractOneLineSummary(sessionRoot) {
+    const artifacts = listMdFiles(sessionRoot, 4);
+    for (const artifact of artifacts.slice(0, 5)) {
+        try {
+            const content = readFileSync(artifact, 'utf8');
+            // Grab the first non-heading, non-empty line after the front section
+            const lines = content.split(/\r?\n/);
+            for (const line of lines) {
+                const trimmed = line.trim();
+                if (!trimmed || trimmed.startsWith('#') || trimmed.startsWith('-') || trimmed.startsWith('`'))
+                    continue;
+                if (trimmed.length > 10 && trimmed.length < 200)
+                    return trimmed;
+                break;
+            }
+        }
+        catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+            // skip unreadable
+        }
+    }
+    return null;
+}
+function buildSessionHistory(projectRoot) {
+    const metas = listSessionMetas(projectRoot);
+    if (metas.length === 0) {
+        return `${MANAGED_BLOCK_START}\n\n_No sessions recorded yet._\n\n${MANAGED_BLOCK_END}`;
+    }
+    const maxSessions = 15;
+    // Sort by createdAt descending (most recent first)
+    const sorted = [...metas].sort((a, b) => (b.createdAt || '').localeCompare(a.createdAt || ''));
+    const recent = sorted.slice(0, maxSessions);
+    let body = `${MANAGED_BLOCK_START}\n\n## Timeline (${metas.length} sessions`;
+    if (metas.length > maxSessions)
+        body += `, showing last ${maxSessions}`;
+    body += ')\n\n';
+    // Human-readable timeline: date | name | brief
+    body += `| Date | Directory | Title | What |\n`;
+    body += `|------|-----------|-------|------|\n`;
+    for (const meta of recent) {
+        const date = meta.createdAt ? meta.createdAt.slice(0, 10) : '?';
+        const dir = meta.sessionId;
+        const title = (meta.title ?? 'Untitled').slice(0, 40);
+        const skill = meta.skill ?? '-';
+        // Extract one-line summary from artifacts for the "What" column
+        const sessionRoot = getSessionDir(projectRoot, meta.sessionId);
+        const summary = extractOneLineSummary(sessionRoot);
+        const brief = summary ? summary.slice(0, 70) : skill;
+        body += `| ${date} | \`${dir}\` | ${title} | ${brief} |\n`;
+    }
+    body += `\n${MANAGED_BLOCK_END}`;
+    return body;
+}
+export async function generateProjectContext(projectRoot) {
+    const peaksDir = join(projectRoot, '.peaks');
+    if (!existsSync(peaksDir)) {
+        mkdirSync(peaksDir, { recursive: true });
+    }
+    const contextPath = join(projectRoot, PROJECT_CONTEXT_FILE);
+    const name = projectName(projectRoot);
+    const now = new Date().toISOString();
+    const sessionHistory = buildSessionHistory(projectRoot);
+    const header = `${CONTEXT_HEADER}${now}\n\n## Project: ${name}\n`;
+    let content;
+    if (existsSync(contextPath)) {
+        const existing = readFileSync(contextPath, 'utf8');
+        const startIdx = existing.indexOf(MANAGED_BLOCK_START);
+        const endIdx = existing.indexOf(MANAGED_BLOCK_END);
+        // Update the Last-updated timestamp in the header
+        const updatedExisting = existing.replace(/Last updated: .*/, `Last updated: ${now}`);
+        if (startIdx >= 0 && endIdx > startIdx) {
+            // Replace managed block, preserve user content outside it
+            const before = updatedExisting.slice(0, startIdx);
+            const after = updatedExisting.slice(endIdx + MANAGED_BLOCK_END.length);
+            content = before + sessionHistory + after;
+        }
+        else {
+            // No managed block found — append
+            content = updatedExisting.trimEnd() + '\n\n' + sessionHistory + '\n';
+        }
+    }
+    else {
+        content = header + '\n' + sessionHistory + '\n';
+    }
+    writeFileSync(contextPath, content, 'utf8');
+    // Slice 2026-07-15-project-scan-bootstrap (G1 + G2):
+    // After writing PROJECT.md, also bootstrap `.peaks/project-scan/`
+    // (project-scan.md + 4 bundled audit/business templates). Idempotent
+    // — re-running this call does not overwrite existing files (unless
+    // the caller passes `force` / `forceTemplates`, which we do NOT do
+    // here; peaks workspace init owns the force variants).
+    const projectScan = await bootstrapProjectScan({ projectRoot });
+    return {
+        path: contextPath,
+        content,
+        sessionCount: listSessionMetas(projectRoot).length,
+        projectScan
+    };
+}
+export function readProjectContext(projectRoot) {
+    const contextPath = join(projectRoot, PROJECT_CONTEXT_FILE);
+    if (!existsSync(contextPath))
+        return null;
+    try {
+        return readFileSync(contextPath, 'utf8');
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        return null;
+    }
+}
+export function getProjectContextPath(projectRoot) {
+    return join(projectRoot, PROJECT_CONTEXT_FILE);
+}

package/dist/services/polyrepo/polyrepo-dispatcher.d.ts

@@ -0,0 +1,34 @@
+import type { PolyrepoDispatch, PolyrepoManifest } from './polyrepo-types.js';
+export interface DispatchOptions {
+    /** Manifest returned by scanPolyrepo (root + children list). */
+    readonly manifest: PolyrepoManifest;
+    /** Session id this dispatch belongs to. */
+    readonly sid: string;
+    /** Request id (used in the on-disk filename). */
+    readonly rid: string;
+    /** Target child ids. Empty = root-only dispatch. Unknown ids are
+     *  recorded as warnings in the result, NOT raised as errors. */
+    readonly targets: readonly string[];
+    /** Artifact body — the role + source path on the parent side. */
+    readonly artifact: PolyrepoDispatch['artifact'];
+}
+export interface ChildDispatchResult {
+    readonly childId: string;
+    readonly path: string;
+    readonly ok: boolean;
+    readonly error?: string;
+    /** Where the artifact was mirrored to (child-side path). */
+    readonly mirroredTo?: string;
+}
+export interface DispatchResult {
+    readonly dispatch: PolyrepoDispatch;
+    readonly perChild: ChildDispatchResult[];
+    readonly warnings: string[];
+}
+export declare function dispatchArtifact(opts: DispatchOptions): DispatchResult;
+/** Default location of the polyrepo manifest on disk. */
+export declare function manifestPath(root: string): string;
+/** Read a persisted manifest from disk. Returns null when missing. */
+export declare function readManifest(root: string): PolyrepoManifest | null;
+/** Write a manifest atomically. */
+export declare function writeManifest(root: string, manifest: PolyrepoManifest): void;