Add active/ hygiene guardrail — flag completed-not-archived notes + ungrouped multi-file topics

[breferrari]

Summary

Add a lightweight, no-LLM guardrail that keeps work/active/ honest by surfacing two drift modes automatically: (1) notes marked done but never archived, and (2) related notes piling up loose in the active/ root that should be grouped into a folder. Wired into the SessionStart and Stop hooks (nudge-only) and the weekly review (where you act on it).

Motivation

active/ is meant to hold only current work, but it rots predictably:

• Completed notes stay because "archive later" never comes. A status: completed note in active/ pollutes the SessionStart task aggregation and any status-filtered Base view.
• A workstream spawns meetings/reports that scatter as loose files in the root instead of grouping, until the folder feels disorganized.

Both are invisible until someone notices. This makes them visible on a cadence, with zero enforcement.

Design

New shared lib .claude/scripts/lib/active-hygiene.ts, consumed by both hooks. Two detectors, both conservative (false negatives preferred over nagging — same philosophy as the existing org-change detector in stop-checklist.ts):

1. completed-not-archived — recursively scan work/active/**.md; flag any whose frontmatter status ∈ {completed, archived, done}. Reuses extractFrontmatterField from lib/session-start.ts.

2. ungrouped multi-file topic — among notes directly in the active/ root (subfoldered = already grouped), tokenise titles (strip a leading YYYY-MM-DD prefix, lowercase, drop tokens <4 chars, numerics, and a small generic-process stopword list: report/sync/plan/notes/draft/meeting/review/…). Flag a token shared by ≥2 root notes. Guards against noise:

   • Document-frequency cap: a token in >50% of root notes is treated as a generic vault-wide term (e.g. a team/element name), not a topic → dropped. This is what makes it safe without a vault-specific stopword list.
   • Min-root threshold: stay silent until the root has ≥4 loose notes — folders are for taming size, not ceremony.

formatActiveHygiene(report) returns [] when clean, so callers emit nothing.

Wiring

• SessionStart hook: conditional ### Vault Hygiene (active/ drift) section, appended only when there are findings (silent when clean).
• Stop hook: append findings under the existing wrap-up checklist.
• /om-weekly: a new "active/ Hygiene Sweep" step — the hooks flag, the weekly is where you act (archive / group / mark stale).
• CLAUDE.md: codify the two conventions this enforces —
  • Date naming: YYYY-MM-DD prefix for point-in-time notes (meetings, syncs, retros, prep); bare title for living project/concept notes.
  • Folder grouping: a workstream with >1 note gets active/<Topic>/ holding the project note + its sub-notes; mirror in archive/YYYY/.

Files

• lib/active-hygiene.ts (new), tests/active-hygiene.test.ts (new)
• session-start.ts, stop-checklist.ts (wire-in, ~6 lines each)
• commands/om-weekly.md, CLAUDE.md (docs/conventions)

Testing

10 unit tests over fixtures (mkdtemp): status detection incl. recursion, cluster detection, stopword + DF guard + min-root behaviour, date-prefix stripping, and the renderer. Full suite stays green.

Out of scope / config

• Never moves files — nudge only.
• Thresholds (DF cap 50%, min 4 root files, stopword list) are constants; could be vault-manifest.json-configurable in a follow-up if desired.

[breferrari]

Reference implementation — already built and tested in a live vault, sanitized here. Mostly drop-in.

.claude/scripts/lib/active-hygiene.ts

/**
 * Active-folder hygiene scan — shared by the SessionStart and Stop hooks.
 *
 * Surfaces the two drift modes that let `work/active/` rot:
 *
 *   1. COMPLETED-NOT-ARCHIVED — a note whose frontmatter `status` is
 *      `completed`/`archived` but is still sitting in `work/active/`. A
 *      completed note in active/ is a bug: it pollutes the SessionStart
 *      task aggregation and any status-filtered Base, and it's how the pile
 *      forms (every deferred archive starts here).
 *
 *   2. UNGROUPED MULTI-FILE TOPIC — two or more notes sitting loose in the
 *      active/ root (not in a subfolder) that share a distinctive topic
 *      token. Convention: once a workstream has >1 note, it gets a folder
 *      (`active/<Topic>/`). This catches clusters before they scatter.
 *
 * Pattern-based, no LLM, conservative. NUDGES — never moves files. False
 * negatives (missing a cluster) are preferred over false positives, so the
 * cluster detector leans on a document-frequency guard: a token shared by
 * more than half the root notes is treated as a generic vault-wide word
 * (e.g. a team name), not a groupable topic.
 */

import { readdirSync, readFileSync, type Dirent } from "node:fs";
import { join } from "node:path";
import { extractFrontmatterField, isMarkdownFilename } from "./session-start.ts";

const ACTIVE_REL = "work/active";

// Frontmatter status values that mean "this should not be in active/".
const ARCHIVABLE_STATUS = new Set(["completed", "archived", "done"]);

// Generic process / artifact words that must never anchor a topic cluster.
// The document-frequency guard catches vault-specific generic terms (team /
// element names) automatically; this list only needs the universal process
// noise. Tune per vault if you like — it's a safety belt, not the mechanism.
const STOPWORDS = new Set([
	"the", "and", "for", "with", "from", "into", "that", "this",
	"report", "plan", "sync", "call", "prep", "notes", "doc", "document",
	"meeting", "review", "draft", "log", "update", "summary", "status",
	"investigation", "analysis", "audit", "discovery", "kickoff", "tracker",
]);

// Strip a leading `YYYY-MM-DD ` date prefix and the `.md` extension, then
// tokenise the title into lowercased alphanumeric words.
function titleTokens(filename: string): string[] {
	const title = filename
		.replace(/\.md$/i, "")
		.replace(/^\d{4}-\d{2}-\d{2}\s+/, "");
	return title
		.toLowerCase()
		.split(/[^a-z0-9]+/)
		.filter((t) => t.length >= 4 && !/^\d+$/.test(t) && !STOPWORDS.has(t));
}

export type TopicCluster = {
	readonly token: string;
	readonly files: readonly string[]; // root-level filenames
};

export type ActiveHygieneReport = {
	readonly completedInActive: readonly string[]; // vault-relative paths
	readonly ungroupedClusters: readonly TopicCluster[];
};

// Recursively collect .md files under a directory, relative to `root`.
// Tolerates a missing directory (returns []).
function walkMarkdown(root: string, relDir: string): string[] {
	let entries: Dirent[];
	try {
		entries = readdirSync(join(root, relDir), { withFileTypes: true });
	} catch {
		return [];
	}
	const out: string[] = [];
	for (const e of entries) {
		const rel = `${relDir}/${e.name}`;
		if (e.isDirectory()) out.push(...walkMarkdown(root, rel));
		else if (e.isFile() && isMarkdownFilename(e.name)) out.push(rel);
	}
	return out;
}

function findCompletedInActive(root: string): string[] {
	const found: string[] = [];
	for (const rel of walkMarkdown(root, ACTIVE_REL)) {
		let content: string;
		try {
			content = readFileSync(join(root, rel), "utf-8");
		} catch {
			continue;
		}
		const status = extractFrontmatterField(content, "status");
		if (status && ARCHIVABLE_STATUS.has(status.toLowerCase())) found.push(rel);
	}
	return found.sort();
}

function findUngroupedClusters(root: string): TopicCluster[] {
	// Only files DIRECTLY in active/ root — subfoldered = already grouped.
	let entries: Dirent[];
	try {
		entries = readdirSync(join(root, ACTIVE_REL), { withFileTypes: true });
	} catch {
		return [];
	}
	const rootFiles = entries
		.filter((e) => e.isFile() && isMarkdownFilename(e.name))
		.map((e) => e.name);

	// Don't nag about grouping when the root is already small.
	if (rootFiles.length < 4) return [];

	const byToken = new Map<string, Set<string>>();
	for (const f of rootFiles) {
		for (const t of new Set(titleTokens(f))) {
			(byToken.get(t) ?? byToken.set(t, new Set()).get(t)!).add(f);
		}
	}

	// Groupable topic = token in >=2 root files but no more than half of them
	// (the DF guard that rejects team/element words).
	const dfCap = Math.floor(rootFiles.length / 2);
	const clusters: TopicCluster[] = [];
	const seen = new Set<string>();
	for (const [token, set] of byToken) {
		if (set.size < 2 || set.size > dfCap) continue;
		const files = [...set].sort();
		const sig = files.join("|"); // dedup tokens with identical file sets
		if (seen.has(sig)) continue;
		seen.add(sig);
		clusters.push({ token, files });
	}
	return clusters.sort(
		(a, b) => b.files.length - a.files.length || a.token.localeCompare(b.token),
	);
}

export function scanActiveHygiene(root: string): ActiveHygieneReport {
	return {
		completedInActive: findCompletedInActive(root),
		ungroupedClusters: findUngroupedClusters(root),
	};
}

/** Render the report as markdown lines. Returns [] when active/ is clean. */
export function formatActiveHygiene(report: ActiveHygieneReport): string[] {
	const { completedInActive, ungroupedClusters } = report;
	if (completedInActive.length === 0 && ungroupedClusters.length === 0) return [];
	const lines: string[] = [];
	if (completedInActive.length > 0) {
		lines.push(
			`⚠️  ${completedInActive.length} note(s) marked done but still in active/ — archive to archive/YYYY/ (try /om-project-archive):`,
		);
		for (const p of completedInActive) lines.push(`   - ${p}`);
	}
	if (ungroupedClusters.length > 0) {
		if (lines.length > 0) lines.push("");
		lines.push("⚠️  Loose active/ notes that look like one topic — consider a folder (active/<Topic>/):");
		for (const { token, files } of ungroupedClusters) {
			lines.push(`   - "${token}": ${files.join(", ")}`);
		}
	}
	return lines;
}

Wire-in — SessionStart (session-start.ts)

Import alongside the other lib imports, then replace the trailing ### Vault File Listing entry of the sections array with a conditional block:

import { scanActiveHygiene, formatActiveHygiene } from "./lib/active-hygiene.ts";

// ...after the `### Active Work` entry, close the array, then:
const hygieneLines = formatActiveHygiene(scanActiveHygiene("."));
if (hygieneLines.length > 0) {
	sections.push("", "### Vault Hygiene (active/ drift)", hygieneLines.join("\n"));
}
sections.push("", "### Vault File Listing", listMd().join("\n"));

Wire-in — Stop (stop-checklist.ts)

import { scanActiveHygiene, formatActiveHygiene } from "./lib/active-hygiene.ts";

// ...after `const lines = [...baseChecklist]` and the org-change block:
const hygieneLines = formatActiveHygiene(scanActiveHygiene(projectDir));
if (hygieneLines.length > 0) {
	lines.push("", "active/ hygiene:", ...hygieneLines);
}

Test approach (tests/active-hygiene.test.ts)

node:test + node:assert/strict, mkdtemp fixtures under tmpdir (same pattern as qmd-ignore.test.ts). 10 cases worth covering:

• status detection incl. recursion into subfolders; active/no-status not flagged; missing active/ returns empty (no throw)
• cluster: ≥2 root notes sharing a distinctive token → flagged
• no cluster on generic stopwords (report/sync)
• DF guard drops a token shared by >half the root notes
• subfoldered notes ignored + silent under 4 root files
• date-prefix stripped before tokenising
• renderer: [] when clean; both sections when populated

Note: the only thing to tune per vault is the stopword list — and even that's optional, since the document-frequency guard is what makes the cluster detector safe without vault-specific knowledge.