syndes 0.1.0

package/practices/budget.mjs

@@ -0,0 +1,97 @@
+/**
+ * The noise governor, and the most important file in this directory.
+ *
+ * A coaching tool that cannot be shut up gets uninstalled, and an uninstalled
+ * ledger records nothing. The budget is not a nicety — it is what keeps the
+ * ledger alive.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, renameSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { coachFile } from '../runtime/paths.mjs';
+import { localDay } from '../analytics/ranges.mjs';
+import { debug } from '../runtime/log.mjs';
+
+/** Three dismissals and the rule stops asking. It does not get a fourth chance. */
+const DISMISSALS_TO_MUTE = 3;
+
+export function load() {
+  try {
+    return JSON.parse(readFileSync(coachFile, 'utf8'));
+  } catch {
+    return { lastByRule: {}, sent: {}, dismissed: {}, muted: [], snoozedUntil: 0 };
+  }
+}
+
+export function save(state) {
+  try {
+    mkdirSync(dirname(coachFile), { recursive: true });
+    const staging = `${coachFile}.tmp`;
+    writeFileSync(staging, `${JSON.stringify(state, null, 2)}\n`);
+    renameSync(staging, coachFile);
+  } catch (error) {
+    debug('coach state save failed', error.message);
+  }
+}
+
+/** @returns {{allowed: boolean, reason: string|null}} */
+export function allows(state, ruleId, config, now = Date.now()) {
+  if (!config.coach.enabled) return { allowed: false, reason: 'coaching is off' };
+  if (now < (state.snoozedUntil ?? 0)) return { allowed: false, reason: 'snoozed' };
+  if (state.muted?.includes(ruleId) || config.coach.muted?.includes(ruleId)) {
+    return { allowed: false, reason: 'muted' };
+  }
+
+  const today = localDay(now);
+  const sentToday = state.sent?.[today] ?? 0;
+  if (sentToday >= config.coach.maxPerDay) return { allowed: false, reason: 'daily budget spent' };
+
+  const last = state.lastByRule?.[ruleId] ?? 0;
+  const cooldown = config.coach.cooldownHours * 3_600_000;
+  if (now - last < cooldown) return { allowed: false, reason: 'cooling down' };
+
+  return { allowed: true, reason: null };
+}
+
+export function record(state, ruleId, now = Date.now()) {
+  const today = localDay(now);
+  state.lastByRule ??= {};
+  state.sent ??= {};
+  state.lastByRule[ruleId] = now;
+  state.sent[today] = (state.sent[today] ?? 0) + 1;
+
+  // Keep the counter file from growing forever; two weeks is plenty of history.
+  for (const day of Object.keys(state.sent)) {
+    if (Object.keys(state.sent).length > 14 && day < today) delete state.sent[day];
+  }
+  return state;
+}
+
+export function dismiss(state, ruleId) {
+  state.dismissed ??= {};
+  state.dismissed[ruleId] = (state.dismissed[ruleId] ?? 0) + 1;
+  if (state.dismissed[ruleId] >= DISMISSALS_TO_MUTE) {
+    state.muted ??= [];
+    if (!state.muted.includes(ruleId)) state.muted.push(ruleId);
+  }
+  return state;
+}
+
+export function mute(state, ruleId) {
+  state.muted ??= [];
+  if (!state.muted.includes(ruleId)) state.muted.push(ruleId);
+  return state;
+}
+
+export function unmute(state, ruleId) {
+  state.muted = (state.muted ?? []).filter((id) => id !== ruleId);
+  state.dismissed && delete state.dismissed[ruleId];
+  return state;
+}
+
+export function snooze(state, ms, now = Date.now()) {
+  state.snoozedUntil = now + ms;
+  return state;
+}
+
+export { DISMISSALS_TO_MUTE };

package/practices/catalog.mjs

@@ -0,0 +1,64 @@
+/**
+ * The human-readable half of every rule: what it is called, the one line the
+ * user sees, why it matters, and what to actually do.
+ *
+ * Separated from detection so wording can be edited and tuned without touching
+ * logic that has tests pinned to it.
+ */
+
+export const CATALOG = {
+  'read-before-edit': {
+    title: 'Editing files blind',
+    why: 'An edit to a file the session has not read is the strongest single predictor of an edit that has to be redone. The model is writing against a guess at the current contents.',
+    fix: 'Ask for the file to be read first, or point at the exact function rather than the file.',
+  },
+  'batch-tool-calls': {
+    title: 'One tool call per turn',
+    why: 'Independent calls issued in one turn cost one round-trip. The same calls spread across separate turns cost one round-trip each, plus the input tokens of the whole conversation again every time.',
+    fix: 'Ask for the reads or searches you need together — "read these four files" rather than four requests.',
+  },
+  'verify-after-change': {
+    title: 'Changes are not being verified',
+    why: 'A run of edits with no test, build or typecheck between them and the end of the session is the loop that feels productive and lands broken.',
+    fix: 'End a change with the project\'s check command, and say which one it is up front.',
+  },
+  'context-hygiene': {
+    title: 'Sessions keep running out of context',
+    why: 'An automatic compaction means the window filled up and had to be summarised. Everything after it is working from a lossy summary, and you paid full price for the tokens that got discarded.',
+    fix: 'Start a fresh session per task, and put the standing context in CLAUDE.md so it does not have to be re-explained.',
+  },
+  'prompt-specificity': {
+    title: 'A lot of prompts are corrections',
+    why: 'A correction means the previous turn missed. The cost is not the correction — it is the whole turn that was thrown away, at full token price.',
+    fix: 'Name the file, the function and the expected outcome in the first prompt.',
+  },
+  'delegate-wide-search': {
+    title: 'Wide searches are running in the main thread',
+    why: 'Every grep result lands in your context and stays there for the rest of the session. A subagent reads the same files and returns only the conclusion.',
+    fix: 'For "where is X handled" questions, ask for a subagent to search and report back.',
+  },
+  'permission-friction': {
+    title: 'The same permission prompt keeps stopping you',
+    why: 'Each stop is a context switch, and you are answering the same question repeatedly. This one is fixable in about ten seconds.',
+    fix: 'Add the tool to the allowlist in settings.json, or run /permissions.',
+  },
+  'retry-storm': {
+    title: 'A command is being retried unchanged',
+    why: 'The same failing command run again with nothing changed in between cannot succeed, and each attempt spends tokens on the same error output.',
+    fix: 'Stop the loop and read the error yourself, or say explicitly what changed.',
+  },
+  'session-sprawl': {
+    title: 'Sessions are staying open far longer than they are used',
+    why: 'A long-idle session is not free: resuming it carries the whole accumulated context, and it makes every per-hour figure in your own metrics meaningless.',
+    fix: 'Close a session when the task is done. Start the next one fresh.',
+  },
+  'project-memory': {
+    title: 'A project you work in often has no CLAUDE.md',
+    why: 'Without it, the same background — how to run tests, where things live, house style — is re-established from scratch every session, at full token price each time.',
+    fix: 'Run /init in that project, or write a short CLAUDE.md by hand.',
+  },
+};
+
+export function describe(id) {
+  return CATALOG[id] ?? { title: id, why: '', fix: '' };
+}

package/practices/deliver.mjs

@@ -0,0 +1,101 @@
+/**
+ * Nudge → the right channel for the moment.
+ *
+ * Every nudge carries its evidence — "you edited src/app.ts 6 times in 12
+ * minutes without running tests", not "consider running tests". A nudge without
+ * evidence is a fortune cookie, and people stop reading fortune cookies.
+ */
+
+import { writeFileSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { stateDir } from '../runtime/paths.mjs';
+import { notify } from '../notify/index.mjs';
+import { debug } from '../runtime/log.mjs';
+
+const CARD_FILE = join(stateDir, 'card.txt');
+
+export async function deliver(finding, config) {
+  const channels = [];
+
+  if (config.coach.channels.notification) {
+    const sent = await notify({
+      title: 'SynDes',
+      subtitle: finding.title,
+      message: finding.evidence,
+    });
+    if (sent) channels.push('notification');
+  }
+
+  if (config.coach.channels.terminal) {
+    if (writeCard(finding)) channels.push('terminal');
+  }
+
+  return { channels };
+}
+
+/**
+ * The terminal channel: a card the next SessionStart hook prints.
+ *
+ * The worker cannot write into a running session, so it leaves the card here.
+ * Plain text, because this is printed by a hook whose stdout Claude Code reads —
+ * anything cleverer risks becoming model context instead of a message.
+ */
+function writeCard(finding) {
+  const width = 72;
+  const line = '─'.repeat(width - 2);
+
+  // Every wrap width is the row's usable space minus its own indent. Getting
+  // this wrong makes a line both wrap AND truncate, which is how you end up
+  // with an ellipsis mid-sentence followed by the rest of the sentence.
+  const body = (text) => wrap(text, width - 4).map((part) => row(`  ${part}`, width));
+  // The arrow marks the start of an instruction, so continuation lines are
+  // indented under it rather than repeating it.
+  const bullet = (text) => wrap(text, width - 6)
+    .map((part, index) => row(index === 0 ? `  → ${part}` : `    ${part}`, width));
+
+  const rows = [
+    `\n┌${line}┐`,
+    row(`SynDes · ${finding.title}`, width),
+    `├${line}┤`,
+    ...body(finding.evidence),
+    row('', width),
+    ...bullet(finding.fix),
+    ...(finding.action ? bullet(finding.action) : []),
+    `└${line}┘`,
+    `  syndes dashboard for the detail · syndes mute ${finding.id} to stop this\n`,
+  ];
+
+  try {
+    mkdirSync(dirname(CARD_FILE), { recursive: true });
+    writeFileSync(CARD_FILE, rows.join('\n'));
+    return true;
+  } catch (error) {
+    debug('card write failed', error.message);
+    return false;
+  }
+}
+
+function row(text, width) {
+  const inner = width - 2;
+  const clipped = text.length > inner ? `${text.slice(0, inner - 1)}…` : text;
+  return `│${clipped.padEnd(inner)}│`;
+}
+
+function wrap(text, width) {
+  if (!text) return [];
+  const words = String(text).split(/\s+/);
+  const lines = [];
+  let current = '';
+  for (const word of words) {
+    if ((`${current} ${word}`).trim().length > width) {
+      if (current) lines.push(current.trim());
+      current = word;
+    } else {
+      current = `${current} ${word}`;
+    }
+  }
+  if (current.trim()) lines.push(current.trim());
+  return lines;
+}
+
+export { CARD_FILE, wrap };

package/practices/engine.mjs

@@ -0,0 +1,107 @@
+/**
+ * Evaluate practice rules over a window and pick at most one nudge.
+ *
+ * Runs ONLY at breakpoints — Stop, SessionEnd, SubagentStop. Never mid-turn.
+ * Interrupting someone to tell them to work better is self-defeating design.
+ *
+ * A rule is { id, pillar, severity, window, detect(merged) → evidence | null }.
+ * detect() is pure over pre-computed metrics, so rules are unit-testable against
+ * a fixture ledger and adding one costs nothing at runtime.
+ */
+
+import { RULES, ruleById } from './rules/index.mjs';
+import { describe } from './catalog.mjs';
+import * as budget from './budget.mjs';
+import { deliver } from './deliver.mjs';
+import { loadConfig } from '../runtime/config.mjs';
+import { rangeFor } from '../analytics/ranges.mjs';
+import { rollupsFor, mergeRollups } from '../analytics/rollup.mjs';
+import { append } from '../ledger/append.mjs';
+import { draft, KIND } from '../ledger/schema.mjs';
+import { debug } from '../runtime/log.mjs';
+
+/**
+ * Evaluate every rule and return what fired, regardless of budget.
+ *
+ * This is what the dashboard shows: the full picture, including rules that are
+ * firing but muted. Hiding a muted finding would make the mute look like a fix.
+ */
+export async function evaluate({ now = Date.now() } = {}) {
+  const config = loadConfig();
+  const state = budget.load();
+  const cache = new Map();
+  const findings = [];
+
+  for (const rule of RULES) {
+    let merged = cache.get(rule.window);
+    if (!merged) {
+      merged = mergeRollups(await rollupsFor(rangeFor(rule.window, now)));
+      cache.set(rule.window, merged);
+    }
+
+    let hit = null;
+    try {
+      hit = rule.detect(merged);
+    } catch (error) {
+      // A broken rule must not take the coach down with it.
+      debug('rule failed', rule.id, error.message);
+      continue;
+    }
+    if (!hit) continue;
+
+    const gate = budget.allows(state, rule.id, config, now);
+    findings.push({
+      id: rule.id,
+      pillar: rule.pillar,
+      severity: rule.severity,
+      window: rule.window,
+      ...describe(rule.id),
+      ...hit,
+      deliverable: gate.allowed,
+      blockedBy: gate.reason,
+      lastSent: state.lastByRule?.[rule.id] ?? null,
+      muted: (state.muted ?? []).includes(rule.id),
+    });
+  }
+
+  // Most severe first, then whichever has gone longest without being said.
+  findings.sort((a, b) => b.severity - a.severity || (a.lastSent ?? 0) - (b.lastSent ?? 0));
+  return findings;
+}
+
+/**
+ * Evaluate, pick one, deliver it, and write it into the ledger.
+ *
+ * Exactly one per run. The alternative is a wall of advice at every Stop, which
+ * is how a coach becomes something you learn to scroll past.
+ */
+export async function runCoach({ now = Date.now(), force = false } = {}) {
+  const config = loadConfig();
+  if (!config.coach.enabled && !force) return { sent: null, reason: 'coaching is off' };
+
+  const findings = await evaluate({ now });
+  const chosen = findings.find((finding) => finding.deliverable || force);
+  if (!chosen) {
+    return { sent: null, reason: findings.length ? findings[0].blockedBy : 'nothing to say', findings };
+  }
+
+  const delivered = await deliver(chosen, config);
+
+  const state = budget.record(budget.load(), chosen.id, now);
+  budget.save(state);
+
+  // The nudge goes into the ledger too. What the coach told you, and when, is
+  // part of the record — otherwise the advice is unauditable.
+  await append([draft(KIND.COACH, {
+    ts: now,
+    data: {
+      rule: chosen.id, pillar: chosen.pillar, severity: chosen.severity,
+      value: chosen.value ?? null, evidence: chosen.evidence,
+      channels: delivered.channels,
+    },
+  })]);
+
+  return { sent: chosen, channels: delivered.channels, findings };
+}
+
+export { RULES, ruleById, budget };

package/practices/rules/batch-tool-calls.mjs

@@ -0,0 +1,15 @@
+/** Independent calls issued one per turn instead of batched. */
+export default {
+  id: 'batch-tool-calls',
+  pillar: 'tools',
+  severity: 2,
+  window: '7d',
+  detect({ tokens }) {
+    if ((tokens?.turnsWithTools ?? 0) < 30) return null;
+    if (tokens.callsPerTurn >= 1.3) return null;
+    return {
+      value: tokens.callsPerTurn,
+      evidence: `${tokens.callsPerTurn.toFixed(2)} tool calls per turn across ${tokens.turnsWithTools} turns — almost every call is its own round-trip`,
+    };
+  },
+};

package/practices/rules/context-hygiene.mjs

@@ -0,0 +1,17 @@
+/** Sessions repeatedly hitting the context ceiling. */
+export default {
+  id: 'context-hygiene',
+  pillar: 'context',
+  severity: 3,
+  window: '7d',
+  detect({ context, volume }) {
+    const sessions = volume?.sessionCount ?? 0;
+    if (sessions < 3 || !context?.autoCompacts) return null;
+    const rate = context.autoCompacts / sessions;
+    if (rate < 0.8) return null;
+    return {
+      value: rate,
+      evidence: `${context.autoCompacts} automatic compactions across ${sessions} sessions — the window filled up and had to be summarised`,
+    };
+  },
+};

package/practices/rules/delegate-wide-search.mjs

@@ -0,0 +1,15 @@
+/** Wide searching in the main thread, where the results stay in context. */
+export default {
+  id: 'delegate-wide-search',
+  pillar: 'tools',
+  severity: 1,
+  window: '7d',
+  detect({ tools }) {
+    if ((tools?.searchViaBash ?? 0) < 25) return null;
+    if ((tools?.delegations ?? 0) > 2) return null;
+    return {
+      value: tools.searchViaBash,
+      evidence: `${tools.searchViaBash} searches ran through Bash and none were delegated — every result is still sitting in your context`,
+    };
+  },
+};

package/practices/rules/index.mjs

@@ -0,0 +1,28 @@
+/**
+ * Rule registry.
+ *
+ * Imported explicitly rather than discovered by scanning the directory: an
+ * implicit registry makes a broken rule silently absent, and a coach that
+ * quietly stops noticing things is worse than one that fails loudly.
+ */
+
+import readBeforeEdit from './read-before-edit.mjs';
+import batchToolCalls from './batch-tool-calls.mjs';
+import verifyAfterChange from './verify-after-change.mjs';
+import contextHygiene from './context-hygiene.mjs';
+import promptSpecificity from './prompt-specificity.mjs';
+import delegateWideSearch from './delegate-wide-search.mjs';
+import permissionFriction from './permission-friction.mjs';
+import retryStorm from './retry-storm.mjs';
+import sessionSprawl from './session-sprawl.mjs';
+import projectMemory from './project-memory.mjs';
+
+export const RULES = [
+  readBeforeEdit, batchToolCalls, verifyAfterChange, contextHygiene,
+  promptSpecificity, delegateWideSearch, permissionFriction, retryStorm,
+  sessionSprawl, projectMemory,
+];
+
+export function ruleById(id) {
+  return RULES.find((rule) => rule.id === id) ?? null;
+}

package/practices/rules/permission-friction.mjs

@@ -0,0 +1,16 @@
+/** The same permission prompt, over and over. Names the exact allowlist entry. */
+export default {
+  id: 'permission-friction',
+  pillar: 'flow',
+  severity: 2,
+  window: '7d',
+  detect({ friction }) {
+    const worst = friction?.worstOffender;
+    if (!worst || worst.count < 6) return null;
+    return {
+      value: worst.count,
+      evidence: `"${worst.target}" stopped you ${worst.count} times, costing about ${Math.round((friction.blockedMs ?? 0) / 60_000)} minutes`,
+      action: `allow: ${worst.target}`,
+    };
+  },
+};

package/practices/rules/project-memory.mjs

@@ -0,0 +1,27 @@
+/** A project worked in repeatedly with no CLAUDE.md to carry its context. */
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { loadProjects } from '../../collect/projects.mjs';
+
+export default {
+  id: 'project-memory',
+  pillar: 'context',
+  severity: 1,
+  window: '30d',
+  detect({ volume }) {
+    const known = loadProjects();
+    for (const id of volume?.projects ?? []) {
+      const project = known[id];
+      if (!project?.root) continue;
+      // Checked at evaluation time, not recorded in the ledger: a file the user
+      // added yesterday should silence this rule today.
+      if (existsSync(join(project.root, 'CLAUDE.md'))) continue;
+      return {
+        value: id,
+        evidence: `"${project.name}" has no CLAUDE.md, so its background is re-established from scratch every session`,
+        action: `cd ${project.root} && claude, then /init`,
+      };
+    }
+    return null;
+  },
+};

package/practices/rules/prompt-specificity.mjs

@@ -0,0 +1,15 @@
+/** A high share of prompts that read as corrections. */
+export default {
+  id: 'prompt-specificity',
+  pillar: 'prompts',
+  severity: 2,
+  window: '7d',
+  detect({ prompts }) {
+    if ((prompts?.count ?? 0) < 15) return null;
+    if (prompts.correctionRate <= 0.15) return null;
+    return {
+      value: prompts.correctionRate,
+      evidence: `${prompts.corrections} of ${prompts.count} prompts were corrections of the previous turn (median prompt: ${prompts.medianWords} words)`,
+    };
+  },
+};

package/practices/rules/read-before-edit.mjs

@@ -0,0 +1,16 @@
+/** Editing files the session never read. */
+export default {
+  id: 'read-before-edit',
+  pillar: 'tools',
+  severity: 3,
+  window: '7d',
+  detect({ tools }) {
+    const edits = (tools?.readFirst ?? 0) + (tools?.blindEdit ?? 0);
+    if (edits < 8 || tools.readBeforeEditRate === null) return null;
+    if (tools.readBeforeEditRate >= 0.7) return null;
+    return {
+      value: tools.readBeforeEditRate,
+      evidence: `${tools.blindEdit} of your last ${edits} edits changed a file the session had not read`,
+    };
+  },
+};

package/practices/rules/retry-storm.mjs

@@ -0,0 +1,22 @@
+/** The same failing command run again with nothing changed. */
+export default {
+  id: 'retry-storm',
+  pillar: 'feedback',
+  severity: 2,
+  window: '7d',
+  detect({ rework }) {
+    if ((rework?.stormCount ?? 0) < 2) return null;
+
+    const worst = [...(rework.storms ?? [])].sort((a, b) => b.streak - a.streak)[0];
+    if (!worst) {
+      return { value: rework.stormCount, evidence: `${rework.stormCount} commands were retried 3+ times without a change` };
+    }
+
+    const [tool, target = ''] = worst.key.split('|');
+    const label = `${tool} ${target}`.trim();
+    return {
+      value: rework.stormCount,
+      evidence: `"${label}" failed ${worst.streak} times in a row with nothing changed in between`,
+    };
+  },
+};

package/practices/rules/session-sprawl.mjs

@@ -0,0 +1,15 @@
+/** Long wall-clock sessions with little active time in them. */
+export default {
+  id: 'session-sprawl',
+  pillar: 'flow',
+  severity: 1,
+  window: '7d',
+  detect({ time }) {
+    if (!time?.wallMs || time.wallMs < 4 * 3_600_000) return null;
+    if ((time.activeShare ?? 1) >= 0.25) return null;
+    return {
+      value: time.activeShare,
+      evidence: `${Math.round(time.wallMs / 3_600_000)}h of open sessions held ${Math.round(time.activeMs / 3_600_000)}h of actual work`,
+    };
+  },
+};

package/practices/rules/verify-after-change.mjs

@@ -0,0 +1,16 @@
+/** Runs of edits that never end in a test or build. */
+export default {
+  id: 'verify-after-change',
+  pillar: 'feedback',
+  severity: 3,
+  window: '7d',
+  detect({ rework }) {
+    const runs = (rework?.verifiedRuns ?? 0) + (rework?.unverifiedRuns ?? 0);
+    if (runs < 5 || rework.verifyRate === null) return null;
+    if (rework.verifyRate >= 0.5) return null;
+    return {
+      value: rework.verifyRate,
+      evidence: `${rework.unverifiedRuns} of ${runs} runs of edits ended without a test, build or typecheck`,
+    };
+  },
+};