@aitne-sh/aitne 0.1.7 → 0.1.8

package/agent-assets/templates/rules/journal-format.md

@@ -2,8 +2,8 @@
 type: rule
 slug: journal-format
 owner: user
-updated: 2026-04-17
-template_version: 1
+updated: 2026-05-16
+template_version: 3
 ---
 # Daily journal — format template
 
@@ -13,49 +13,156 @@ reads it as a **format spec** (body structure, required/optional sections,
 voice) — it does NOT follow this as code; natural-language guidance is
 fine.
 
+## Framing — this is the user's diary
+
+`daily/<date>.md` is the **user's diary**, not the agent's behavior
+log. It records the user's day: what the user did, what the user
+talked about, what was on their schedule. The agent is the author
+because the human user doesn't journal by hand — but the perspective,
+voice, and content all belong to the user.
+
+Agent-side bookkeeping (action counts, internal anomalies, audit
+trail) lives in `agent/journal.md` — not here. If you find yourself
+about to log "the agent ran N tools today" or "the hourly check
+fired M times", that belongs in the agent-side log instead. Filter
+it out.
+
+The daemon's `journal-skeleton-builder`
+(`docs/design/appendices/morning-routine-optimization.md` §"Daemon-side
+modules to add" — Phase 2 daemon primitive) emits scratch data
+(`## Schedule`, `## Tasks`, `## Conversations`) read from SQLite +
+yesterday.md. Stage B **authors the entire body** per the section
+list below, using the scratch sections as input data — the skeleton
+sections are NOT preserved verbatim. Only the skeleton-owned
+frontmatter MUST be preserved byte-for-byte; the daemon's daily-write
+chokepoint validates frontmatter drift with
+`context.skeleton_field_drift` and rejects the PUT with 422. Body
+content (section names, ordering, prose) is Stage B's responsibility
+and not validated for drift.
+
 ## Required frontmatter fields
-- `date`, `weekday`, `type: daily`, `agent_generated: true`
-- `agent_last_synced_at`, `content_hash`
+
+Skeleton-owned (preserved byte-for-byte by Stage B):
+- `date`, `weekday`, `type: daily`, `owner: agent`, `agent_generated: true`
+- `calendar_events: <count>` — total calendar events filtered to the
+  agent-day window
+- `messages_handled: <count>` — **incoming user messages only**
+  (`messages.role='user'` rows within the agent-day window). Agent
+  replies and internal `system` rows are excluded so the value
+  matches "how many messages did the user send today" rather than
+  total conversation turns. (Field name kept for backward
+  compatibility with already-written daily journals; a future rename
+  to `messages_received` is deferred.)
+- `updated: <YYYY-MM-DD>` — today's agent-day, stamped by the daemon
+  at skeleton-build time. The generic context-frontmatter validator
+  requires this field on every `daily/*.md` PUT; emitting it from the
+  daemon (instead of leaving it as a Stage-B placeholder) eliminates
+  the 422 failure mode where Stage B forgot to fill the slot.
+
+Stage B-owned (filled from the narrative Stage B authors):
+- `agent_last_synced_at` (ISO 8601), `content_hash` (`sha256:<hex>`)
 - `projects: [...]`, `people: [...]`, `tags: [...]`
-- `calendar_events: <count>`, `messages_handled: <count>`
-
-## Required body sections (in order)
-1. `# YYYY-MM-DD (Weekday)` — title
-2. `## Summary` — 1 paragraph, 3–5 sentences, first-person voice
-3. `## Schedule` — actual events (from calendar + today.md), time — title,
-   flag attended/skipped
-4. `## What moved forward` — bullets of real progress, work + personal
-   separated if meaningful
-5. `## Conversations` — key DM/mail exchanges only:
-   `### <Name> — <channel>, HH:MM → HH:MM` with one-line summary
-6. `## Decisions` — bullets
-7. `## Open threads` — checkboxes (`- [ ] ...`)
-8. `## Tomorrow hook` — 1–2 sentences pointing to the next day's focus
-
-## Optional sections (include only when relevant)
-- `## Meetings` — if ≥1 meeting (time — title — outcome)
-- `## Reading / Learning` — books / articles / courses touched
-- `## Health / mood` — ONLY if explicitly logged by user
-
-## Voice
-- First-person ("I shipped...", "I met with..."), concise, factual
+
+## Required body sections (Stage B output order)
+
+Stage B authors each section below. Annotations describe the scratch
+data Stage B reads from the daemon-emitted skeleton; the skeleton
+section names happen to match the output section names, but Stage B
+remains free to reshape data, add bullets, drop a section on a sparse
+day, etc.
+
+1. `# YYYY-MM-DD (Weekday)` — title. Stage B emits verbatim from the
+   skeleton's title line.
+2. `## Summary` — **one paragraph, 3–5 sentences, first-person voice
+   from the user's perspective**. Authored entirely by Stage B (no
+   skeleton placeholder). Placed first so the reader's eye lands on
+   the narrative synthesis before the raw-fact sections that follow
+   (TL;DR-at-top reading order matching the pre-rev2 daily journal
+   corpus the user has accumulated). The voice is **the user's**, not
+   the agent's — "I shipped X", "I met with Y", "I felt rushed about
+   Z". Don't write about what the agent did ("the agent triaged 4
+   inbox items") — that's footprint, not diary content.
+3. `## Schedule` — yesterday's events the user attended (or had
+   planned). Each line is `- HH:MM — <title>` for timed events, `-
+   <title>` for all-day. `- (none)` when the day carried no events.
+   Stage B reads the skeleton's `## Schedule` scratch section as
+   input; may add `(attended)` / `(skipped)` flags from yesterday
+   context.
+4. `## Tasks` — yesterday's `## User Tasks` carried forward, checkbox
+   markers stripped, `(none)` placeholder filtered. These are the
+   things the user was meant to do — keep them user-side (not
+   agent-side schedule rows). `- (none)` when yesterday had no User
+   Tasks. Stage B reads the skeleton's `## Tasks` scratch section as
+   input.
+5. `## Conversations` — **what the user talked about that day**, as
+   topic-level bullets. Stage B reads the skeleton's
+   `## Conversations` scratch section (rolling DM summaries with
+   HH:MM + message counts) and synthesises **2–5 topic bullets** in
+   the user's voice, e.g. `- Discussed Q2 roadmap with the agent —
+   agreed to defer feature X`. The HH:MM and `(n=N)` markers from
+   the scratch input are NOT preserved verbatim; they're inputs for
+   topic synthesis, not output structure. `- (none)` when no DM
+   activity. Skip mechanical per-thread enumeration — collapse to
+   topics.
+
+**Sections deliberately NOT in the daily journal:**
+
+- ❌ Agent action counts (`agent_actions` breakdown by type). Lives
+  in `agent/journal.md` instead — the audit-trail footprint.
+- ❌ Internal stage status, retry counts, anomalies. Same as above.
+- ❌ "The agent did X for the user" framing. The user's diary uses
+  user voice; agent meta-narration belongs in the agent-side log.
+
+## Voice (`## Summary` and `## Conversations`)
+
+- First-person **from the user's perspective** ("I shipped...", "I
+  met with...", "I asked the agent about..."), concise, factual
 - Written in `settings.primary_language`; keep technical terms in their
   original form if that's how the user writes them
+- Refers to the entities Stage B surfaces in the body sections that
+  follow (the meetings under `## Schedule`, the tasks under
+  `## Tasks`, the topics under `## Conversations`) so the narrative
+  reads as a synthesis of those facts, not a separate stream of
+  consciousness
 
 ## Wikilink rendering
-- When `settings.vault_mode` is `obsidian`, render project / people
-  references as `[[wikilinks]]` targeting `projects/<slug>.md` or
-  `user/people.md#<person>` (basename resolves automatically).
-- When `vault_mode` is `plain`, write plain text only — no double
-  brackets, no link markup.
+
+- When `settings.vault_mode` is `obsidian`, Stage B renders project /
+  people references throughout the body as `[[wikilinks]]` targeting
+  `projects/<slug>.md` or `user/people.md#<person>` (basename resolves
+  automatically). The `## Summary` paragraph is the primary surface,
+  but data sections may also receive wikilinks where a project / person
+  name appears (e.g. a meeting title containing a person's name).
+- When `vault_mode` is `plain`, Stage B writes plain text only — no
+  double brackets, no link markup.
+- The skeleton's scratch sections do not embed wikilinks; Stage B
+  applies them as it authors the final body.
 
 ## Redaction
-- Apply `rules/redaction.md` patterns (always)
-- Apply `rules/journal-export.md` user rules (always)
-- If yesterday.md frontmatter had `no_journal_export: true`, write the
-  placeholder `[Skipped by user request]` and no body
+
+- Apply `rules/redaction.md` patterns to the entire body Stage B
+  authors (Summary + data sections both — Stage B owns the body, so
+  redaction applies wherever sensitive content might surface).
+- Apply `rules/journal-export.md` user rules to the entire body.
+- If yesterday.md frontmatter had `no_journal_export: true`, write
+  `[Skipped by user request]` as the body of `## Summary` and omit
+  the data sections (they would echo information the export rule is
+  trying to suppress).
+
+The skeleton's scratch sections carry data sourced from upstream
+writers (calendar observer, yesterday.md `## User Tasks`, the
+`dm_conversation_log` rolling-summary writer). Stage B SHOULD apply
+redaction during authoring; but the *primary* defence belongs
+**upstream** — if a credit-card number is appearing in
+`dm_conversation_log` summaries, fix the rolling-summary writer
+rather than relying on Stage B as the last line of defence. Stage
+B's redaction is a backstop, not a safety net.
 
 ## Conflict behavior
-- Follow B-006 content-hash protection: if the user edited the previous
-  day's `daily/<date>.md`, append `## Agent revision — <timestamp>` rather
-  than overwrite.
+
+Follow B-006 content-hash protection: if the user edited the previous
+day's `daily/<date>.md`, append `## Agent revision — <ISO timestamp>`
+rather than overwrite. The Agent revision section may carry a fresh
+Summary + any updated data sections. The original body the user
+edited is preserved verbatim above the Agent revision boundary;
+Stage B does NOT rewrite sections the user touched.

package/agent-assets/templates/user/expertise.md

@@ -1,7 +1,9 @@
 ---
 type: user
 owner: shared
-updated: 2026-04-21
-template_version: 1
+updated: 2026-05-18
+template_version: 2
 ---
 # Expertise
+
+## Tools

package/agent-assets/templates/user/goals.md

@@ -1,7 +1,9 @@
 ---
 type: user
 owner: shared
-updated: 2026-04-21
-template_version: 1
+updated: 2026-05-18
+template_version: 2
 ---
 # Goals
+
+## Learning

package/agent-assets/templates/user/people.md

@@ -1,7 +1,13 @@
 ---
 type: user
 owner: shared
-updated: 2026-04-21
-template_version: 1
+updated: 2026-05-18
+template_version: 2
 ---
 # People
+
+## Family
+
+## Colleagues
+
+## Friends

package/agent-assets/templates/user/personal.md

@@ -1,7 +1,9 @@
 ---
 type: user
 owner: shared
-updated: 2026-04-21
-template_version: 1
+updated: 2026-05-18
+template_version: 2
 ---
 # Personal
+
+## Habits

package/agent-assets/templates/user/work.md

@@ -1,7 +1,9 @@
 ---
 type: user
 owner: shared
-updated: 2026-04-21
-template_version: 1
+updated: 2026-05-18
+template_version: 2
 ---
 # Work
+
+## Stack

package/bin/aitne.mjs

@@ -989,6 +989,11 @@ Operations:
   open                              Open dashboard root in browser
   doctor                            Diagnose install (Node, ports, keychain, CLIs, …)
   audit [--since <dur>] [--type X]  Show agent action log (filterable)
+  run-now <job>                     Fire a daemon-internal maintenance job
+                                    on demand (e.g. roadmap_maintenance)
+  verify [target]                   Run post-launch verification for a
+                                    shipped design surface (e.g.
+                                    evening-review-slimdown)
   version                           Print version + Node + install path
   update                            Print npm command to upgrade
   uninstall                         Stop, then offer to wipe ${path.basename(DATA_DIR) || "data dir"}
@@ -1016,7 +1021,7 @@ Run 'aitne help <command>' for detailed usage of a single command.`);
 // Used by `aitne help <cmd>` to dispatch into the module rather than duplicating
 // usage strings in cmdHelp() above.
 const PER_COMMAND_HELP = new Set([
-  "doctor", "audit", "setup", "open", "version", "update", "uninstall",
+  "doctor", "audit", "setup", "open", "version", "update", "uninstall", "run-now", "verify",
 ]);
 
 /**
@@ -1069,6 +1074,8 @@ switch (subcommand) {
   case "open":      await runExternalCommand("open", subArgs); break;
   case "doctor":    await runExternalCommand("doctor", subArgs); break;
   case "audit":     await runExternalCommand("audit", subArgs); break;
+  case "run-now":   await runExternalCommand("run-now", subArgs); break;
+  case "verify":    await runExternalCommand("verify", subArgs); break;
 
   // version / -v / --version all dispatch identically — passing subArgs
   // through so `aitne --version --json` yields the same output as

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aitne-sh/aitne",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "Aitne — a local-first, proactive personal AI agent. A long-running TypeScript daemon is the nervous system; Claude Code (or Codex / Gemini CLI) is the brain. All persistent memory lives in local Markdown files.",
   "keywords": [
     "ai",
@@ -43,9 +43,9 @@
     "README.md"
   ],
   "dependencies": {
-    "@aitne/daemon": "0.1.7",
-    "@aitne/dashboard": "0.1.7",
-    "@aitne/shared": "0.1.7"
+    "@aitne/daemon": "0.1.8",
+    "@aitne/dashboard": "0.1.8",
+    "@aitne/shared": "0.1.8"
   },
   "devDependencies": {
     "@typescript-eslint/eslint-plugin": "^8.58.1",

package/scripts/commands/doctor.mjs

@@ -37,6 +37,8 @@ Exit code:
     await checkPort("Dashboard port", ctx.DASHBOARD_PORT, ctx.DASHBOARD_PID_FILE, ctx.helpers.getRunningPid),
     await checkSecretStore(ctx),
     await checkBackendCli(),
+    await checkProcessProbe(),
+    await checkBrowserOpener(),
     await checkDataDirWritable(ctx.DATA_DIR),
     await checkBetterSqlite3(ctx.PROJECT_ROOT),
     await checkAgentAssets(ctx.PROJECT_ROOT),
@@ -221,6 +223,56 @@ async function checkBackendCli() {
   };
 }
 
+/**
+ * Process-listing primitive — `pgrep` on POSIX, `tasklist` on Windows. The
+ * Obsidian observer uses this to ask "is the desktop app currently open?"
+ * before treating the vault as live (services/obsidian.ts). Warn (not fail)
+ * because every other observer keeps working without it.
+ */
+async function checkProcessProbe() {
+  const isWin = process.platform === "win32";
+  const tool = isWin ? "tasklist" : "pgrep";
+  if (whichSync(tool)) {
+    return { status: "pass", label: "Process probe", detail: `${tool} on PATH` };
+  }
+  return {
+    status: "warn",
+    label: "Process probe",
+    detail: `${tool} not on PATH`,
+    hint: isWin
+      ? "tasklist ships with Windows — check that %SystemRoot%\\System32 is on PATH."
+      : process.platform === "linux"
+        ? "apt install procps  · or equivalent for your distro."
+        : "pgrep ships with macOS in-box; check $PATH.",
+  };
+}
+
+/**
+ * Browser opener used by `aitne open` and the auto-open after `aitne start`.
+ * darwin → `open`, win32 → `cmd` (hosts the `start` builtin), linux → `xdg-open`.
+ * Warn-only: nothing in the daemon depends on this; users can navigate to
+ * the dashboard URL by hand if missing.
+ */
+async function checkBrowserOpener() {
+  const platform = process.platform;
+  const tool =
+    platform === "darwin" ? "open"
+      : platform === "win32" ? "cmd"
+        : "xdg-open";
+  if (whichSync(tool)) {
+    return { status: "pass", label: "Browser opener", detail: `${tool} on PATH` };
+  }
+  return {
+    status: "warn",
+    label: "Browser opener",
+    detail: `${tool} not on PATH`,
+    hint:
+      platform === "linux"
+        ? "apt install xdg-utils  · or open http://localhost:3000 manually after `aitne start`."
+        : "Auto-open is a convenience; the dashboard URL works in any browser.",
+  };
+}
+
 async function checkDataDirWritable(dataDir) {
   try {
     fs.mkdirSync(dataDir, { recursive: true });

package/scripts/commands/run-now.mjs

@@ -0,0 +1,202 @@
+/**
+ * `aitne run-now <job>` — fire a daemon-internal maintenance job on
+ * demand.
+ *
+ * Currently supported jobs:
+ *   - `roadmap_maintenance` — mechanical roadmap.md maintenance pass
+ *     (substeps 2a / 2b / 2d of the legacy `routine.evening_review`
+ *     Step 2). Same code path the 17:45 cron callback fires. See
+ *     `docs/design/appendices/evening-review-slimdown.md` §2.2.
+ *
+ * Implementation:
+ *   - Reads the daemon's apiToken from the macOS Keychain (the same
+ *     entry the dashboard proxy uses). Bearer-auth required because
+ *     `POST /api/agent/run-now/*` routes are Approve-tier in the
+ *     `risk-classifier`.
+ *   - POSTs to `http://127.0.0.1:<PA_API_PORT>/api/agent/run-now/<job>`.
+ *   - Renders the structured `result` payload as a compact summary
+ *     plus the full JSON on `--json`.
+ *
+ * Exit codes:
+ *   - 0  job completed (including idempotent / no-op runs)
+ *   - 2  validation / argument error
+ *   - 3  daemon not running, not reachable, or 5xx
+ *   - 4  result.status === "failed" — the job reported errors[]
+ */
+import { execFileSync } from "node:child_process";
+
+const SUPPORTED_JOBS = new Set(["roadmap_maintenance"]);
+
+const JOB_ENDPOINTS = {
+  roadmap_maintenance: "/api/agent/run-now/roadmap-maintenance",
+};
+
+export async function run(args, ctx) {
+  if (args.includes("--help") || args.includes("-h")) {
+    printHelp();
+    return;
+  }
+  const opts = parseArgs(args);
+  if (!opts.job) {
+    process.stderr.write("Job is required.\n");
+    process.stderr.write("Available jobs: " + [...SUPPORTED_JOBS].join(", ") + "\n");
+    process.stderr.write("Run `aitne help run-now` for usage.\n");
+    process.exit(2);
+  }
+
+  if (!SUPPORTED_JOBS.has(opts.job)) {
+    process.stderr.write(`Unknown job: ${opts.job}\n`);
+    process.stderr.write("Available jobs: " + [...SUPPORTED_JOBS].join(", ") + "\n");
+    process.exit(2);
+  }
+
+  const token = readApiToken();
+  if (!token) {
+    process.stderr.write(
+      "Failed to read daemon API token from the macOS Keychain.\n" +
+        "Is the daemon initialized? Run `aitne start` once first.\n",
+    );
+    process.exit(3);
+  }
+
+  const endpoint = JOB_ENDPOINTS[opts.job];
+  const url = `http://127.0.0.1:${ctx.DAEMON_PORT}${endpoint}`;
+
+  let res;
+  try {
+    res = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${token}`,
+      },
+      body: JSON.stringify({}),
+    });
+  } catch (err) {
+    process.stderr.write(`Failed to reach the daemon at ${url}: ${err.message}\n`);
+    process.stderr.write("Is the daemon running? Try `aitne status`.\n");
+    process.exit(3);
+  }
+
+  const text = await res.text();
+  let body;
+  try {
+    body = JSON.parse(text);
+  } catch {
+    body = { raw: text };
+  }
+
+  if (!res.ok) {
+    process.stderr.write(
+      `POST ${endpoint} → ${res.status}: ${body.error ?? "unknown"}\n`,
+    );
+    if (body.message) process.stderr.write(`${body.message}\n`);
+    process.exit(res.status >= 500 ? 3 : 2);
+  }
+
+  if (opts.json) {
+    process.stdout.write(JSON.stringify(body, null, 2) + "\n");
+  } else {
+    printSummary(opts.job, body.result ?? body);
+  }
+
+  const status = body?.result?.status;
+  if (status === "failed") process.exit(4);
+}
+
+function parseArgs(args) {
+  const opts = { job: null, json: false };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--json") {
+      opts.json = true;
+      continue;
+    }
+    if (a.startsWith("-")) {
+      process.stderr.write(`Unknown flag: ${a}\n`);
+      process.exit(2);
+    }
+    if (opts.job) {
+      process.stderr.write(`Unexpected positional argument: ${a}\n`);
+      process.exit(2);
+    }
+    opts.job = a;
+  }
+  return opts;
+}
+
+function readApiToken() {
+  try {
+    return execFileSync(
+      "security",
+      [
+        "find-generic-password",
+        "-s",
+        "com.personal-agent.secret.apiToken",
+        "-w",
+      ],
+      { encoding: "utf-8" },
+    ).trim();
+  } catch {
+    return null;
+  }
+}
+
+function printSummary(job, result) {
+  if (job === "roadmap_maintenance") {
+    if (!result || typeof result !== "object") {
+      process.stdout.write("(no result payload)\n");
+      return;
+    }
+    const status = result.status ?? "unknown";
+    const lines = [
+      `status:           ${status}`,
+      `status_synced:    ${result.statusSynced ?? 0}`,
+      `swept:            ${result.swept ?? 0}`,
+      `stale_marked:     ${result.staleMarked ?? 0}`,
+    ];
+    if (result.skipReason) lines.push(`skip_reason:      ${result.skipReason}`);
+    if (Array.isArray(result.errors) && result.errors.length > 0) {
+      lines.push(`errors:           ${result.errors.length}`);
+      for (const err of result.errors) {
+        lines.push(`  - ${err.step}: ${err.message}`);
+      }
+    }
+    process.stdout.write(lines.join("\n") + "\n");
+    return;
+  }
+  process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+}
+
+function printHelp() {
+  process.stdout.write(`Usage: aitne run-now <job> [--json]
+
+Fire a daemon-internal maintenance job on demand. Uses the same code
+path the cron schedule fires — useful for parallel-verification
+rollouts and operator debugging.
+
+Jobs:
+  roadmap_maintenance   Run the mechanical roadmap.md maintenance pass
+                        (substeps 2a / 2b / 2d). Acquires roadmap write
+                        lock, syncs Scheduled: statuses, sweeps aged
+                        Agent Action Plan entries, and applies
+                        Long-term Plans stale markers. Emits an
+                        \`agent_actions\` audit row with
+                        action_type='roadmap_mechanical_maintenance'
+                        and appends a line to agent/journal.md.
+
+Flags:
+  --json    Emit the full JSON result instead of the summary.
+  -h, --help  Print this message.
+
+Exit codes:
+  0   completed (success / skipped)
+  2   argument / validation error
+  3   daemon unreachable or 5xx
+  4   the job ran but reported errors[]
+
+Examples:
+  aitne run-now roadmap_maintenance
+  aitne run-now roadmap_maintenance --json
+`);
+}