toga-ai 1.0.0

package/scripts/harness.js

@@ -0,0 +1,605 @@
+#!/usr/bin/env node
+
+/**
+ * toga-harness — harness utility CLI for the TOGA Technology Claude knowledge repo.
+ *
+ * Commands:
+ *   audit              Validate knowledge base, check completeness, output score 0-100
+ *   sync [path]        Sync skills into a project's .claude/skills/
+ *   status             Show knowledge base statistics and last git commit info
+ *   new-repo           Interactive wizard to onboard a new repo into registry.json
+ *
+ * Usage:
+ *   node scripts/harness.js <command> [args]
+ *   toga-harness <command> [args]           (via npm bin)
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execSync, spawnSync } = require('child_process');
+const readline = require('readline');
+
+const REPO_ROOT = path.resolve(__dirname, '..');
+const KNOWLEDGE_DIR = path.join(REPO_ROOT, 'knowledge');
+const REGISTRY_FILE = path.join(KNOWLEDGE_DIR, 'registry.json');
+const FRAMEWORKS = ['1.0', '2.0'];
+const DOC_TYPES = ['feature', 'client-feature', 'workflow', 'architecture', 'standard'];
+
+/* ------------------------------------------------------------------ */
+/* shared utilities                                                    */
+/* ------------------------------------------------------------------ */
+
+function loadRegistry() {
+    if (!fs.existsSync(REGISTRY_FILE)) return [];
+    try {
+        return JSON.parse(fs.readFileSync(REGISTRY_FILE, 'utf8'));
+    } catch (e) {
+        console.error('ERROR: registry.json is not valid JSON: ' + e.message);
+        return [];
+    }
+}
+
+function saveRegistry(registry) {
+    fs.writeFileSync(REGISTRY_FILE, JSON.stringify(registry, null, 2) + '\n');
+}
+
+function walkMd(dir) {
+    const results = [];
+    if (!fs.existsSync(dir)) return results;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) results.push(...walkMd(full));
+        else if (entry.isFile() && entry.name.endsWith('.md') && entry.name !== 'INDEX.md') {
+            results.push(full);
+        }
+    }
+    return results;
+}
+
+function parseFrontmatter(content) {
+    if (!content.startsWith('---')) return { data: {}, body: content };
+    const end = content.indexOf('\n---', 3);
+    if (end === -1) return { data: {}, body: content };
+    const raw = content.slice(3, end).replace(/^\n/, '');
+    const body = content.slice(end + 4).replace(/^\r?\n/, '');
+    const data = {};
+    const lines = raw.split(/\r?\n/);
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        if (!line.trim()) { i++; continue; }
+        const m = line.match(/^([A-Za-z0-9_]+):\s*(.*)$/);
+        if (!m) { i++; continue; }
+        const key = m[1];
+        let val = m[2].trim();
+        if (val === '') {
+            const arr = [];
+            let j = i + 1;
+            while (j < lines.length && /^\s*-\s+/.test(lines[j])) {
+                arr.push(lines[j].replace(/^\s*-\s+/, '').trim().replace(/^["']|["']$/g, ''));
+                j++;
+            }
+            data[key] = arr;
+            i = j;
+            continue;
+        }
+        if (val.startsWith('[') && val.endsWith(']')) {
+            const inner = val.slice(1, -1).trim();
+            data[key] = inner === '' ? [] : inner.split(',').map((s) => s.trim().replace(/^["']|["']$/g, ''));
+        } else {
+            data[key] = val.replace(/^["']|["']$/g, '');
+        }
+        i++;
+    }
+    return { data, body };
+}
+
+function allDocs() {
+    const dirs = FRAMEWORKS.map((fw) => path.join(KNOWLEDGE_DIR, fw))
+        .concat([path.join(KNOWLEDGE_DIR, 'clients')]);
+    return dirs.flatMap(walkMd).map((file) => {
+        const content = fs.readFileSync(file, 'utf8');
+        const { data, body } = parseFrontmatter(content);
+        const rel = path.relative(KNOWLEDGE_DIR, file).split(path.sep).join('/');
+        return { file, rel, data, body };
+    });
+}
+
+function gitLastCommitDate(targetPath) {
+    try {
+        const result = spawnSync('git', [
+            '-C', REPO_ROOT, 'log', '-1', '--format=%ci', '--', targetPath
+        ], { encoding: 'utf8' });
+        if (result.status === 0 && result.stdout.trim()) {
+            return result.stdout.trim().split(' ')[0]; // YYYY-MM-DD
+        }
+        return null;
+    } catch (e) {
+        return null;
+    }
+}
+
+function runValidate() {
+    const result = spawnSync('node', [path.join(REPO_ROOT, 'knowledge.js'), 'validate'], {
+        encoding: 'utf8',
+        cwd: REPO_ROOT
+    });
+    return {
+        stdout: result.stdout || '',
+        stderr: result.stderr || '',
+        exitCode: result.status || 0
+    };
+}
+
+/* ------------------------------------------------------------------ */
+/* command: audit                                                      */
+/* ------------------------------------------------------------------ */
+
+function cmdAudit() {
+    console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+    console.log('toga-harness audit');
+    console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+    console.log('');
+
+    const checks = [];   // { label, pass, detail }
+    const warnings = []; // { label, detail }
+
+    // --- CHECK 1: validate ---
+    process.stdout.write('Running knowledge.js validate... ');
+    const validateResult = runValidate();
+    const validatePassed = validateResult.exitCode === 0 &&
+        !validateResult.stdout.includes('FAILED') &&
+        !validateResult.stderr.includes('ERROR');
+    const validateErrors = (validateResult.stdout + validateResult.stderr)
+        .split('\n')
+        .filter((l) => l.includes('ERROR'))
+        .length;
+
+    console.log(validatePassed ? '✓ PASS' : '✗ FAIL (' + validateErrors + ' errors)');
+    if (!validatePassed) {
+        const errorLines = (validateResult.stdout + validateResult.stderr)
+            .split('\n')
+            .filter((l) => l.trim())
+            .slice(0, 10)
+            .map((l) => '    ' + l)
+            .join('\n');
+        console.log(errorLines);
+    }
+    checks.push({
+        label: 'validate: knowledge base integrity',
+        pass: validatePassed,
+        detail: validatePassed ? 'No errors' : validateErrors + ' error(s) found'
+    });
+
+    // --- CHECK 2: registry has entries ---
+    const registry = loadRegistry();
+    const registryOk = registry.length > 0;
+    checks.push({
+        label: 'registry.json: has entries',
+        pass: registryOk,
+        detail: registry.length + ' repo(s) registered'
+    });
+
+    // --- CHECK 3: each registered repo has architecture.md ---
+    const missingArch = [];
+    for (const entry of registry) {
+        const archPath = path.join(KNOWLEDGE_DIR, entry.framework, 'apps', entry.repo, 'architecture.md');
+        if (!fs.existsSync(archPath)) {
+            missingArch.push(entry.framework + '/apps/' + entry.repo + '/architecture.md');
+        }
+    }
+    const archOk = missingArch.length === 0;
+    checks.push({
+        label: 'all registered repos have architecture.md',
+        pass: archOk,
+        detail: archOk ? 'All repos covered' : 'Missing: ' + missingArch.join(', ')
+    });
+
+    // --- CHECK 4: INDEX.md files are not hand-edited ---
+    const handEditedIndexFiles = [];
+    for (const fw of FRAMEWORKS) {
+        const appsDir = path.join(KNOWLEDGE_DIR, fw, 'apps');
+        if (!fs.existsSync(appsDir)) continue;
+        for (const repo of fs.readdirSync(appsDir, { withFileTypes: true })
+            .filter((e) => e.isDirectory()).map((e) => e.name)) {
+            const indexPath = path.join(appsDir, repo, 'INDEX.md');
+            if (!fs.existsSync(indexPath)) continue;
+            const content = fs.readFileSync(indexPath, 'utf8');
+            // INDEX.md files generated by knowledge.js start with "# <repo>" and have no "Auto-generated" note
+            // We detect hand-edits if content doesn't start with the expected heading pattern
+            // and doesn't have the table structure we produce
+            if (!content.includes('| Doc |') && content.trim().length > 50) {
+                handEditedIndexFiles.push(fw + '/apps/' + repo + '/INDEX.md');
+            }
+        }
+    }
+    // Also check master INDEX.md
+    const masterIndex = path.join(KNOWLEDGE_DIR, 'INDEX.md');
+    if (fs.existsSync(masterIndex)) {
+        const masterContent = fs.readFileSync(masterIndex, 'utf8');
+        if (!masterContent.includes('Auto-generated')) {
+            warnings.push({
+                label: 'knowledge/INDEX.md may be hand-edited',
+                detail: 'Expected "Auto-generated" notice not found'
+            });
+        }
+    }
+    const indexOk = handEditedIndexFiles.length === 0;
+    checks.push({
+        label: 'INDEX.md files appear auto-generated (not hand-edited)',
+        pass: indexOk,
+        detail: indexOk ? 'All INDEX.md files look correct' : 'Possibly hand-edited: ' + handEditedIndexFiles.join(', ')
+    });
+
+    // --- CHECK 5: clients/ directory exists ---
+    const clientsDir = path.join(KNOWLEDGE_DIR, 'clients');
+    const clientsOk = fs.existsSync(clientsDir);
+    checks.push({
+        label: 'clients/ directory exists',
+        pass: clientsOk,
+        detail: clientsOk ? 'clients/ found' : 'clients/ missing — client knowledge not started'
+    });
+
+    // --- CHECK 6: 1.0/standards/ has at least one file ---
+    const standards10Dir = path.join(KNOWLEDGE_DIR, '1.0', 'standards');
+    const standards10Files = fs.existsSync(standards10Dir)
+        ? fs.readdirSync(standards10Dir).filter((f) => f.endsWith('.md'))
+        : [];
+    const standards10Ok = standards10Files.length > 0;
+    checks.push({
+        label: '1.0/standards/ has at least one standard',
+        pass: standards10Ok,
+        detail: standards10Ok
+            ? standards10Files.length + ' standard(s): ' + standards10Files.join(', ')
+            : '1.0/standards/ is empty or missing'
+    });
+
+    // --- CHECK 7: 2.0/standards/ has at least one file ---
+    const standards20Dir = path.join(KNOWLEDGE_DIR, '2.0', 'standards');
+    const standards20Files = fs.existsSync(standards20Dir)
+        ? fs.readdirSync(standards20Dir).filter((f) => f.endsWith('.md'))
+        : [];
+    const standards20Ok = standards20Files.length > 0;
+    checks.push({
+        label: '2.0/standards/ has at least one standard',
+        pass: standards20Ok,
+        detail: standards20Ok
+            ? standards20Files.length + ' standard(s): ' + standards20Files.join(', ')
+            : '2.0/standards/ is empty or missing'
+    });
+
+    // --- CHECK 8: all docs have required frontmatter ---
+    const docs = allDocs();
+    const missingFrontmatter = [];
+    for (const doc of docs) {
+        const required = ['title', 'framework', 'type', 'status'];
+        const missing = required.filter((f) => !doc.data[f]);
+        if (missing.length > 0) {
+            missingFrontmatter.push(doc.rel + ' (missing: ' + missing.join(', ') + ')');
+        }
+    }
+    const frontmatterOk = missingFrontmatter.length === 0;
+    checks.push({
+        label: 'all docs have required frontmatter',
+        pass: frontmatterOk,
+        detail: frontmatterOk
+            ? docs.length + ' docs checked'
+            : missingFrontmatter.slice(0, 3).join('; ') + (missingFrontmatter.length > 3 ? ' ...' : '')
+    });
+
+    // --- Scoring ---
+    console.log('');
+    console.log('Check results:');
+    const passed = checks.filter((c) => c.pass).length;
+    const total = checks.length;
+    for (const c of checks) {
+        const icon = c.pass ? '  ✓' : '  ✗';
+        console.log(icon + ' [' + (c.pass ? 'PASS' : 'FAIL') + '] ' + c.label);
+        if (!c.pass && c.detail) console.log('       → ' + c.detail);
+    }
+
+    if (warnings.length > 0) {
+        console.log('');
+        console.log('Warnings:');
+        for (const w of warnings) {
+            console.log('  ⚠ ' + w.label);
+            if (w.detail) console.log('    → ' + w.detail);
+        }
+    }
+
+    const score = Math.round((passed / total) * 100);
+    console.log('');
+    console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+    console.log('Score: ' + score + '/100  (' + passed + '/' + total + ' checks passed)');
+    console.log('');
+
+    // Top 3 action items
+    const failing = checks.filter((c) => !c.pass);
+    if (failing.length > 0) {
+        console.log('Top action items:');
+        const top3 = failing.slice(0, 3);
+        top3.forEach((c, i) => {
+            console.log('  ' + (i + 1) + '. Fix: ' + c.label);
+            if (c.detail) console.log('     ' + c.detail);
+        });
+    } else {
+        console.log('✓ Knowledge base is healthy. No action items.');
+    }
+    console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+
+    process.exitCode = score < 60 ? 1 : 0;
+}
+
+/* ------------------------------------------------------------------ */
+/* command: sync                                                       */
+/* ------------------------------------------------------------------ */
+
+function cmdSync(args) {
+    const projectPath = args[0] || null;
+    const syncScript = path.join(REPO_ROOT, 'sync-skills.js');
+    if (!fs.existsSync(syncScript)) {
+        console.error('ERROR: sync-skills.js not found at ' + syncScript);
+        process.exit(1);
+    }
+    const spawnArgs = [syncScript];
+    if (projectPath) spawnArgs.push(projectPath);
+    const result = spawnSync('node', spawnArgs, {
+        cwd: process.cwd(),
+        stdio: 'inherit',
+        encoding: 'utf8'
+    });
+    process.exitCode = result.status || 0;
+}
+
+/* ------------------------------------------------------------------ */
+/* command: status                                                     */
+/* ------------------------------------------------------------------ */
+
+function cmdStatus() {
+    const registry = loadRegistry();
+    const docs = allDocs();
+
+    console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+    console.log('toga-harness status — Knowledge Base Overview');
+    console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+    console.log('');
+
+    // Registered repos
+    console.log('Registered repos: ' + registry.length);
+    for (const e of registry) {
+        const docCount = docs.filter((d) => d.data.repo === e.repo && d.data.framework === e.framework).length;
+        const role = e.role === 'core' ? ' [core]' : '';
+        console.log('  ' + e.framework + '/' + e.repo + ' (' + e.project + ')' + role + ' — ' + docCount + ' doc(s)');
+    }
+    console.log('');
+
+    // Docs per framework
+    for (const fw of FRAMEWORKS) {
+        const fwDocs = docs.filter((d) => d.data.framework === fw);
+        const byType = {};
+        for (const d of fwDocs) {
+            const t = d.data.type || 'unknown';
+            byType[t] = (byType[t] || 0) + 1;
+        }
+        const typeStr = Object.entries(byType).map(([k, v]) => v + ' ' + k).join(', ') || 'none';
+        console.log('Framework ' + fw + ': ' + fwDocs.length + ' doc(s) (' + typeStr + ')');
+    }
+    console.log('');
+
+    // Docs per client
+    const clientsDir = path.join(KNOWLEDGE_DIR, 'clients');
+    if (fs.existsSync(clientsDir)) {
+        const clients = fs.readdirSync(clientsDir, { withFileTypes: true })
+            .filter((e) => e.isDirectory())
+            .map((e) => e.name);
+        if (clients.length === 0) {
+            console.log('Clients: none (clients/ exists but is empty)');
+        } else {
+            console.log('Clients: ' + clients.length);
+            for (const client of clients) {
+                const clientDir = path.join(clientsDir, client);
+                const clientDocs = walkMd(clientDir);
+                console.log('  ' + client + ': ' + clientDocs.length + ' doc(s)');
+            }
+        }
+    } else {
+        console.log('Clients: clients/ directory not found');
+    }
+    console.log('');
+
+    // Total doc count
+    console.log('Total knowledge docs: ' + docs.length);
+    console.log('');
+
+    // Last git commit date on knowledge/ files
+    const lastCommit = gitLastCommitDate(KNOWLEDGE_DIR);
+    if (lastCommit) {
+        console.log('Last knowledge/ commit: ' + lastCommit);
+    } else {
+        console.log('Last knowledge/ commit: (git unavailable or no commits yet)');
+    }
+
+    // Skills count
+    const skillsDir = path.join(REPO_ROOT, 'skills');
+    if (fs.existsSync(skillsDir)) {
+        const skillNames = fs.readdirSync(skillsDir, { withFileTypes: true })
+            .filter((e) => e.isDirectory())
+            .map((e) => e.name);
+        console.log('Skills available: ' + skillNames.length + ' (' + skillNames.join(', ') + ')');
+    }
+
+    console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+}
+
+/* ------------------------------------------------------------------ */
+/* command: new-repo (interactive wizard)                              */
+/* ------------------------------------------------------------------ */
+
+function prompt(rl, question) {
+    return new Promise((resolve) => rl.question(question, resolve));
+}
+
+async function cmdNewRepo() {
+    const registry = loadRegistry();
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+
+    console.log('');
+    console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+    console.log('New Repo Onboarding Wizard');
+    console.log('This will add a new entry to knowledge/registry.json');
+    console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+    console.log('');
+
+    let repo = '';
+    while (!repo) {
+        repo = (await prompt(rl, '1. Repo name (exact on-disk folder/repo name, e.g. worker2): ')).trim();
+        if (!repo) console.log('   Repo name is required.');
+        else if (registry.find((r) => r.repo === repo)) {
+            console.log('   WARNING: "' + repo + '" is already in registry.json.');
+            const confirm = await prompt(rl, '   Overwrite? (y/N): ');
+            if (confirm.trim().toLowerCase() !== 'y') {
+                repo = '';
+                console.log('   OK, enter a different name.');
+            }
+        }
+    }
+
+    let framework = '';
+    while (!['1.0', '2.0'].includes(framework)) {
+        framework = (await prompt(rl, '2. Framework (1.0 or 2.0): ')).trim();
+        if (!['1.0', '2.0'].includes(framework)) {
+            console.log('   Must be exactly "1.0" or "2.0".');
+        }
+    }
+
+    let project = '';
+    while (!project) {
+        project = (await prompt(rl, '3. Project name (human-readable, e.g. "Worker"): ')).trim();
+        if (!project) console.log('   Project name is required.');
+    }
+
+    let role = '';
+    while (!['core', 'app'].includes(role)) {
+        role = (await prompt(rl, '4. Role ("core" for the framework base, "app" for everything else): ')).trim().toLowerCase();
+        if (!['core', 'app'].includes(role)) {
+            console.log('   Must be "core" or "app".');
+        }
+    }
+
+    const existingRepos = registry.map((r) => r.repo).filter((r) => r !== repo);
+    let dependsOn = [];
+    if (existingRepos.length > 0) {
+        console.log('   Known repos: ' + existingRepos.join(', '));
+        const depsInput = (await prompt(rl, '5. dependsOn (comma-separated repos beyond framework core, or leave blank): ')).trim();
+        if (depsInput) {
+            dependsOn = depsInput.split(',').map((s) => s.trim()).filter(Boolean);
+            const unknown = dependsOn.filter((d) => !existingRepos.includes(d));
+            if (unknown.length > 0) {
+                console.log('   WARNING: unknown repo(s) in dependsOn: ' + unknown.join(', '));
+                console.log('   These will be added anyway — register them separately if needed.');
+            }
+        }
+    } else {
+        console.log('5. dependsOn: no other repos registered yet, skipping.');
+    }
+
+    const localPath = (await prompt(rl, '6. Local path on this machine (e.g. C:\\WWW\\2.0\\worker2 or /home/user/projects/worker2): ')).trim();
+
+    rl.close();
+
+    // Build the new entry
+    const newEntry = { repo, project, framework, role, dependsOn };
+
+    // Confirm
+    console.log('');
+    console.log('New registry entry:');
+    console.log(JSON.stringify(newEntry, null, 2));
+    if (localPath) {
+        console.log('');
+        console.log('Local path (for Claude memory only — NOT committed): ' + localPath);
+        console.log('Add to Claude memory as: repo-path-' + repo + ' = ' + localPath);
+    }
+    console.log('');
+
+    // Use a synchronous readline for the final confirm since we closed async rl
+    const rl2 = readline.createInterface({ input: process.stdin, output: process.stdout });
+    await new Promise((resolve) => {
+        rl2.question('Append to registry.json? (Y/n): ', (answer) => {
+            rl2.close();
+            if (answer.trim().toLowerCase() === 'n') {
+                console.log('Aborted — registry not changed.');
+                resolve();
+                return;
+            }
+
+            // Remove existing entry for this repo if present
+            const filtered = registry.filter((r) => r.repo !== repo);
+            filtered.push(newEntry);
+            saveRegistry(filtered);
+            console.log('');
+            console.log('✓ registry.json updated with "' + repo + '"');
+
+            // Run validate
+            console.log('Running validate...');
+            const result = spawnSync('node', [path.join(REPO_ROOT, 'knowledge.js'), 'validate'], {
+                encoding: 'utf8',
+                cwd: REPO_ROOT,
+                stdio: 'inherit'
+            });
+            if (result.status !== 0) {
+                console.error('');
+                console.error('ERROR: validate failed after adding the repo.');
+                console.error('Please fix the errors before continuing.');
+                process.exitCode = 1;
+            } else {
+                console.log('');
+                console.log('Next steps:');
+                console.log('  1. Save Claude memory: repo-path-' + repo + ' = ' + (localPath || '<local path>'));
+                console.log('  2. Create knowledge/' + framework + '/apps/' + repo + '/architecture.md when you start work');
+                console.log('  3. Run /capture after your first session to populate features/');
+            }
+            resolve();
+        });
+    });
+}
+
+/* ------------------------------------------------------------------ */
+/* dispatch                                                            */
+/* ------------------------------------------------------------------ */
+
+async function main() {
+    const [, , cmd, ...rest] = process.argv;
+
+    switch (cmd) {
+        case 'audit':
+            cmdAudit();
+            break;
+        case 'sync':
+            cmdSync(rest);
+            break;
+        case 'status':
+            cmdStatus();
+            break;
+        case 'new-repo':
+            await cmdNewRepo();
+            break;
+        default:
+            console.log('toga-harness — TOGA Technology Claude harness utilities');
+            console.log('');
+            console.log('Usage: node scripts/harness.js <command>');
+            console.log('');
+            console.log('Commands:');
+            console.log('  audit              Validate + completeness check, score 0-100');
+            console.log('  sync [path]        Sync skills into a project .claude/skills/');
+            console.log('  status             Show knowledge base statistics');
+            console.log('  new-repo           Interactive wizard to onboard a new repo');
+            process.exitCode = 1;
+    }
+}
+
+main().catch((err) => {
+    console.error('Unexpected error: ' + err.message);
+    process.exit(1);
+});

package/scripts/hooks/evaluate-session.js

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const COUNTER_FILE = path.join(os.tmpdir(), 'toga-session-counter.json');
+const PATTERN_INTERVAL = 25;
+
+function loadCounter() {
+    try {
+        if (fs.existsSync(COUNTER_FILE)) {
+            return JSON.parse(fs.readFileSync(COUNTER_FILE, 'utf8'));
+        }
+    } catch (e) {
+        // Corrupt counter file — start fresh
+    }
+    return {};
+}
+
+function saveCounter(data) {
+    try {
+        fs.writeFileSync(COUNTER_FILE, JSON.stringify(data, null, 2));
+    } catch (e) {
+        // Non-fatal — counter persistence is best-effort
+    }
+}
+
+function main() {
+    const pid = String(process.ppid || process.pid);
+    const counters = loadCounter();
+
+    if (!counters[pid]) {
+        counters[pid] = 0;
+    }
+
+    counters[pid] += 1;
+    const count = counters[pid];
+
+    saveCounter(counters);
+
+    // Output reminder on every 25th call for this session PID
+    if (count % PATTERN_INTERVAL === 0) {
+        console.log('');
+        console.log('Pattern opportunity: This session (' + count + ' responses) may contain');
+        console.log('extractable patterns worth capturing. Run /learn to distill them into');
+        console.log('the knowledge base, or /capture to save session learnings.');
+        console.log('');
+    }
+
+    process.exit(0);
+}
+
+main();