@lastboy/pai 0.3.0 → 0.4.0

package/README.md

@@ -83,9 +83,19 @@ Exports the same rules `pai rules` shows — from `CLAUDE.md` and
 `CLAUDE.local.md` is per-machine and is not exported.
 
 ```json
-{ "version": 2, "rules": [ { "rule": "…", "category": "…", "scope": "global" } ] }
+{
+  "version": 2,
+  "pai": "0.3.1",
+  "exportedAt": "2026-08-29T12:00:00.000Z",
+  "rules": [ { "rule": "…", "category": "…", "scope": "global" } ]
+}
 ```
 
+`version` is the export format (for compatibility checks), `pai` is the PAI
+version that produced the file, and `exportedAt` is when it was written;
+files from a newer format than this `pai` supports are rejected with an
+upgrade hint.
+
 | Option | Effect |
 |---|---|
 | `--out <file>` | write to a file instead of stdout |
@@ -118,13 +128,19 @@ Hand-written `CLAUDE.md` rules are never used for deduplication — only
 | Option | Effect |
 |---|---|
 | `--dry-run` | report what would change ("would add …") without writing |
+| `--validate` | check the file only — parse, migrate, validate — and print a summary; writes nothing |
 
 ```bash
 pai import mine.json --dry-run
 pai import mine.json
+pai import mine.json --validate
 ```
 
 Invalid or unsupported files fail with a clear message and a non-zero exit code.
+Files from an older export format are migrated automatically; files from a
+newer format than this `pai` supports are rejected with an upgrade hint. See
+[the export format contract](docs/export-format.md) for the full JSON shape,
+field constraints, and migration/compatibility rules.
 
 **Cross-platform.** A file exported on macOS or Linux imports on Windows and
 back. Exports contain no filesystem paths, so nothing is machine-specific, and
@@ -211,6 +227,17 @@ repository.
 Working today: `status`, `review`, `rules`, `export`, `import`, and the two
 experiments.
 
-Next: `pai learn` — scan sessions, distill candidate rules, approve or reject
-them interactively, and store the approved ones. Then auditing sessions against
-stored rules (which rules the agent actually violated, with evidence).
+Next: see [Roadmap](#roadmap).
+
+## Roadmap
+
+- **`pai learn`** — scan sessions, distill candidate rules with a local model, approve/reject/edit interactively, write approved rules to `CLAUDE.pai.md`.
+- **Compliance audit** — check sessions against your rules and report violations with evidence (which rule, how often, your own words) — the "is the agent following my guidance" measure.
+- **Trends** — violations over time, before/after a rule was added, and comparison across models/configurations.
+- **Cross-project promotion** — rules that keep appearing in several projects get proposed as global rules.
+- **Better session review** — active time instead of wall-clock duration, filtering out headless/automation sessions.
+- **Long-list UX** — category summaries with counts, `--category`, an interactive picker.
+- **More agents** — Codex CLI adapter (`AGENTS.md`); the core stays agent-independent.
+- **Optional integrations, only if needed** — Claude Code hooks for real-time capture; MCP so the agent can ask PAI about rules.
+
+Order is not a commitment; each item ships as its own small, tested step.

package/dist/cli/program.js

@@ -15,6 +15,7 @@ import { buildDistillPrompt, parseDistillResponse } from '../experiments/rule-di
 import { findExportableGuidelineFiles, findGuidelineFiles, guidelineDir, managedImportTarget, } from '../adapters/claude/guidelines.js';
 import { filterGuidelineGroups } from '../core/guidelines.js';
 import { parseExportDocument, serializeExportDocument, toExportRules, } from '../core/managed-guidelines.js';
+import { CURRENT_EXPORT_FORMAT } from '../core/export-migrations.js';
 import { importManagedGuidelines, readGuidelineGroups, } from '../persistence/managed-guideline-files.js';
 import { decodeTextFile } from '../persistence/text-file.js';
 import { parseSelection, renderGuidelines, renderReview, renderSessionList } from './render.js';
@@ -53,8 +54,25 @@ async function chooseSession(out) {
 function describeError(error) {
     return error instanceof Error ? error.message : String(error);
 }
+/**
+ * Best-effort read of the file's own `pai`/`exportedAt` fields for the
+ * `--validate` summary. Only called after `parseExportDocument` has already
+ * succeeded on the same text, so this re-parse cannot fail in practice.
+ */
+function readExportMeta(text) {
+    try {
+        const parsed = JSON.parse(text.replace(/^/, ''));
+        return {
+            ...(typeof parsed['pai'] === 'string' ? { pai: parsed['pai'] } : {}),
+            ...(typeof parsed['exportedAt'] === 'string' ? { exportedAt: parsed['exportedAt'] } : {}),
+        };
+    }
+    catch {
+        return {};
+    }
+}
 // Same relative depth from src/cli and dist/cli.
-function packageVersion() {
+export function packageVersion() {
     const pkg = JSON.parse(readFileSync(join(import.meta.dirname, '..', '..', 'package.json'), 'utf8'));
     return pkg.version ?? '0.0.0';
 }
@@ -122,7 +140,10 @@ export function createProgram(out) {
             // Global files come first, so the output order is global → project.
             const files = findExportableGuidelineFiles(process.cwd()).filter((file) => options.scope === undefined || file.scope === options.scope);
             const rules = toExportRules(readGuidelineGroups(files));
-            const json = serializeExportDocument(rules);
+            const json = serializeExportDocument(rules, {
+                pai: packageVersion(),
+                exportedAt: new Date().toISOString(),
+            });
             if (options.out === undefined) {
                 out(json.trimEnd());
                 return;
@@ -140,17 +161,41 @@ export function createProgram(out) {
         .argument('<file>', 'JSON file previously produced by "pai export"')
         .description('Merge rules from a file into CLAUDE.pai.md on this machine (never overwrites)')
         .option('--dry-run', 'show what would change without writing')
+        .option('--validate', 'check the file only; print a summary and exit without writing')
         .action(async (file, options) => {
+        const text = decodeTextFile(await readFile(file));
         let incoming;
         try {
-            incoming = parseExportDocument(decodeTextFile(await readFile(file)));
+            incoming = parseExportDocument(text, { currentPaiVersion: packageVersion() });
         }
         catch (error) {
-            out(`Could not read ${file}: ${describeError(error)}`);
+            if (options.validate) {
+                for (const line of describeError(error).split('\n'))
+                    out(line);
+            }
+            else {
+                out(`Could not read ${file}: ${describeError(error)}`);
+            }
             process.exitCode = 1;
             return;
         }
+        if (options.validate) {
+            const meta = readExportMeta(text);
+            const paiPart = meta.pai !== undefined ? `pai ${meta.pai}` : 'pai unknown';
+            const exportedPart = meta.exportedAt !== undefined ? `, exported ${meta.exportedAt}` : '';
+            out(`Valid PAI export (format ${CURRENT_EXPORT_FORMAT}, ${paiPart}${exportedPart})`);
+            const global = incoming.rules.filter((rule) => rule.scope === 'global').length;
+            const project = incoming.rules.filter((rule) => rule.scope === 'project').length;
+            out(`Rules: ${incoming.rules.length} (global ${global}, project ${project})`);
+            if (incoming.migratedFrom !== undefined) {
+                out(`Migrated from format ${incoming.migratedFrom} (would be imported as format ${CURRENT_EXPORT_FORMAT})`);
+            }
+            return;
+        }
         try {
+            if (incoming.migratedFrom !== undefined) {
+                out(`Migrated from format ${incoming.migratedFrom}.`);
+            }
             for (const scope of ['global', 'project']) {
                 const rules = incoming.rules.filter((rule) => rule.scope === scope);
                 if (rules.length === 0)

package/dist/core/export-migrations.js

@@ -0,0 +1,41 @@
+// Migration chain that brings an older PAI export up to the current format.
+// Pure: no I/O, no filesystem, no process access.
+import { parseRuleStore } from './rule-store.js';
+export const CURRENT_EXPORT_FORMAT = 2;
+/** Older `.pai/rules.json` stores carry the same three fields an export needs. */
+function v1ToV2(doc) {
+    const store = parseRuleStore(JSON.stringify(doc));
+    return {
+        version: 2,
+        rules: store.rules.map((r) => ({ rule: r.rule, category: r.category, scope: r.scope })),
+    };
+}
+// Adding a future migration is one new entry here: key N migrates format N to N+1.
+const MIGRATIONS = {
+    1: v1ToV2,
+};
+export function migrateExport(raw, options) {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new Error('Invalid PAI export: file is not a JSON object');
+    }
+    const record = raw;
+    const version = record['version'];
+    if (typeof version !== 'number' || !Number.isInteger(version) || version < 1) {
+        throw new Error('Invalid PAI export: "version" must be a positive integer');
+    }
+    if (version > CURRENT_EXPORT_FORMAT) {
+        const producer = typeof record['pai'] === 'string' && record['pai'].trim() !== '' ? record['pai'] : 'unknown';
+        throw new Error(`Invalid PAI export: format ${version} was produced by pai ${producer}; this pai (${options.currentPaiVersion}) supports up to format ${CURRENT_EXPORT_FORMAT} — upgrade pai`);
+    }
+    let document = record;
+    let from = version;
+    while (from < CURRENT_EXPORT_FORMAT) {
+        const migrate = MIGRATIONS[from];
+        if (!migrate) {
+            throw new Error(`Invalid PAI export: no migration path from format ${from}`);
+        }
+        document = migrate(document);
+        from += 1;
+    }
+    return { document, ...(version !== CURRENT_EXPORT_FORMAT ? { migratedFrom: version } : {}) };
+}

package/dist/core/managed-guidelines.js

@@ -2,8 +2,8 @@
 // guidance files are never edited; PAI owns one sibling file per scope and
 // merges into it. Everything here is pure — paths and I/O live elsewhere.
 import { HEADING, parseGuidelines } from './guidelines.js';
-import { parseRuleStore, ruleId } from './rule-store.js';
-const EXPORT_VERSION = 2;
+import { ruleId } from './rule-store.js';
+import { CURRENT_EXPORT_FORMAT, migrateExport } from './export-migrations.js';
 export const MANAGED_HEADER = '<!-- Managed by PAI. Hand-written rules belong in CLAUDE.md; PAI adds rules here via `pai import` / `pai learn`. -->';
 function toLf(text) {
     return text.replace(/\r\n?/g, '\n');
@@ -12,70 +12,117 @@ function toLf(text) {
 export function toExportRules(groups) {
     return groups.flatMap((group) => group.guidelines.map((g) => ({ rule: g.text, category: g.category, scope: group.scope })));
 }
-export function serializeExportDocument(rules) {
-    const document = { version: EXPORT_VERSION, rules };
+export function serializeExportDocument(rules, meta) {
+    const document = {
+        version: CURRENT_EXPORT_FORMAT,
+        pai: meta.pai,
+        exportedAt: meta.exportedAt,
+        rules,
+    };
     return `${JSON.stringify(document, null, 2)}\n`;
 }
-export function parseExportDocument(json) {
-    let parsed;
-    try {
-        // Tolerate a byte-order mark left by Windows editors.
-        parsed = JSON.parse(json.replace(/^/, ''));
-    }
-    catch {
-        return failParse('file is not valid JSON');
-    }
-    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
-        return failParse('file is not a JSON object');
+const MAX_RULE_LENGTH = 500;
+const MAX_CATEGORY_LENGTH = 80;
+const MAX_PROBLEMS_SHOWN = 20;
+/**
+ * Strict validation of a format-2 document (after migration). Collects every
+ * problem instead of stopping at the first one; each message is prefixed
+ * with a JSON-path so multiple problems in one file can be fixed at once.
+ * Unknown extra fields, top-level or per-rule, are ignored for forward
+ * compatibility.
+ */
+export function validateExportDocument(doc) {
+    const problems = [];
+    if (doc['version'] !== CURRENT_EXPORT_FORMAT) {
+        problems.push(`version: expected ${CURRENT_EXPORT_FORMAT}`);
     }
-    const raw = parsed;
-    if (raw['version'] === 1) {
-        // Older `.pai/rules.json` stores carry the same three fields we need.
-        return {
-            version: EXPORT_VERSION,
-            rules: parseRuleStore(json).rules.map((r) => ({
-                rule: r.rule,
-                category: r.category,
-                scope: r.scope,
-            })),
-        };
+    if (doc['pai'] !== undefined && typeof doc['pai'] !== 'string') {
+        problems.push('pai: expected string');
     }
-    if (raw['version'] !== EXPORT_VERSION) {
-        return failParse(`unsupported version: ${String(raw['version'])} (expected ${EXPORT_VERSION})`);
+    if (doc['exportedAt'] !== undefined) {
+        const exportedAt = doc['exportedAt'];
+        if (typeof exportedAt !== 'string' || Number.isNaN(Date.parse(exportedAt))) {
+            problems.push('exportedAt: expected ISO-8601 timestamp');
+        }
     }
-    if (!Array.isArray(raw['rules'])) {
-        return failParse('"rules" must be an array');
+    const rawRules = doc['rules'];
+    if (!Array.isArray(rawRules)) {
+        problems.push('rules: expected array');
+        return { ok: false, problems };
     }
     const rules = [];
-    for (const [index, entry] of raw['rules'].entries()) {
+    rawRules.forEach((entry, index) => {
+        const path = `rules[${index}]`;
         if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) {
-            return failParse(`rule ${index + 1} is not an object`);
+            problems.push(`${path}: expected object`);
+            return;
         }
         const record = entry;
-        const text = record['rule'];
-        if (typeof text !== 'string' || text.trim() === '') {
-            return failParse(`rule ${index + 1} is missing a non-empty "rule" field`);
+        const rawText = record['rule'];
+        // A bullet is one line; line breaks inside a rule would split it.
+        const normalizedText = typeof rawText === 'string' ? toLf(rawText).replace(/\n/g, ' ').trim() : undefined;
+        const ruleValid = normalizedText !== undefined && normalizedText !== '' && normalizedText.length <= MAX_RULE_LENGTH;
+        if (!ruleValid) {
+            problems.push(`${path}.rule: expected non-empty string (max ${MAX_RULE_LENGTH} chars)`);
         }
-        const category = record['category'];
-        if (category !== undefined && typeof category !== 'string') {
-            return failParse(`rule ${index + 1} has a non-string "category"`);
+        let category = 'General';
+        let categoryValid = true;
+        const rawCategory = record['category'];
+        if (rawCategory !== undefined) {
+            if (typeof rawCategory !== 'string' || rawCategory.trim().length > MAX_CATEGORY_LENGTH) {
+                categoryValid = false;
+                problems.push(`${path}.category: expected string (max ${MAX_CATEGORY_LENGTH} chars)`);
+            }
+            else {
+                category = rawCategory.trim() === '' ? 'General' : rawCategory.trim();
+            }
         }
         const scope = record['scope'];
-        if (scope !== 'global' && scope !== 'project') {
-            return failParse(`rule ${index + 1} has an invalid "scope" (expected "global" or "project")`);
+        const scopeValid = scope === 'global' || scope === 'project';
+        if (!scopeValid) {
+            problems.push(`${path}.scope: expected "global" or "project"`);
         }
-        rules.push({
-            // A bullet is one line; line breaks inside a rule would split it.
-            rule: toLf(text).replace(/\n/g, ' ').trim(),
-            category: category === undefined || category.trim() === '' ? 'General' : category.trim(),
-            scope,
-        });
+        if (ruleValid && categoryValid && scopeValid) {
+            rules.push({ rule: normalizedText, category, scope: scope });
+        }
+    });
+    if (problems.length > 0)
+        return { ok: false, problems };
+    return { ok: true, document: { version: CURRENT_EXPORT_FORMAT, rules } };
+}
+export function parseExportDocument(json, options) {
+    let parsed;
+    try {
+        // Tolerate a byte-order mark left by Windows editors.
+        parsed = JSON.parse(json.replace(/^/, ''));
     }
-    return { version: EXPORT_VERSION, rules };
+    catch {
+        return failParse('file is not valid JSON');
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return failParse('file is not a JSON object');
+    }
+    const { document, migratedFrom } = migrateExport(parsed, {
+        currentPaiVersion: options.currentPaiVersion,
+    });
+    const result = validateExportDocument(document);
+    if (!result.ok)
+        failValidation(result.problems);
+    return { ...result.document, ...(migratedFrom !== undefined ? { migratedFrom } : {}) };
 }
 function failParse(reason) {
     throw new Error(`Invalid PAI export: ${reason}`);
 }
+function failValidation(problems) {
+    const shown = problems.slice(0, MAX_PROBLEMS_SHOWN);
+    const remaining = problems.length - shown.length;
+    const lines = [
+        `Invalid PAI export: ${problems.length} problem(s)`,
+        ...shown.map((problem) => `  - ${problem}`),
+        ...(remaining > 0 ? [`  - … and ${remaining} more`] : []),
+    ];
+    throw new Error(lines.join('\n'));
+}
 /**
  * Make sure the hand-written file references the managed one. Only a suffix
  * is ever produced — the caller appends it in place, so a symlinked CLAUDE.md

package/docs/export-format.md

@@ -0,0 +1,83 @@
+# PAI export format
+
+The contract for the JSON file `pai export` writes and `pai import` reads.
+It exists so a file exported by one version of PAI, on one machine, imports
+safely — or fails clearly — on another.
+
+## Format 2 (current)
+
+```json
+{
+  "version": 2,
+  "pai": "0.3.1",
+  "exportedAt": "2026-08-29T12:00:00.000Z",
+  "rules": [
+    { "rule": "Keep answers short.", "category": "Communication", "scope": "global" },
+    { "rule": "Never force-push.", "category": "Git", "scope": "project" }
+  ]
+}
+```
+
+| Field | Type | Required | Constraint |
+|---|---|---|---|
+| `version` | number | yes | must be `2` |
+| `pai` | string | no | PAI version that produced the file |
+| `exportedAt` | string | no | ISO-8601 timestamp, parseable by `Date` |
+| `rules` | array | yes | array of rule objects (may be empty) |
+| `rules[].rule` | string | yes | non-empty after trim, max 500 chars |
+| `rules[].category` | string | no | max 80 chars; defaults to `"General"` |
+| `rules[].scope` | string | yes | `"global"` or `"project"` |
+
+Unknown extra fields — at the top level or inside a rule object — are
+ignored, both by validation and on import. This is what lets a newer PAI add
+fields to the format without breaking an older one that only understands the
+fields above.
+
+## Normalization
+
+On import, each rule is normalized before it is compared or written:
+
+- CRLF and lone CR are converted to LF
+- newlines inside `rule` become a single space (a rule is one bullet, one line)
+- the result is trimmed
+- an empty or missing `category` becomes `"General"`
+
+## Compatibility policy
+
+- **Same format** (`version: 2`) — always safe to import, on any PAI version
+  that supports format 2.
+- **Older format** — migrated automatically. Migrations applied so far:
+  - **1 → 2**: reads the old `.pai/rules.json` store shape
+    (`rules[].{rule,category,scope}`, plus `id`, `evidence`, `source`,
+    `createdAt`/`updatedAt`). Only `rule`, `category` and `scope` survive;
+    `id`, `evidence`, `source` and the timestamps are dropped — none of them
+    are part of the export format.
+- **Newer format** — rejected with an exact, upgrade-pointing message:
+
+  ```
+  Invalid PAI export: format <N> was produced by pai <pai or "unknown">; this pai (<current>) supports up to format 2 — upgrade pai
+  ```
+
+## Validation errors
+
+An invalid file (right format, wrong contents) is rejected with every
+problem found, not just the first one:
+
+```
+Invalid PAI export: 2 problem(s)
+  - rules[0].rule: expected non-empty string (max 500 chars)
+  - rules[0].scope: expected "global" or "project"
+```
+
+Each line is prefixed with a JSON path to the offending field. At most 20
+problems are listed; beyond that, a final line reads `  - … and N more`.
+
+Run `pai import <file> --validate` to check a file against this contract —
+parse, migrate, and validate — without writing anything.
+
+## Encodings accepted
+
+`pai import` decodes, in order of likelihood: UTF-8, UTF-8 with a BOM
+(as written by Notepad or PowerShell's `Set-Content`), and UTF-16 with a BOM
+(as written by PowerShell 5.1's `>` redirect). `pai export` always writes
+UTF-8 with LF line endings and no BOM.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lastboy/pai",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "PAI — Personal AI Supervisor: a local-first CLI that observes how you work with AI coding agents and turns it into knowledge you own",
   "keywords": [
     "cli",