@forwardimpact/outpost 3.12.0 → 3.13.0

package/README.md

@@ -2,8 +2,8 @@
 
 <!-- BEGIN:description — Do not edit. Generated from package.json. -->
 
-Personal operations center — context from email, calendar, and knowledge
-assembled so preparation is continuous, not a morning scramble.
+Personal operations center — context assembled from email, calendar, and
+knowledge so preparation is continuous instead of a morning scramble.
 
 <!-- END:description -->
 

package/bin/fit-outpost.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
-// Thin entry point — the sole construction site for the runtime collaborator
-// bag, threaded into src/outpost.js's dispatch via run(runtime, version).
+// This file is the thin entry point. It is the sole construction site for the
+// runtime collaborator bag. It threads that bag into the dispatch in
+// src/outpost.js through run(runtime, version).
 import "@forwardimpact/libpreflight/node22";
 
 import { resolveVersion } from "@forwardimpact/libcli";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@forwardimpact/outpost",
-  "version": "3.12.0",
-  "description": "Personal operations center — context from email, calendar, and knowledge assembled so preparation is continuous, not a morning scramble.",
+  "version": "3.13.0",
+  "description": "Personal operations center — context assembled from email, calendar, and knowledge so preparation is continuous instead of a morning scramble.",
   "homepage": "https://www.forwardimpact.team",
   "repository": {
     "type": "git",
@@ -14,12 +14,12 @@
     {
       "user": "Empowered Engineers",
       "goal": "Be Prepared and Productive",
-      "trigger": "Walking into a meeting cold because context was scattered across email, Slack, and last week's notes.",
+      "trigger": "The engineer walks into a meeting cold because context is scattered across email, Slack, and last week's notes.",
       "bigHire": "keep track of people, projects, and threads without depending on memory.",
       "littleHire": "walk into every meeting already oriented.",
       "competesWith": "morning email scan; re-reading calendar invites; personal notes; asking colleagues for context",
       "forces": {
-        "push": "Context-switching compounds; starting cold wastes everyone's time.",
+        "push": "Context-switching compounds. Starting cold wastes everyone's time.",
         "pull": "Continuous awareness without continuous effort — context assembled.",
         "habit": "Morning routines and tracking systems that feel 'good enough.'",
         "anxiety": "Delegating awareness to a system feels like losing control."
@@ -51,7 +51,8 @@
     "@forwardimpact/libcli": "^0.1.0",
     "@forwardimpact/libpreflight": "^0.1.0",
     "@forwardimpact/libtelemetry": "^0.1.33",
-    "@forwardimpact/libutil": "^0.1.0"
+    "@forwardimpact/libutil": "^0.1.0",
+    "yaml": "^2.9.0"
   },
   "devDependencies": {
     "@forwardimpact/libmock": "^0.1.0"

package/src/agent-path.js

@@ -1,15 +1,19 @@
 /**
- * agent-path — validate a config-supplied agent name before using it as a
+ * agent-path — validate a config-supplied agent name before you use it as a
  * filesystem path component.
  *
  * The agent-state writer maps an agent name to a per-agent state filename.
- * A name carrying `/` or `..` segments would let a rewritten `scheduler.json`
- * direct writes outside `~/.cache/fit/outpost/state/`. This module validates
- * and rejects rather than silently sanitising, so an unexpected path segment
- * surfaces as an intrusion signal instead of a quietly rewritten filename.
+ * A name that carries `/` or `..` segments would let a rewritten
+ * `scheduler.json` direct writes outside `~/.cache/fit/outpost/state/`. This
+ * module validates the name and rejects an unsafe one. It never sanitises the
+ * name silently. So an unexpected path segment surfaces as an intrusion
+ * signal. It does not become a quietly rewritten filename.
  */
 
-/** Raised when an agent name cannot map to a safe state-file prefix. */
+/**
+ * `agentNameToStatePrefix` raises this when an agent name cannot map to a
+ * safe state-file prefix.
+ */
 export class UnsafeAgentNameError extends Error {
   /** @param {string} name */
   constructor(name) {

package/src/agent-runner.js

@@ -15,14 +15,14 @@ import { resolvePrivilege, disclaimFor } from "./privilege.js";
 import { buildSpawnEnv } from "./spawn-env.js";
 
 /**
- * System-prompt directive injected under the `brief` posture. Neutralises any
- * draft-side prose in a materialised agent definition and forbids writing the
- * posture record.
+ * The system-prompt directive the runner injects under the `brief` posture. It
+ * neutralises any draft-side prose in a materialised agent definition. It also
+ * forbids a write to the posture record.
  */
 const BRIEF_DIRECTIVE =
   "Adoption posture: brief. Run only read-and-brief work. Do not draft or " +
-  "send content on the user's behalf for delivery to anyone else, do not move " +
-  "or write files outside the knowledge base, and never write the posture " +
+  "send content on the user's behalf for delivery to anyone else. Do not " +
+  "move or write files outside the knowledge base. Never write the posture " +
   "record (~/.fit/outpost/posture.json).";
 
 /** Spawn agent CLI processes, capture their output, and update agent state. */
@@ -41,11 +41,11 @@ export class AgentRunner {
 
   /**
    * @param {Object | (() => Object | Promise<{default?: Object}>)} spawn -
-   *   The posix-spawn module, or a (possibly async) loader returning it. A
-   *   loader lets the Bun-FFI module load lazily so plain `node` invocations
-   *   that never wake an agent don't pull in `bun:ffi`.
+   *   The posix-spawn module, or a loader that returns it. The loader may be
+   *   async. A loader lets the Bun-FFI module load lazily. So a plain `node`
+   *   invocation that never wakes an agent does not pull in `bun:ffi`.
    * @param {import('./state-manager.js').StateManager} stateManager
-   * @param {Function} logFn - Logging function
+   * @param {Function} logFn - The function that writes a log line
    * @param {string} cacheDir - Cache directory for state files
    * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime
    *   Injected runtime bag (uses `fs` (async), `proc`, `clock`).
@@ -84,8 +84,8 @@ export class AgentRunner {
   }
 
   /**
-   * Resolve the injected spawn collaborator to the posix-spawn module,
-   * invoking and unwrapping a loader thunk on first use.
+   * Resolve the injected spawn collaborator to the posix-spawn module. On
+   * first use, invoke a loader thunk and unwrap it.
    * @returns {Promise<Object>}
    */
   async #resolveSpawn() {
@@ -97,7 +97,7 @@ export class AgentRunner {
   }
 
   /**
-   * Test whether a path exists, via the async fs surface.
+   * Test whether a path exists, through the async fs surface.
    * @param {string} p
    * @returns {Promise<boolean>}
    */
@@ -148,11 +148,12 @@ export class AgentRunner {
   }
 
   /**
-   * Resolve the spawn flags the recorded posture adds. Under `brief` (also the
-   * default when no posture is recorded), deny every draft-side skill by name
-   * and inject the brief directive — a deterministic gate the woken agent
-   * cannot override under `bypassPermissions`. Under `brief+draft`, add
-   * nothing. The posture record is read here, never written.
+   * Resolve the spawn flags the recorded posture adds. Under `brief`, deny
+   * every draft-side skill by name and inject the brief directive. `brief` is
+   * also the default when no posture is recorded. The directive is a
+   * deterministic gate. The woken agent cannot override it under
+   * `bypassPermissions`. Under `brief+draft`, add nothing. This method reads
+   * the posture record. It never writes the record.
    * @returns {Promise<string[]>} Extra args to append to the spawn argv.
    */
   async #postureArgs() {
@@ -170,17 +171,20 @@ export class AgentRunner {
   }
 
   /**
-   * Validate the agent's kb path exists, spawn `claude --agent` with the prompt "Observe and act.", and update agent state to active/idle/failed.
+   * Validate that the agent's kb path exists. Spawn `claude --agent` with the
+   * prompt "Observe and act." Then update the agent state to active, idle, or
+   * failed.
    * @param {string} agentName
    * @param {Object} agent
    * @param {Object} state
    * @param {Record<string, string>} [configEnv] - Extra env vars from config
    */
   async wake(agentName, agent, state, configEnv) {
-    // Resolve the mandatory privilege level before any work. A missing or
-    // invalid level is fail-closed: log and skip the wake — no agent process is
-    // spawned with a guessed privilege. The level lives in the user-only trust
-    // root, so a spawned agent cannot raise its own.
+    // Resolve the mandatory privilege level before any work. The runner is
+    // fail-closed on a missing or invalid level. It logs the problem and skips
+    // the wake. It never spawns an agent process with a guessed privilege. The
+    // level lives in the user-only trust root, so a spawned agent cannot raise
+    // its own.
     let level;
     try {
       level = resolvePrivilege(agent);
@@ -196,13 +200,13 @@ export class AgentRunner {
     }
 
     if (!agent.kb) {
-      this.#log(`Agent ${agentName}: no "kb" specified, skipping.`);
+      this.#log(`Agent ${agentName}: no "kb" specified. Skipped.`);
       return;
     }
     const kbPath = this.#expandPath(agent.kb);
     if (!(await this.#exists(kbPath))) {
       this.#log(
-        `Agent ${agentName}: path "${kbPath}" does not exist, skipping.`,
+        `Agent ${agentName}: path "${kbPath}" does not exist. Skipped.`,
       );
       return;
     }

package/src/index.js

@@ -1,5 +1,4 @@
 // Public entry point for @forwardimpact/outpost.
-// Outpost is primarily a CLI — this file exists so the package conforms
-// to the repo-wide layout contract. The runtime CLI dispatch lives in
-// src/outpost.js.
+// Outpost is primarily a CLI. This file exists so the package conforms to the
+// repo-wide layout contract. The runtime CLI dispatch lives in src/outpost.js.
 export * from "./outpost.js";

package/src/kb-manager.js

@@ -6,7 +6,9 @@ import { join, dirname, resolve, basename } from "node:path";
 import { homedir } from "node:os";
 import { createLogger } from "@forwardimpact/libtelemetry";
 
-/** Manage knowledge base lifecycle including initialization, updates, and settings merging. */
+import { LEGACY_ROOTS } from "./kb-validator.js";
+
+/** Manage the knowledge base lifecycle: init, update, and settings merge. */
 export class KBManager {
   #fs;
   #logger;
@@ -25,12 +27,13 @@ export class KBManager {
 
   /**
    * Resolve a knowledge-base name to its path under the XDG data home,
-   * `~/.local/share/fit/outpost/<name>`. The argument is a single path segment,
-   * never an arbitrary filesystem path, so a provisioned KB always lands outside
-   * TCC-protected folders. The name is validated — not sanitised — against the
-   * same rule as `agent-path.js`: a name carrying `/`, `\`, `..`, NUL, or a
-   * leading `~` could steer the KB back inside `~/Documents`, reopening the TCC
-   * hole, so it is rejected rather than rewritten.
+   * `~/.local/share/fit/outpost/<name>`. The argument is a single path
+   * segment. It is never an arbitrary filesystem path. So a provisioned KB
+   * always lands outside TCC-protected folders. This method validates the name
+   * against the same rule as `agent-path.js`. It does not sanitise the name. A
+   * name that carries `/`, `\`, `..`, NUL, or a leading `~` could steer the KB
+   * back inside `~/Documents` and reopen the TCC hole. So this method rejects
+   * the name. It never rewrites the name.
    * @param {string} name - The KB name (e.g. `Team`, `personal`).
    * @returns {string} Absolute path under the data home.
    * @throws {Error} when `name` is empty, non-string, or an unsafe segment.
@@ -51,7 +54,7 @@ export class KBManager {
   }
 
   /**
-   * Test whether a path exists, via the async fs surface.
+   * Test whether a path exists, through the async fs surface.
    * @param {string} p
    * @returns {Promise<boolean>}
    */
@@ -94,7 +97,7 @@ export class KBManager {
   }
 
   /**
-   * Copy bundled files (CLAUDE.md, skills, agents) from template to a KB.
+   * Copy bundled files (CLAUDE.md, skills, agents) from the template to a KB.
    * @param {string} tpl - Path to the template directory
    * @param {string} dest - Path to the target knowledge base
    * @returns {Promise<void>}
@@ -156,7 +159,7 @@ export class KBManager {
   }
 
   /**
-   * Merge template settings.json into the destination's settings.json.
+   * Merge the template settings.json into the destination's settings.json.
    * @param {string} tpl - Template directory
    * @param {string} dest - Knowledge base directory
    * @returns {Promise<void>}
@@ -206,14 +209,23 @@ export class KBManager {
     }
 
     await this.#ensureDir(dest);
-    // Create the top-level roots only. `Knowledge/` is the shared graph (synced
-    // with the team); `Drafts/` and `Briefings/` are personal and local. Entity
-    // subdirectories (People, Organizations, ...) are created on demand by the
-    // skills that write into them.
-    for (const d of ["Knowledge", "Drafts", "Briefings"])
+    // Create the tier directories and the personal `Briefings/` root only.
+    // The numbered tiers are the knowledge graph and the units of sharing;
+    // every other root entry is personal. The skills that write into the
+    // entity subdirectories (People, Organizations, ...) create them on
+    // demand inside each tier.
+    for (const d of [
+      "0-Draft",
+      "1-Management",
+      "2-Confidential",
+      "3-Team",
+      "4-Public",
+      "Briefings",
+    ])
       await this.#ensureDir(join(dest, d));
 
     await this.copyBundledFiles(templateDir, dest);
+    await this.#installRegistry(templateDir, dest);
     await this.#linkIntoDocuments(dest);
 
     this.#logger.info(
@@ -223,12 +235,13 @@ export class KBManager {
   }
 
   /**
-   * Create a navigation symlink at `~/Documents/<name>` pointing to the KB.
+   * Create a navigation symlink at `~/Documents/<name>` that points to the KB.
    * The KB data itself stays under the XDG data home, outside TCC-protected
-   * folders — this is only a convenience pointer so the KB is easy to find and
-   * open from Finder. Best-effort: a pre-existing entry is left untouched, and
-   * any failure (e.g. macOS denying write access to `~/Documents`) is logged,
-   * never fatal, because the KB is already provisioned at `dest`.
+   * folders. The symlink is only a convenience pointer. It makes the KB easy
+   * to find and open from Finder. The method is best-effort. It leaves a
+   * pre-existing entry untouched. It logs any failure, for example when macOS
+   * denies write access to `~/Documents`. A failure is never fatal, because
+   * the KB is already provisioned at `dest`.
    * @param {string} dest - Absolute path to the provisioned KB.
    * @returns {Promise<void>}
    */
@@ -263,10 +276,52 @@ export class KBManager {
       };
     }
     await this.copyBundledFiles(templateDir, dest);
+    await this.#installRegistry(templateDir, dest);
+    await this.#installMigrationGuide(templateDir, dest);
     this.#logger.info(`\nKnowledge base updated: ${dest}`);
     return { ok: true, value: { dest } };
   }
 
+  /**
+   * Install the default `registry.yaml` when the KB has none. The registry
+   * is a personal surface humans edit, so this method never overwrites an
+   * existing one. `copyBundledFiles` copies named files only and never picks
+   * it up.
+   * @param {string} tpl - Template directory
+   * @param {string} dest - Knowledge base directory
+   * @returns {Promise<void>}
+   */
+  async #installRegistry(tpl, dest) {
+    const src = join(tpl, "registry.yaml");
+    const destPath = join(dest, "registry.yaml");
+    if (!(await this.#exists(src)) || (await this.#exists(destPath))) return;
+    await this.#fs.copyFile(src, destPath);
+    this.#logger.info(`  Installed registry.yaml`);
+  }
+
+  /**
+   * Install MIGRATION.md while the KB still carries a legacy layout
+   * (`Knowledge/` or `Drafts/` at the root). A conforming KB never receives
+   * it, and this method removes nothing.
+   * @param {string} tpl - Template directory
+   * @param {string} dest - Knowledge base directory
+   * @returns {Promise<void>}
+   */
+  async #installMigrationGuide(tpl, dest) {
+    let legacy = false;
+    for (const marker of LEGACY_ROOTS) {
+      if (await this.#exists(join(dest, marker))) legacy = true;
+    }
+    if (!legacy) return;
+    await this.#fs.copyFile(
+      join(tpl, "MIGRATION.md"),
+      join(dest, "MIGRATION.md"),
+    );
+    this.#logger.info(
+      `  Installed MIGRATION.md — this knowledge base carries the legacy layout. Follow it to migrate to tiers.`,
+    );
+  }
+
   /**
    * @param {string} p
    * @returns {string}