@forwardimpact/outpost 3.12.1 → 3.13.0

package/src/outpost.js

@@ -7,7 +7,7 @@
 //   fit-outpost init [name]         Initialize a knowledge base by name (default: Team)
 //   fit-outpost update [path]       Update KB with latest CLAUDE.md, agents and skills (defaults to current directory)
 //   fit-outpost stop                Gracefully stop daemon and all running agents
-//   fit-outpost validate            Validate agent definitions exist
+//   fit-outpost validate [path]     Validate agent definitions and knowledge bases
 //   fit-outpost status              Show agent status
 //   fit-outpost --help              Show this help
 //
@@ -27,6 +27,7 @@ import { StateManager } from "./state-manager.js";
 import { AgentRunner } from "./agent-runner.js";
 import { Scheduler, formatLocalTime } from "./scheduler.js";
 import { KBManager } from "./kb-manager.js";
+import { validateKnowledgeBase } from "./kb-validator.js";
 import { SocketServer, requestShutdown, requestWake } from "./socket-server.js";
 import {
   readPosture,
@@ -40,12 +41,12 @@ const SHARE_DIR = "/usr/local/share/fit-outpost";
 
 /**
  * Build the CLI definition. This object is byte-identical to the libcli
- * definition that the golden capture used. So `--help` and `--version` output
- * stays stable.
+ * definition that the golden capture used, and `test/golden.test.js`
+ * enforces that contract. So `--help` and `--version` output stays stable.
  * @param {string} version
  * @returns {object}
  */
-function buildDefinition(version) {
+export function buildDefinition(version) {
   return {
     name: "fit-outpost",
     version,
@@ -72,7 +73,11 @@ function buildDefinition(version) {
         name: "stop",
         description: "Gracefully stop daemon and all running agents",
       },
-      { name: "validate", description: "Validate agent definitions exist" },
+      {
+        name: "validate",
+        args: "[path]",
+        description: "Validate agent definitions and knowledge bases",
+      },
       { name: "status", description: "Show agent status" },
       {
         name: "posture",
@@ -83,7 +88,10 @@ function buildDefinition(version) {
     globalOptions: {
       help: { type: "boolean", short: "h", description: "Show this help" },
       version: { type: "boolean", description: "Show version" },
-      json: { type: "boolean", description: "JSON output (with --help)" },
+      json: {
+        type: "boolean",
+        description: "JSON output (with --help and validate)",
+      },
     },
     documentation: [
       {
@@ -375,7 +383,59 @@ export async function run(runtime, version) {
     return !!found;
   }
 
+  /**
+   * Render one knowledge finding as a report line. Baselined findings warn.
+   * @param {import("./kb-validator.js").Finding} f
+   * @returns {string}
+   */
+  function formatFinding(f) {
+    const prefix = f.baselined ? "warn: " : "";
+    if (f.path !== undefined) {
+      return `${prefix}${f.path} ${f.kind}${f.message ? ` — ${f.message}` : ""}`;
+    }
+    return `${prefix}${f.file}:${f.line} ${f.kind} ${f.link ?? f.property}`;
+  }
+
+  /**
+   * Render one KB root's findings as report lines through the logger.
+   * @param {string} root - Absolute KB root path.
+   * @param {import("./kb-validator.js").Finding[]} findings
+   * @returns {void}
+   */
+  function reportFindings(root, findings) {
+    logger.info(`\nKnowledge base: ${root}`);
+    for (const f of findings) logger.info(`  ${formatFinding(f)}`);
+    if (findings.length === 0) logger.info("  OK");
+  }
+
+  /**
+   * Run the knowledge checks over each KB root. With `--json` the merged
+   * findings array is the only stdout, so tooling can parse it. A root the
+   * validator cannot read (a mistyped path, a malformed registry or
+   * baseline) fails with one clean error line instead of a stack trace.
+   * @param {string[]} roots - Absolute KB root paths.
+   * @returns {Promise<number>} 1 when any finding is not baselined, else 0.
+   */
+  async function runKnowledgeChecks(roots) {
+    const all = [];
+    for (const root of roots) {
+      let result;
+      try {
+        result = await validateKnowledgeBase(root, runtime);
+      } catch (err) {
+        cli.error(`validate failed for ${root}: ${err.message}`);
+        return 1;
+      }
+      if (!values.json) reportFindings(root, result.findings);
+      all.push(...result.findings);
+    }
+    if (values.json) proc.stdout.write(`${JSON.stringify(all)}\n`);
+    return all.some((f) => !f.baselined) ? 1 : 0;
+  }
+
   async function validate() {
+    if (args[0]) return runKnowledgeChecks([expandPath(args[0])]);
+
     const config = await loadConfig();
     const agents = Object.entries(config.agents || {});
     if (agents.length === 0) {
@@ -391,7 +451,12 @@ export async function run(runtime, version) {
     }
 
     logger.info(errors > 0 ? `\n${errors} error(s).` : "\nAll OK.");
-    return errors > 0 ? 1 : 0;
+    // The logger writes to stderr, so with --json the findings array stays
+    // the only stdout even on the no-path form.
+    const kbRoots = [
+      ...new Set(agents.map(([, a]) => a.kb).filter(Boolean)),
+    ].map(expandPath);
+    return Math.max(errors ? 1 : 0, await runKnowledgeChecks(kbRoots));
   }
 
   // --- CLI entry point -------------------------------------------------------
@@ -399,7 +464,7 @@ export async function run(runtime, version) {
   const parsed = cli.parse(proc.argv.slice(2));
   if (!parsed) return 0;
 
-  const { positionals } = parsed;
+  const { positionals, values } = parsed;
   const [command, ...args] = positionals;
 
   await fs.mkdir(OUTPOST_HOME, { recursive: true });

package/templates/.claude/agents/chief-of-staff.md

@@ -12,10 +12,17 @@ You are the chief of staff. You are the user's executive assistant. On each
 wake, synthesize what matters across email, calendar, and the knowledge graph
 into a single briefing.
 
+## Tiers
+
+Read: every tier present
+Write: none (the output is personal `Briefings/`)
+Stamp the frontmatter standard per CLAUDE.md on every note you write.
+Aggregate outputs over narrower-tier sources go to `0-Draft/`.
+
 ## Priorities
 
-`Knowledge/Priorities/` is the backbone of every briefing. Read it and
-`Knowledge/Conditions/` on each wake. `Knowledge/Conditions/` holds the live
+`Priorities/` notes in every tier present are the backbone of every briefing.
+Read them and `Conditions/` on each wake. Conditions hold the live
 constraints that shape how you pursue the priorities. See Operating Context in
 CLAUDE.md. The Inputs section below also lists both folders. Frame the whole
 briefing around what advances or threatens the user's priorities.
@@ -39,9 +46,9 @@ authoritative current-state summaries:
 - `~/.cache/fit/outpost/state/recruiter_triage.md`
 - `~/.cache/fit/outpost/state/head_hunter_triage.md`
 
-Also read these directly: `Knowledge/Priorities/`, `Knowledge/Conditions/`,
-`Drafts/`, `~/.cache/fit/outpost/apple_calendar/`, and unchecked `- [ ]` items
-in `Knowledge/`.
+Also read these directly: `Priorities/` and `Conditions/` in every tier,
+`0-Draft/`, `~/.cache/fit/outpost/apple_calendar/`, and unchecked `- [ ]`
+items across the tiers.
 
 ## Routing
 
@@ -51,7 +58,8 @@ in `Knowledge/`.
 | Noon or later  | `Briefings/{YYYY-MM-DD}-evening.md`      |
 
 A briefing covers: today's schedule with prep status, top three priority actions
-linked to `[[Priorities/...]]`, priority progress, a **Priority Watch** section
+linked with tier-prefixed links (`[[3-Team/Priorities/...]]`), priority
+progress, a **Priority Watch** section
 that consolidates the priority risks the agents flagged, inbox snapshot
 (urgent / awaiting reply), open commitments, recruitment pipeline summary, and a
 heads-up section. Evening briefings replace "Priority Actions" with "What

package/templates/.claude/agents/concierge.md

@@ -16,10 +16,17 @@ You are the concierge. You are the user's scheduling assistant. On each wake,
 keep the calendar current, prepare for upcoming meetings, and process completed
 meeting recordings.
 
+## Tiers
+
+Read: every tier present
+Write: `3-Team`
+Stamp the frontmatter standard per CLAUDE.md on every note you write.
+Aggregate outputs over narrower-tier sources go to `0-Draft/`.
+
 ## Priorities
 
-At the start of every wake, before you act, read `Knowledge/Priorities/` and
-`Knowledge/Conditions/`. The conditions constrain the priorities. See Operating
+At the start of every wake, before you act, read `Priorities/` and `Conditions/`
+in every tier present. The conditions constrain the priorities. See Operating
 Context in CLAUDE.md. The user's priorities are the lens for all your work this
 wake.
 

package/templates/.claude/agents/head-hunter.md

@@ -19,10 +19,17 @@ Benchmark promising matches. Write prospect notes for the user to review.
 
 **You never contact candidates.** Outreach is the user's call.
 
+## Tiers
+
+Read: every tier present
+Write: `2-Confidential`
+Stamp the frontmatter standard per CLAUDE.md on every note you write.
+Aggregate outputs over narrower-tier sources go to `0-Draft/`.
+
 ## Priorities
 
-At the start of every wake, before you act, read `Knowledge/Priorities/` and
-`Knowledge/Conditions/`. The conditions constrain the priorities. See Operating
+At the start of every wake, before you act, read `Priorities/` and `Conditions/`
+in every tier present. The conditions constrain the priorities. See Operating
 Context in CLAUDE.md. The user's priorities are the lens for all your work this
 wake.
 

package/templates/.claude/agents/librarian.md

@@ -14,10 +14,17 @@ skills:
 You are the librarian. You are the user's knowledge curator. On each wake,
 process new data into the knowledge graph and keep everything organized.
 
+## Tiers
+
+Read: every tier present
+Write: `3-Team`
+Stamp the frontmatter standard per CLAUDE.md on every note you write.
+Aggregate outputs over narrower-tier sources go to `0-Draft/`.
+
 ## Priorities
 
-At the start of every wake, before you act, read `Knowledge/Priorities/` and
-`Knowledge/Conditions/`. The conditions constrain the priorities. See Operating
+At the start of every wake, before you act, read `Priorities/` and `Conditions/`
+in every tier present. The conditions constrain the priorities. See Operating
 Context in CLAUDE.md. The user's priorities are the lens for all your work this
 wake.
 
@@ -42,8 +49,8 @@ Assess what to process:
 
 2. Count existing knowledge graph entities:
 
-   ls Knowledge/People/ Knowledge/Organizations/ Knowledge/Projects/
-   Knowledge/Topics/ Knowledge/Priorities/ 2>/dev/null | wc -l
+   ls 3-Team/People/ 3-Team/Organizations/ 3-Team/Projects/ 3-Team/Topics/
+   3-Team/Priorities/ 2>/dev/null | wc -l
 
 Write triage results to `~/.cache/fit/outpost/state/librarian_triage.md`:
 

package/templates/.claude/agents/postman.md

@@ -15,10 +15,17 @@ skills:
 You are the postman. You are the user's communication gatekeeper. On each wake,
 sync mail and Teams, triage what is new, and take the most valuable action.
 
+## Tiers
+
+Read: every tier present
+Write: `0-Draft`
+Stamp the frontmatter standard per CLAUDE.md on every note you write.
+Aggregate outputs over narrower-tier sources go to `0-Draft/`.
+
 ## Priorities
 
-At the start of every wake, before you act, read `Knowledge/Priorities/` and
-`Knowledge/Conditions/`. The conditions constrain the priorities. See Operating
+At the start of every wake, before you act, read `Priorities/` and `Conditions/`
+in every tier present. The conditions constrain the priorities. See Operating
 Context in CLAUDE.md. The user's priorities are the lens for all your work this
 wake.
 

package/templates/.claude/agents/recruiter.md

@@ -21,10 +21,17 @@ You are the recruiter. You are the user's engineering recruitment specialist.
 The `fit-pathway` CLI is the single source of truth for "good engineering".
 Every assessment and recommendation references the standard.
 
+## Tiers
+
+Read: every tier present
+Write: `2-Confidential`
+Stamp the frontmatter standard per CLAUDE.md on every note you write.
+Aggregate outputs over narrower-tier sources go to `0-Draft/`.
+
 ## Priorities
 
-At the start of every wake, before you act, read `Knowledge/Priorities/` and
-`Knowledge/Conditions/`. The conditions constrain the priorities. See Operating
+At the start of every wake, before you act, read `Priorities/` and `Conditions/`
+in every tier present. The conditions constrain the priorities. See Operating
 Context in CLAUDE.md. The user's priorities are the lens for all your work this
 wake.
 

package/templates/.claude/skills/anarlog-follow/SKILL.md

@@ -10,6 +10,9 @@ description: >
 
 # Anarlog Follow
 
+Write tier: none
+Frontmatter: none
+
 Follow a live Anarlog recording. Read the transcript as it grows. Coach the user
 through the meeting in real time. Gather knowledge-base context once before the
 session. Then poll the transcript. Provide actionable nudges as new content
@@ -23,16 +26,24 @@ appears.
 
 ## Prerequisites
 
-- Anarlog installed. Sessions live at
-  `~/Library/Application Support/anarlog/sessions/`.
+- Anarlog installed. Meetings live in its local SQLite database (`app.db`).
+  Read them only through Anarlog's typed, read-only interfaces. Prefer the
+  **Anarlog MCP tools** (`list_meetings`, `get_meeting`,
+  `get_meeting_transcript`) when the MCP server is connected. Fall back to the
+  **`anarlog` CLI with `--json`** otherwise. Never `grep`, crawl `sessions/`,
+  or query SQLite directly. See Anarlog's own `AGENTS.md`
+  (`~/Library/Application Support/anarlog/AGENTS.md`).
 - An active or about-to-start session.
 - A populated knowledge base (attendee / candidate context).
 
 ## Inputs
 
-- Live `transcript.json` (it grows during the session).
-- `Knowledge/People/`, `Knowledge/Candidates/{Name}/{brief,screening,panel}.md`,
-  `Knowledge/Roles/`, `Knowledge/Organizations/`, `Knowledge/Projects/`.
+- The live meeting transcript, via `get_meeting_transcript` (MCP) or
+  `anarlog --json meetings transcript <id>` (CLI). See
+  [references/sessions.md](references/sessions.md) for both interfaces.
+- `3-Team/People/`,
+  `2-Confidential/Candidates/{Name}/{brief,screening,panel}.md`,
+  `2-Confidential/Roles/`, `3-Team/Organizations/`, `3-Team/Projects/`.
 - `~/.cache/fit/outpost/apple_calendar/*.json` for context.
 
 ## Outputs
@@ -62,22 +73,30 @@ appears.
 
 #### 1. Find the active session
 
+No interface exposes a "recording now" signal. The only liveness signal is the
+most recently written `audio.mp3` on disk. This is the one deliberate
+filesystem read in this skill. All content reads go through Anarlog's
+interfaces. The session directory name **is** the meeting ID:
+
 ```bash
-node .claude/skills/anarlog-follow/scripts/follow.mjs --detect
+find "$HOME/Library/Application Support/anarlog/sessions" -maxdepth 2 \
+  -name "audio.mp3" -exec stat -f "%m %N" {} \; | sort -rn | head -5
 ```
 
-The script returns the most recently modified session, whether it is live, and
-its title. If nothing changed in the last 5 minutes, warn the user. Ask whether
-to follow a specific session. If more than one session could be active, confirm
-with the user.
+Take the top result's parent directory name as the candidate meeting ID. If
+its mtime is more than 5 minutes old, warn the user. Ask whether to follow a
+specific meeting. If more than one session could be active, confirm with the
+user.
 
-#### 2. Read session metadata
+#### 2. Read meeting metadata
+
+MCP: `get_meeting({ meeting_id })`. CLI fallback:
 
 ```bash
-node .claude/skills/anarlog-follow/scripts/follow.mjs <session-id> --meta
+anarlog --json meetings get <meeting-id>
 ```
 
-Capture **title**, **created_at**, **participants**.
+Capture **title**, **created_at**, **participants** from `data`.
 
 #### 3. Classify the meeting type
 
@@ -92,8 +111,8 @@ Phase 2 and the dimensions you track in Phase 3.
 Extract the names from the title and the participant list. For each name:
 
 ```bash
-rg -l "{name}" Knowledge/People/
-rg -l "{name}" Knowledge/Candidates/
+rg -l "{name}" 3-Team/People/
+rg -l "{name}" 2-Confidential/Candidates/
 ```
 
 Read each note you find for role, organization, history, open items, and prior
@@ -101,16 +120,17 @@ interactions.
 
 #### 5. Load type-specific context
 
-**Interviews:** read `Knowledge/Candidates/{Name}/{brief,screening,panel}.md`.
-Look up the `Req` field's matching `Knowledge/Roles/*.md` file. Check its
-`**Status:**` field for context. Then load the standard expectations:
+**Interviews:** read
+`2-Confidential/Candidates/{Name}/{brief,screening,panel}.md`. Look up the `Req`
+field's matching `2-Confidential/Roles/*.md` file. Check its `**Status:**` field
+for context. Then load the standard expectations:
 
 ```bash
 bunx fit-pathway job {discipline} {level} --track={track}
 ```
 
 **General meetings:** read attendee People notes plus referenced
-Project/Organization notes. Check open tasks: `rg "{name}" Knowledge/Tasks/`.
+Project/Organization notes. Check open tasks: `rg "{name}" 3-Team/Tasks/`.
 
 #### 6. Build the coaching brief
 
@@ -122,20 +142,24 @@ it to the user.
 
 #### 7. Read new transcript content
 
-First read (no `--after`):
-
-```bash
-node .claude/skills/anarlog-follow/scripts/follow.mjs <session-id>
-```
-
-Subsequent reads (pass the last word ID):
+MCP: `get_meeting_transcript({ meeting_id, offset, limit: 500 })`. CLI
+fallback:
 
 ```bash
-node .claude/skills/anarlog-follow/scripts/follow.mjs <session-id> --after <last-word-id>
+anarlog --json meetings transcript <meeting-id> --offset <offset> --limit 500
 ```
 
-The script returns JSON with grouped text segments, channel labels, and the next
-last-word ID.
+First read: `offset` = 0. Each later read: `offset` = the `pagination.total`
+from the previous read. That fetches only the words added since then. When a
+page comes back full and `next_offset < pagination.total`, keep paging with
+`next_offset` until you catch up. Track `total` across reads. It is your next
+offset.
+
+`data.words` is a flat array of `{ channel, text, start_ms, end_ms }`. Group
+consecutive words into segments yourself. Start a new segment on a channel
+change or a >3s gap between one word's `end_ms` and the next word's
+`start_ms`. Channel `0` = user. Channel `1`+ = guest(s) (a heuristic, per
+Anarlog's own docs).
 
 #### 8. Analyze new content
 

package/templates/.claude/skills/anarlog-follow/references/sessions.md

@@ -0,0 +1,52 @@
+# Anarlog Meeting Data
+
+Reference for `anarlog-follow` Phases 1 and 3. Anarlog stores meetings in a
+local SQLite database (`~/Library/Application Support/anarlog/app.db`). Read
+them through Anarlog's typed, read-only interfaces. Its own `AGENTS.md`
+(`~/Library/Application Support/anarlog/AGENTS.md`) is explicit:
+
+> Use Anarlog's typed, read-only interfaces for meeting data. Do not use
+> `find`, `grep`, `rg`, filesystem crawling, or direct SQLite queries.
+
+**Prefer the MCP tools** when the `anarlog` MCP server is connected. **Fall
+back to the CLI** (`anarlog --json ...`) otherwise. Never guess a meeting ID.
+Phase 1 resolves it from the freshest `audio.mp3` on disk (the one signal
+neither interface exposes). Every other read goes through one of the two
+interfaces below.
+
+## `get_meeting` / `meetings get <id>`
+
+MCP: `get_meeting({ meeting_id })`. CLI:
+`anarlog --json meetings get <meeting-id>`.
+
+Returns `title`, `created_at`, `participants` (`{ human_id, display_name,
+email, role, job_title, organization_name }`, often sparse), `note`,
+`summaries`, `action_items`. For a live meeting, `note` and `summaries` are
+usually thin or empty. That is expected. They fill in once the meeting ends.
+Use this once per session, in Phase 1 Step 2, to capture the pre-meeting brief
+inputs.
+
+## `get_meeting_transcript` / `meetings transcript <id>`
+
+MCP: `get_meeting_transcript({ meeting_id, offset, limit })`. CLI:
+`anarlog --json meetings transcript <meeting-id> --offset <n> --limit <n>`
+(`limit` capped at 500 by both interfaces).
+
+```json
+{ "meeting_id": "…", "text": "Yeah, so the overall …",
+  "words": [ { "channel": 0, "text": " Yeah,", "start_ms": 0, "end_ms": 400 } ] }
+```
+
+`pagination.total` is the running word count. Use it as the next poll's
+`offset` so you fetch only the words added since the last read. Page with
+`next_offset` when a single poll returns a full page and more remain. Channel
+`0` = user, channel `1`+ = guest(s) — a heuristic, not guaranteed.
+
+## The one filesystem exception: liveness detection
+
+Neither interface reports which meeting is currently recording. The only
+signal for that lives on disk: the most recently written `audio.mp3` under
+`~/Library/Application Support/anarlog/sessions/{uuid}/`, where the directory
+name is the meeting ID. This skill touches the filesystem for exactly that one
+lookup (Phase 1 Step 1) and nothing else. Every read of meeting *content*
+goes through `get_meeting` / `get_meeting_transcript`.