hotmilk 0.1.13 → 0.1.14

package/skills/update-docs/references/doc-inventory.md

@@ -0,0 +1,69 @@
+# Doc inventory
+
+**Load when:** Phase 0 (full sync), or you need the truth → doc matrix for an unfamiliar drift.
+
+**Do NOT load when:** Post-ship route already names the row (read that row here only if unsure), or the user scoped a single file you already know.
+
+Code and config win. Docs below are reconciliation targets. **Adapt rows to the repo** — skip rows that do not exist.
+
+## Detect project type (Phase 0)
+
+Read one manifest first, then use the matching rows:
+
+| Signal file                   | Project type   |
+| ----------------------------- | -------------- |
+| `package.json`                | Node / JS / TS |
+| `Cargo.toml`                  | Rust           |
+| `pyproject.toml` / `setup.py` | Python         |
+| `go.mod`                      | Go             |
+| `pom.xml` / `build.gradle*`   | JVM            |
+
+Also note doc roots if present: `README.md`, `CONTRIBUTING.md`, `docs/`, `CHANGELOG.md`, and any root instruction files (`AGENTS.md`, `CLAUDE.md`, …).
+
+**Monorepo / multi-manifest:** When root and package manifests both exist, treat **root manifest scripts + root README/CONTRIBUTING** as canonical for repo-wide commands. Package READMEs get package-local scripts and paths only — do not copy root commands into every package README unless that package owns them.
+
+## Truth → doc matrix
+
+| Source of truth                                                                | What to extract                                                       | Doc targets                                                                      |
+| ------------------------------------------------------------------------------ | --------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| Package manifest (`package.json`, `Cargo.toml`, `pyproject.toml`, `go.mod`, …) | Scripts/commands, deps, version, entry points, published files        | `README.md`, `CONTRIBUTING.md`                                                   |
+| Source layout (`src/`, `lib/`, `cmd/`, …)                                      | Module roles, public API surface                                      | README architecture section, `docs/`                                             |
+| CI config (`.github/workflows/`, `.gitlab-ci.yml`, …)                          | Test/lint/build commands                                              | `README.md`, `CONTRIBUTING.md`                                                   |
+| Config templates in repo root                                                  | Default values users copy                                             | README config sample, setup docs                                                 |
+| `CHANGELOG.md` / release tags                                                  | Version, breaking changes                                             | README version notes                                                             |
+| `docs/` (when directory exists)                                                | Topic pages, API reference                                            | Cross-link from README; do not create `docs/` during sync                        |
+| Root instruction files (when present)                                          | Commands, layout tables, contributor rules                            | That file only — do not invent paths                                             |
+| Workspace / monorepo (root + package manifests)                                | Root scripts for repo-wide ops; package scripts for package-local ops | Root README/CONTRIBUTING ↔ root manifest; package README ↔ that package manifest |
+
+## Post-ship triggers (targeted recon)
+
+When the user changed code recently, scan **only** rows touched by the change:
+
+| Change area                                                              | Minimum doc pass                                                            |
+| ------------------------------------------------------------------------ | --------------------------------------------------------------------------- |
+| New dependency or entry point                                            | Manifest ↔ README (+ CONTRIBUTING if it lists deps)                         |
+| Default config flip or toggle default change                             | Config template ↔ README sample and feature/toggle tables                   |
+| Lazy-loaded or opt-in feature (doc mentions it; default off in template) | Template defaults ↔ README — mark opt-in/experimental when default is false |
+| New script or test command                                               | Manifest scripts ↔ README + CONTRIBUTING                                    |
+| Version / peer bump                                                      | README version note, manifest version constraints                           |
+| Public API or module layout change                                       | Layout tables, `docs/` API pages                                            |
+| CI workflow change                                                       | CONTRIBUTING / README verify commands                                       |
+
+## Full-sync order
+
+1. Detect project type; read truth files for applicable matrix rows.
+2. Read every doc target listed for those rows.
+3. Build a diff list — fact mismatches only.
+4. Patch the smallest set of files that restores consistency.
+5. Run [`drift-verification.md`](drift-verification.md).
+
+## Common drifts (quick scan)
+
+| Symptom                                        | Likely fix                                                                    |
+| ---------------------------------------------- | ----------------------------------------------------------------------------- |
+| README command does not exist in manifest      | Align with manifest scripts/targets                                           |
+| Doc paths point to removed modules             | Update layout table from current tree                                         |
+| Config sample shows stale defaults             | Copy from repo config template after confirming code                          |
+| Doc lists a feature not in manifest/config     | Remove or mark as external/optional                                           |
+| Duplicate facts disagree across two docs       | Pick one canonical source; link from the other                                |
+| Doc, manifest, and CI disagree on same command | Apply precedence (CI > manifest > source); report conflict if still ambiguous |

package/skills/update-docs/references/drift-verification.md

@@ -0,0 +1,59 @@
+# Drift verification
+
+**Load when:** Phase 4 — after any patch, or when reporting "docs already in sync."
+
+**Do NOT load when:** Recon-only pass with zero edits planned — skip to a short "no drift found" note instead.
+
+**Truth conflicts:** When sources disagree, apply **CI > manifest scripts/targets > source comments**. Report unresolved conflicts in **Gaps** — do not patch until the user picks a winner.
+
+## Checklist
+
+Mark each item that applies to scope. All applicable items must pass before "done."
+
+### Always (any patch)
+
+- [ ] Every edited claim traces to a truth file read this session (path named in report)
+- [ ] No code or config files changed unless the user explicitly asked to fix defaults
+- [ ] Diff stayed within scoped doc files — no cosmetic-only edits elsewhere
+
+### Full sync
+
+- [ ] README commands match manifest scripts/targets (or language equivalent); in monorepos, root README uses root manifest — package READMEs use package manifest only
+- [ ] Config template in docs matches repo config defaults
+- [ ] Path references in edited docs still exist on disk
+- [ ] Duplicate facts across docs agree — one canonical source preferred
+
+### Optional (when root instruction files were in scope)
+
+- [ ] Command and layout tables match manifest, CI, and current tree
+
+### Post-ship: dependency / manifest
+
+- [ ] New manifest entries have matching README mention when user-facing
+- [ ] Opt-in or experimental features documented when defaults are off
+
+## Commands (adapt to project)
+
+```bash
+# Which doc files changed
+git diff --name-only -- '*.md'
+
+# Node: list scripts
+node -e "console.log(require('./package.json').scripts)"
+
+# Rust: list bin targets
+cargo metadata --no-deps --format-version 1 | head
+
+# Python: project scripts (when pyproject.toml exists)
+python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb')).get('project',{}).get('scripts',{}))" 2>/dev/null || true
+```
+
+Run the project's test/lint command when code changed in the same task (from README, CONTRIBUTING, CI config, or manifest scripts). Markdown-only sync does not require a full test run.
+
+## Report blockers
+
+If a checklist item fails, report **blocked** with:
+
+- which item failed
+- what truth vs doc say
+- whether user decision is needed (e.g. intentional undocumented feature)

package/src/bootstrap/extensions.ts

@@ -36,6 +36,8 @@ export type RegisterBundledExtensionsOptions = {
   cwd?: string;
   /** Precomputed skips (tests); defaults to scanning Pi settings. */
   globalSkips?: GlobalBundledExtensionSkip[];
+  /** When false, only global Pi settings are scanned (trust-safe startup). */
+  includeProjectSettings?: boolean;
 };
 
 export type RegisterBundledExtensionsResult = {
@@ -48,7 +50,11 @@ export async function registerBundledExtensions(
   options: RegisterBundledExtensionsOptions = {},
 ): Promise<RegisterBundledExtensionsResult> {
   const globalSkips =
-    options.globalSkips ?? detectGlobalBundledExtensionSkips({ cwd: options.cwd });
+    options.globalSkips ??
+    detectGlobalBundledExtensionSkips({
+      cwd: options.cwd,
+      includeProjectSettings: options.includeProjectSettings ?? true,
+    });
   const skipById = new Map(globalSkips.map((skip) => [skip.id, skip] as const));
 
   const enabledIds = new Set<BundledExtensionId>();

package/src/bootstrap/global-extension-sources.ts

@@ -17,6 +17,8 @@ export type GlobalBundledExtensionSkip = {
 export type CollectGlobalExtensionSourcesOptions = {
   cwd?: string;
   homedir?: string;
+  /** When false, skip project `.pi/settings.json` (Pi project trust gate). */
+  includeProjectSettings?: boolean;
 };
 
 function isLocalPackageEntry(entry: string): boolean {
@@ -105,6 +107,7 @@ export function collectInstalledPackageNamesFromPiSettings(
 ): Set<string> {
   const home = options.homedir ?? process.env.HOME ?? process.env.USERPROFILE ?? os.homedir();
   const cwd = options.cwd ?? process.cwd();
+  const includeProjectSettings = options.includeProjectSettings ?? true;
   const names = new Set<string>();
 
   const sources: Array<{ settingsPath: string; baseDir: string }> = [
@@ -112,9 +115,15 @@ export function collectInstalledPackageNamesFromPiSettings(
       settingsPath: path.join(home, ".pi", "agent", "settings.json"),
       baseDir: path.join(home, ".pi", "agent"),
     },
-    { settingsPath: path.join(cwd, PI_PROJECT_CONFIG_DIR, "settings.json"), baseDir: cwd },
   ];
 
+  if (includeProjectSettings) {
+    sources.push({
+      settingsPath: path.join(cwd, PI_PROJECT_CONFIG_DIR, "settings.json"),
+      baseDir: cwd,
+    });
+  }
+
   for (const { settingsPath, baseDir } of sources) {
     for (const entry of readSettingsEntries(settingsPath)) {
       const npmName = parseNpmPackageName(entry);

package/src/bootstrap/project-trust.ts

@@ -0,0 +1,41 @@
+import type {
+  ExtensionAPI,
+  ProjectTrustContext,
+  ProjectTrustEventResult,
+} from "@earendil-works/pi-coding-agent";
+import type { ResolvedProjectTrust } from "../config/hotmilk.ts";
+
+const HOTMILK_TRUST_PROMPT = (cwd: string): string =>
+  `Trust this project for hotmilk?\n\n${cwd}\n\nEnables: .pi/settings.json, project extensions, .agents/skills, gentle-ai files under .pi/. Decline keeps global hotmilk bundles only.`;
+
+export function resolveProjectTrustDecision(
+  settings: ResolvedProjectTrust,
+  ctx: ProjectTrustContext,
+  cwd: string,
+): Promise<ProjectTrustEventResult> {
+  switch (settings.mode) {
+    case "always":
+      return Promise.resolve({ trusted: "yes", remember: settings.remember });
+    case "never":
+      return Promise.resolve({ trusted: "no", remember: settings.remember });
+    case "prompt":
+      if (!ctx.hasUI) {
+        return Promise.resolve({ trusted: "undecided" });
+      }
+      return ctx.ui.confirm(HOTMILK_TRUST_PROMPT(cwd), "Trust project").then((trusted) => ({
+        trusted: trusted ? "yes" : "no",
+        remember: trusted ? settings.remember : false,
+      }));
+    default:
+      return Promise.resolve({ trusted: "undecided" });
+  }
+}
+
+export function registerProjectTrustHandlers(
+  pi: ExtensionAPI,
+  settings: ResolvedProjectTrust,
+): void {
+  pi.on("project_trust", async (event, ctx): Promise<ProjectTrustEventResult> => {
+    return resolveProjectTrustDecision(settings, ctx, event.cwd);
+  });
+}

package/src/bootstrap/session.ts

@@ -1,5 +1,6 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { applyContextStackOnSessionStart } from "./context-stack.ts";
+import { detectGlobalBundledExtensionSkips } from "./global-extension-sources.ts";
 import { seedAgentMcpJsonIfMissing } from "../config/mcp.ts";
 import { AGENT_HOTMILK_CONFIG_LABEL, seedHotmilkConfigIfMissing } from "../config/hotmilk.ts";
 import type { HotmilkRuntime } from "../config/runtime.ts";
@@ -16,6 +17,23 @@ const HOTMILK_PARSE_ERROR_MESSAGE = (path: string, error: string): string =>
 const MCP_SEEDED_MESSAGE = (path: string): string =>
   `Created ${path} from hotmilk MCP template (add servers for pi-mcp-adapter; context-mode uses the extension bridge).`;
 
+function formatProjectTrustSkipMessage(
+  skips: HotmilkRuntime["globalExtensionSkips"],
+): string | undefined {
+  if (skips.length === 0) {
+    return undefined;
+  }
+  const rows = skips.map((skip) => `${skip.id}: project ${skip.packageName}`).join("\n");
+  return `Project settings also provide bundled packages (run /reload to dedupe):\n${rows}`;
+}
+
+function detectProjectOnlyBundledSkips(cwd: string): HotmilkRuntime["globalExtensionSkips"] {
+  const globalOnly = detectGlobalBundledExtensionSkips({ cwd, includeProjectSettings: false });
+  const withProject = detectGlobalBundledExtensionSkips({ cwd, includeProjectSettings: true });
+  const globalIds = new Set(globalOnly.map((skip) => skip.id));
+  return withProject.filter((skip) => !globalIds.has(skip.id));
+}
+
 function formatGlobalExtensionSkipsMessage(
   skips: HotmilkRuntime["globalExtensionSkips"],
 ): string | undefined {
@@ -43,7 +61,7 @@ export function registerSessionHandlers(pi: ExtensionAPI, runtime: HotmilkRuntim
       uiNotify(HOTMILK_PARSE_ERROR_MESSAGE(runtime.configPath, runtime.configError), "warning");
     }
 
-    if (runtime.extensionToggles["gentle-ai"]) {
+    if (runtime.extensionToggles["gentle-ai"] && ctx.isProjectTrusted()) {
       seedPersonaFromDefaults(ctx.cwd, runtime.defaults);
     }
 
@@ -54,6 +72,15 @@ export function registerSessionHandlers(pi: ExtensionAPI, runtime: HotmilkRuntim
       uiNotify(globalSkipMessage, "info");
     }
 
+    if (ctx.isProjectTrusted()) {
+      const projectSkipMessage = formatProjectTrustSkipMessage(
+        detectProjectOnlyBundledSkips(ctx.cwd),
+      );
+      if (projectSkipMessage) {
+        uiNotify(projectSkipMessage, "warning");
+      }
+    }
+
     if (shouldWarnCavemanJaConflict(runtime.extensionToggles.caveman, runtime.defaults.language)) {
       uiNotify(CAVEMAN_JA_CONFLICT_MESSAGE, "warning");
     }

package/src/config/bundled-extensions.ts

@@ -128,6 +128,12 @@ export const BUNDLED_EXTENSION_DEFINITIONS = [
     module: "@tomxprime/planning-with-files/extensions/planning-with-files/index.ts",
     group: "Workflow",
   },
+  {
+    id: "plannotator",
+    package: { packageName: "@plannotator/pi-extension" },
+    module: "@plannotator/pi-extension/index.ts",
+    group: "Workflow",
+  },
   {
     id: "caveman",
     package: { packageName: "pi-caveman" },
@@ -140,6 +146,12 @@ export const BUNDLED_EXTENSION_DEFINITIONS = [
     module: "pi-red-green/dist/index.js",
     group: "Workflow",
   },
+  {
+    id: "autoresearch",
+    package: { packageName: "pi-autoresearch" },
+    module: "pi-autoresearch/extensions/pi-autoresearch/index.ts",
+    group: "Experiments",
+  },
   {
     id: "agent-dashboard",
     package: {

package/src/config/hotmilk.ts

@@ -16,11 +16,16 @@ function readBundledHotmilkTemplate(): HotmilkConfig {
   return JSON.parse(readFileSync(BUNDLED_TEMPLATE_PATH, "utf8")) as HotmilkConfig;
 }
 
+function isProjectTrustMode(value: unknown): value is ProjectTrustMode {
+  return value === "delegate" || value === "prompt" || value === "always" || value === "never";
+}
+
 function buildDefaultConfigFromTemplate(template: HotmilkConfig): {
   extensions: Record<BundledExtensionId, boolean>;
   graph: ResolvedGraphSettings;
   defaults: ResolvedDefaults;
   mcp: ResolvedMcpSettings;
+  projectTrust: ResolvedProjectTrust;
 } {
   const extensions = {} as Record<BundledExtensionId, boolean>;
   for (const id of BUNDLED_EXTENSION_IDS) {
@@ -33,6 +38,7 @@ function buildDefaultConfigFromTemplate(template: HotmilkConfig): {
 
   const language = template.defaults?.language?.trim();
   const persona = template.defaults?.persona;
+  const projectTrustMode = template.projectTrust?.mode;
 
   return {
     extensions,
@@ -47,6 +53,10 @@ function buildDefaultConfigFromTemplate(template: HotmilkConfig): {
     mcp: {
       seedOnStart: template.mcp?.seedOnStart ?? false,
     },
+    projectTrust: {
+      mode: isProjectTrustMode(projectTrustMode) ? projectTrustMode : "delegate",
+      remember: template.projectTrust?.remember ?? false,
+    },
   };
 }
 
@@ -57,6 +67,13 @@ export { BUNDLED_EXTENSION_IDS, type BundledExtensionId } from "./bundled-extens
 
 export type PersonaMode = "gentleman" | "neutral";
 
+export type ProjectTrustMode = "delegate" | "prompt" | "always" | "never";
+
+export type ResolvedProjectTrust = {
+  mode: ProjectTrustMode;
+  remember: boolean;
+};
+
 export type HotmilkConfig = {
   extensions?: Partial<Record<BundledExtensionId, boolean>>;
   graph?: {
@@ -70,6 +87,10 @@ export type HotmilkConfig = {
   mcp?: {
     seedOnStart?: boolean;
   };
+  projectTrust?: {
+    mode?: ProjectTrustMode;
+    remember?: boolean;
+  };
 };
 
 type ConfigPathResult = {
@@ -174,4 +195,5 @@ export {
   resolveDefaults,
   resolveGraphSettings,
   resolveMcpSettings,
+  resolveProjectTrust,
 } from "./resolve.ts";

package/src/config/resolve.ts

@@ -4,9 +4,11 @@ import {
   type BundledExtensionId,
   type HotmilkConfig,
   type PersonaMode,
+  type ProjectTrustMode,
   type ResolvedDefaults,
   type ResolvedGraphSettings,
   type ResolvedMcpSettings,
+  type ResolvedProjectTrust,
 } from "./hotmilk.ts";
 
 function isPersonaMode(value: unknown): value is PersonaMode {
@@ -46,3 +48,17 @@ export function resolveMcpSettings(config: HotmilkConfig): ResolvedMcpSettings {
     seedOnStart: config.mcp?.seedOnStart ?? DEFAULT_HOTMILK_CONFIG.mcp.seedOnStart,
   };
 }
+
+function isProjectTrustMode(value: unknown): value is ProjectTrustMode {
+  return value === "delegate" || value === "prompt" || value === "always" || value === "never";
+}
+
+export function resolveProjectTrust(config: HotmilkConfig): ResolvedProjectTrust {
+  const mode = config.projectTrust?.mode;
+  const remember = config.projectTrust?.remember;
+  return {
+    mode: isProjectTrustMode(mode) ? mode : DEFAULT_HOTMILK_CONFIG.projectTrust.mode,
+    remember:
+      typeof remember === "boolean" ? remember : DEFAULT_HOTMILK_CONFIG.projectTrust.remember,
+  };
+}

package/src/config/runtime.ts

@@ -6,12 +6,14 @@ import {
   type ResolvedDefaults,
   type ResolvedGraphSettings,
   type ResolvedMcpSettings,
+  type ResolvedProjectTrust,
 } from "./hotmilk.ts";
 import {
   resolveBundledExtensionToggles,
   resolveDefaults,
   resolveGraphSettings,
   resolveMcpSettings,
+  resolveProjectTrust,
 } from "./resolve.ts";
 
 export type HotmilkRuntime = {
@@ -24,6 +26,7 @@ export type HotmilkRuntime = {
   defaults: ResolvedDefaults;
   graph: ResolvedGraphSettings;
   mcp: ResolvedMcpSettings;
+  projectTrust: ResolvedProjectTrust;
 };
 
 export function createHotmilkRuntime(configRoot?: string): HotmilkRuntime {
@@ -37,5 +40,6 @@ export function createHotmilkRuntime(configRoot?: string): HotmilkRuntime {
     defaults: resolveDefaults(loaded.config),
     graph: resolveGraphSettings(loaded.config),
     mcp: resolveMcpSettings(loaded.config),
+    projectTrust: resolveProjectTrust(loaded.config),
   };
 }

package/src/index.ts

@@ -12,11 +12,14 @@ import { registerSessionHandlers } from "./bootstrap/session.ts";
 import { registerInputCommands, routeInputCommand } from "./controller/input.ts";
 import { registerHotmilkSessionLogo } from "./ui/session-logo.ts";
 import { installHotmilkCtxSearchCapture } from "./bootstrap/btw.ts";
+import { registerProjectTrustHandlers } from "./bootstrap/project-trust.ts";
 import { registerSubagentsDoctorCommand } from "./bootstrap/subagents-doctor.ts";
 
 export default async function registerHotmilk(pi: ExtensionAPI): Promise<void> {
   const runtime = createHotmilkRuntime();
 
+  registerProjectTrustHandlers(pi, runtime.projectTrust);
+
   // Register before bundled imports so session_start handlers exist when bindExtensions emits.
   registerHotmilkSessionLogo(pi);
   installHotmilkCtxSearchCapture(pi);
@@ -25,6 +28,7 @@ export default async function registerHotmilk(pi: ExtensionAPI): Promise<void> {
 
   const bundled = await registerBundledExtensions(pi, runtime.extensionToggles, {
     cwd: process.cwd(),
+    includeProjectSettings: false,
   });
   if (runtime.extensionToggles.subagents === true) {
     await registerSubagentsDoctorCommand(pi);

package/themes/monokai.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "https://raw.githubusercontent.com/badlogic/pi-mono/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json",
+  "$schema": "https://raw.githubusercontent.com/earendil-works/pi/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json",
   "name": "monokai",
   "vars": {
     "bg": "#272822",