@cspeach/cli 1.1.13 → 1.1.15

package/README.md

@@ -128,6 +128,69 @@ If `cspeach doctor` fails:
 
 If the REPL hangs on first prompt, check `https://api.cspeach.dev/health`.
 
+## Working on team projects (contributors only)
+
+`cspeach team …` and the `/team/` page are built on two sibling packages in this
+repo:
+
+- `register-core/` — the merge: records in, one picture out
+- `sap-client/` — the SAP calls, including `atcRunSet`
+
+The CLI depends on them as **`file:` links**, and pnpm **copies their `dist/`**
+into `node_modules` at install time. Neither `dist/` is in git. So a fresh
+checkout, or any checkout where somebody changed one of them and did not
+rebuild, runs the CLI against whatever was copied last — usually a
+`TypeError: … is not a function` in the middle of a `cspeach team refresh`.
+
+`src/register/__tests__/linked-packages.test.ts` is the tripwire. When it fails
+with *"The linked packages are out of date"*, run the recipe below.
+
+### The recipe
+
+Git Bash:
+
+```bash
+cd sap-client     && npm run build
+cd ../register-core && ../cspeach-cli/node_modules/.bin/tsc
+cd ../cspeach-cli && pnpm install
+```
+
+Windows (PowerShell or cmd):
+
+```text
+cd sap-client
+npm run build
+cd ..\register-core
+..\cspeach-cli\node_modules\.bin\tsc.CMD
+cd ..\cspeach-cli
+pnpm install
+```
+
+Then check the link really took:
+
+```bash
+grep -c ruleIdFromAtc cspeach-cli/node_modules/@cspeach/register-core/dist/rules.js   # ≥ 1
+grep -c atcRunSet     cspeach-cli/node_modules/@cspeach/sap-client/dist/adt-client.js # ≥ 1
+```
+
+If either prints `0`, run `pnpm install --force` in `cspeach-cli/`.
+
+Notes:
+
+- **`npm run build` does not work in `register-core/`** in this checkout — its
+  devDependencies are not installed. Build it with the CLI's own compiler, as
+  above. `sap-client/` builds normally.
+- **`dist/index.js` is only a re-export barrel**, so grep a real module
+  (`dist/rules.js`, `dist/register.js`) when you check a new name landed.
+- **`pnpm install` rewrites one path separator in `cspeach-cli/pnpm-lock.yaml`.**
+  That is noise. Restore it before you commit:
+  `git checkout -- cspeach-cli/pnpm-lock.yaml`.
+- The **viewer** reads `register-core` from SOURCE (a Vite alias) and needs none
+  of this.
+- Both packages are **unpublished**. `prepublishOnly` blocks `npm publish` of
+  the CLI while either dependency is still a `file:` link; they have to be
+  published and the versions pinned before a CLI release.
+
 ## Links
 
 - **Landing**: https://cspeach.dev

package/dist/cli.js

@@ -4,6 +4,11 @@ import { runAddSapWizard } from './sap/onboarding.js';
 import { runGcOnStartup } from './session/gc.js';
 import { checkForUpgrade } from './upgrade-check.js';
 import { extractSapAliasFlag, extractNoSapFlag } from './cli-args.js';
+/**
+ * The verbs that make `cspeach project …` a mistyped team command rather than
+ * a prompt somebody meant to send. See the check in `main`.
+ */
+const TEAM_SUBCOMMANDS = new Set(['init', 'join', 'lane', 'refresh', 'status', 'outbox', 'rule', 'leave']);
 export async function main(argv) {
     runGcOnStartup().catch(() => { });
     checkForUpgrade().catch(() => { });
@@ -144,6 +149,47 @@ export async function main(argv) {
         const cfg = await loadConfig();
         return runWhoamiCommand({ proxyUrl: cfg.proxy_url, print: (s) => console.log(s) });
     }
+    // A team project — many laptops, one picture (spec 2026-09-18).
+    if (args[0] === 'team') {
+        const { runTeamCommand } = await import('./commands/team.js');
+        const { getAuthorIdentity } = await import('./agent/loop.js');
+        return runTeamCommand(args.slice(1), {
+            print: (s) => console.log(s),
+            identity: () => getAuthorIdentity(),
+            noSap,
+            // Standalone: no connection is offered at all, so nothing in `team` can reach for one.
+            connect: noSap ? undefined : async (alias) => {
+                const { loadConfig } = await import('./config/loader.js');
+                const { getConnection } = await import('./sap/connection-manager.js');
+                const { AdtClient } = await import('@cspeach/sap-client');
+                const cfg = await loadConfig();
+                const name = alias ?? sapAlias ?? Object.keys(cfg.sap)[0];
+                if (!name || !cfg.sap[name])
+                    throw new Error('No SAP system is configured. Run: cspeach config add-sap');
+                const adt = new AdtClient(await getConnection(name, cfg.sap[name]));
+                return {
+                    sql: (q, max) => adt.sqlQuery(q, max),
+                    system: { sid: name },
+                    atc: { runSet: (refs, variant, opts) => adt.atcRunSet(refs, variant, opts) },
+                };
+            },
+            ask: async (question) => {
+                const { isHeadless } = await import('./renderer/tty.js');
+                if (isHeadless())
+                    return '';
+                const { input } = await import('@inquirer/prompts');
+                return input({ message: question });
+            },
+        });
+    }
+    // Typed from yesterday's notes. Without this the words fall through to the
+    // one-shot path at the bottom of this function and are sent to the model as
+    // a PAID prompt on a machine that is configured and logged in. A hint, not
+    // an alias: the old family does not run, and nothing is renamed back.
+    if (args[0] === 'project' && TEAM_SUBCOMMANDS.has(args[1] ?? '')) {
+        console.log('Unknown command: cspeach project. Team projects use: cspeach team init|join|lane|refresh|status|outbox|rule|leave');
+        return 1;
+    }
     if (args[0] === 'analyze' && args[1] === 'project-context') {
         const { runProjectContextImpactCommand } = await import('./commands/project-context-impact.js');
         return runProjectContextImpactCommand(args.slice(2));
@@ -162,32 +208,40 @@ export async function main(argv) {
     return runRepl({ sapAlias, noSap });
 }
 function printHelp() {
-    console.log(`
-CSPeach — AI-assisted ABAP development CLI
-
-Usage:
-  cspeach                           Start interactive REPL
-  cspeach "<prompt>"                One-shot — runs one turn and exits
-  cspeach --one-shot "<prompt>"     Same as above, explicit flag
-  cspeach --sap-alias <name>        Use a specific SAP alias (overrides default)
-  cspeach --no-sap                  Start without a SAP system (paste-mode skills only)
-  cspeach --resume [id]             Resume a previous session (list if no id)
-  cspeach config add-sap            Add a SAP system interactively
-  cspeach config standalone         Set the standalone SAP profile (no system)
-  cspeach standards init            Capture your team's ABAP development standards
-  cspeach configure                 Alias for \`cspeach config add-sap\`
-  cspeach config set <key> <value>  Update a config key
-  cspeach config unset <key>        Remove a config key (revert to default)
-  cspeach config show [key]         Show config (full or single key)
-  cspeach doctor                    Diagnose install + connectivity
-  cspeach login                     Sign in via device-code flow
-  cspeach logout                    Sign out (keep keychain key, if any)
-  cspeach whoami                    Print current account info
-  cspeach analyze project-context   Compare flag-on vs flag-off session metrics
-  cspeach --upgrade                 Upgrade to latest via npm
-  cspeach --version                 Print version
-  cspeach --help                    Show this help
-
-Docs: https://cspeach.dev
+    console.log(`
+CSPeach — AI-assisted ABAP development CLI
+
+Usage:
+  cspeach                           Start interactive REPL
+  cspeach "<prompt>"                One-shot — runs one turn and exits
+  cspeach --one-shot "<prompt>"     Same as above, explicit flag
+  cspeach --sap-alias <name>        Use a specific SAP alias (overrides default)
+  cspeach --no-sap                  Start without a SAP system (paste-mode skills only)
+  cspeach --resume [id]             Resume a previous session (list if no id)
+  cspeach config add-sap            Add a SAP system interactively
+  cspeach config standalone         Set the standalone SAP profile (no system)
+  cspeach standards init            Capture your team's ABAP development standards
+  cspeach configure                 Alias for \`cspeach config add-sap\`
+  cspeach config set <key> <value>  Update a config key
+  cspeach config unset <key>        Remove a config key (revert to default)
+  cspeach config show [key]         Show config (full or single key)
+  cspeach doctor                    Diagnose install + connectivity
+  cspeach login                     Sign in via device-code flow
+  cspeach logout                    Sign out (keep keychain key, if any)
+  cspeach whoami                    Print current account info
+  cspeach team init <folder>        Lead: pull the object list from SAP, start a team project
+  cspeach team join <folder>        Record your results against a team project (on this laptop only)
+  cspeach team lane add|list        Lead: who owns which packages
+  cspeach team refresh --lane <id>  Measure with ATC: what is verified, what did not hold
+  cspeach team status [folder]      Where every object stands, who owns it, what is proven
+  cspeach team outbox               What this laptop has recorded, and where
+  cspeach team rule T N <d>         Lead: settle a conflicting decision
+  cspeach team leave                Stop recording
+  cspeach analyze project-context   Compare flag-on vs flag-off session metrics
+  cspeach --upgrade                 Upgrade to latest via npm
+  cspeach --version                 Print version
+  cspeach --help                    Show this help
+
+Docs: https://cspeach.dev
 `);
 }

package/dist/commands/project.js

@@ -0,0 +1,301 @@
+/**
+ * `cspeach project …` — the Project Register from the terminal
+ * (spec: docs/superpowers/specs/2026-09-18-project-register-folder-mode.md §6).
+ *
+ *   init <folder>   lead: pull the baseline from SAP, write the project folder
+ *   join <folder>   everyone: start recording against a project
+ *   lane …          lead: who owns which packages
+ *   status [folder] anyone: the register as text
+ *   outbox          what this laptop has recorded, and where
+ *   rule …          lead: settle a disagreement
+ *   leave           stop recording
+ *
+ * Every path written here is one a person typed. Nothing is written to a
+ * network location on CSPeach's own initiative, and none of this is reachable
+ * from a model tool.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { buildRegister, objectKey } from '@cspeach/register-core';
+import { LOCAL_PACKAGE, listCustomPackages, pullBaseline, BaselineError } from '../register/baseline.js';
+import { BASELINE_FILE, PROJECT_FILE, RegisterError, activeProject, collectRecords, defaultOutboxDir, loadState, projectIdFor, readBaseline, readLanes, readProjectFile, saveState, sha256, writeLanes, writerIdFor, } from '../register/store.js';
+import { writeRecord } from '../register/records.js';
+const CLASSIFICATIONS = ['keep', 'fix', 'retire', 'redesign'];
+const TYPES = ['clean-core', 'upgrade', 'build'];
+function flags(args) {
+    const positional = [];
+    const opts = {};
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a.startsWith('--')) {
+            opts[a.slice(2)] = args[i + 1] && !args[i + 1].startsWith('--') ? args[++i] : 'true';
+        }
+        else
+            positional.push(a);
+    }
+    return { positional, opts };
+}
+const list = (v) => (v ?? '').split(',').map((s) => s.trim()).filter(Boolean);
+/** `ZFI_*` style match, used only to expand --packages patterns against the real package list. */
+function matches(pattern, value) {
+    const re = new RegExp(`^${pattern.replace(/[.+?^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*')}$`, 'i');
+    return re.test(value);
+}
+export async function runProjectCommand(args, deps) {
+    const [sub, ...rest] = args;
+    try {
+        switch (sub) {
+            case 'init': return await init(rest, deps);
+            case 'join': return join(rest, deps);
+            case 'lane': return lane(rest, deps);
+            case 'status': return status(rest, deps);
+            case 'outbox': return outbox(rest, deps);
+            case 'rule': return rule(rest, deps);
+            case 'leave': return leave(deps);
+            default:
+                deps.print('Usage: cspeach project init|join|lane|status|outbox|rule|leave   (cspeach --help for details)');
+                return sub ? 1 : 0;
+        }
+    }
+    catch (e) {
+        if (e instanceof RegisterError || e instanceof BaselineError) {
+            deps.print(`✗ ${e.message}`);
+            return 1;
+        }
+        throw e;
+    }
+}
+function requireLead(project, deps) {
+    const me = deps.identity().name;
+    if (me.trim().toLowerCase() !== project.lead.name.trim().toLowerCase()) {
+        throw new RegisterError(`Only the project lead (${project.lead.name}) changes this. You are ${me}.`);
+    }
+}
+function joinedOrThrow() {
+    const joined = activeProject();
+    if (!joined)
+        throw new RegisterError('This laptop has not joined a project. Run: cspeach project join <folder>');
+    return joined;
+}
+// ── init ────────────────────────────────────────────────────────────────────
+async function init(args, deps) {
+    const { positional, opts } = flags(args);
+    const folder = positional[0];
+    if (!folder)
+        throw new RegisterError('Usage: cspeach project init <folder> --name "<name>" [--type clean-core|upgrade|build] [--packages ZFI_*,ZSD_*] [--include-local]');
+    const dir = path.resolve(folder);
+    if (fs.existsSync(path.join(dir, PROJECT_FILE)))
+        throw new RegisterError(`${dir} already holds a project. Pick an empty folder.`);
+    const name = opts.name ?? path.basename(dir);
+    const type = (opts.type ?? 'clean-core');
+    if (!TYPES.includes(type))
+        throw new RegisterError(`--type must be one of: ${TYPES.join(', ')}`);
+    if (!deps.connect)
+        throw new RegisterError('init needs a SAP connection to pull the object list.');
+    const { sql, system } = await deps.connect(opts['sap-alias']);
+    deps.print('Reading the package list from SAP…');
+    const all = await listCustomPackages(sql);
+    const patterns = list(opts.packages);
+    let chosen = all.filter((p) => patterns.some((pat) => matches(pat, p.package)));
+    if (!patterns.length && deps.choosePackages) {
+        const picked = new Set(await deps.choosePackages(all));
+        chosen = all.filter((p) => picked.has(p.package));
+    }
+    const local = all.find((p) => p.package === LOCAL_PACKAGE)?.objects ?? 0;
+    if (!opts['include-local'])
+        chosen = chosen.filter((p) => p.package !== LOCAL_PACKAGE);
+    if (!chosen.length) {
+        throw new RegisterError(`No package chosen. ${all.length} customer packages exist; name them with --packages, e.g. --packages "ZFI_*,ZSD_*".`);
+    }
+    deps.print(`Pulling ${chosen.length} package${chosen.length === 1 ? '' : 's'}, checking each against the system's own count…`);
+    const pull = await pullBaseline(sql, { packages: chosen });
+    if (!pull.objects.length)
+        throw new RegisterError('Those packages hold no code objects. Nothing was written.');
+    const now = (deps.now ?? (() => new Date()))();
+    const projectId = projectIdFor(name);
+    const baselineText = `${JSON.stringify({ kind: 'baseline', formatVersion: 1, projectId, objects: pull.objects }, null, 1)}\n`;
+    const project = {
+        kind: 'project', formatVersion: 1, projectId, name, type, lead: { name: deps.identity().name },
+        ...(system ? { system } : {}),
+        ...(opts['atc-variant'] ? { atcVariant: opts['atc-variant'] } : {}),
+        baseline: { file: BASELINE_FILE.replace(/\\/g, '/'), sha256: sha256(baselineText), takenAt: now.toISOString(), objectCount: pull.objects.length },
+        setAside: { local: opts['include-local'] ? 0 : local, generated: pull.setAside.generated, otherTypes: pull.setAside.otherTypes },
+        createdAt: now.toISOString(),
+    };
+    fs.mkdirSync(path.join(dir, 'baseline'), { recursive: true });
+    fs.writeFileSync(path.join(dir, BASELINE_FILE), baselineText);
+    fs.writeFileSync(path.join(dir, PROJECT_FILE), `${JSON.stringify(project, null, 2)}\n`);
+    writeLanes(dir, projectId, []);
+    deps.print(`✓ ${name}: ${pull.objects.length} objects in ${chosen.length} packages. Every package matched the system's count.`);
+    deps.print(`  Set aside, not in scope: ${project.setAside.local} local ($TMP), ${pull.setAside.generated} generated, ${pull.setAside.otherTypes} non-code entries.`);
+    deps.print(`  Written to ${dir}`);
+    deps.print('  Next: cspeach project lane add <id> --owner "<name>" --packages "ZFI_*"   then each person: cspeach project join <folder>');
+    return join([dir], deps);
+}
+// ── join / leave ────────────────────────────────────────────────────────────
+function join(args, deps) {
+    const { positional, opts } = flags(args);
+    if (!positional[0])
+        throw new RegisterError('Usage: cspeach project join <project folder> [--outbox <folder>]');
+    const projectDir = path.resolve(positional[0]);
+    const project = readProjectFile(projectDir);
+    const objects = readBaseline(projectDir).length; // also verifies the checksum
+    const state = loadState();
+    const outboxDir = path.resolve(opts.outbox ?? state.projects[project.projectId]?.outboxDir ?? defaultOutboxDir(project.projectId));
+    const writerId = writerIdFor(deps.identity().name);
+    fs.mkdirSync(path.join(outboxDir, 'writers', writerId, 'records'), { recursive: true });
+    state.projects[project.projectId] = { projectDir, outboxDir, writerId };
+    state.active = project.projectId;
+    saveState(state);
+    deps.print(`✓ Joined "${project.name}" (${objects} objects, lead ${project.lead.name}) as ${writerId}.`);
+    deps.print(`  Your results are recorded on this laptop, in ${outboxDir}`);
+    deps.print('  CSPeach does not send them anywhere. Hand them in by copying that folder\'s "writers" folder into the project folder,');
+    deps.print('  or keep the outbox inside your own synced folder: cspeach project join <folder> --outbox <folder>');
+    return 0;
+}
+function leave(deps) {
+    const state = loadState();
+    if (!state.active) {
+        deps.print('This laptop is not recording against a project.');
+        return 0;
+    }
+    const was = state.active;
+    state.active = null;
+    saveState(state);
+    deps.print(`✓ Stopped recording against ${was}. Files already written stay where they are.`);
+    return 0;
+}
+// ── lane ────────────────────────────────────────────────────────────────────
+function lane(args, deps) {
+    const [verb, ...rest] = args;
+    const { positional, opts } = flags(rest);
+    const joined = joinedOrThrow();
+    const project = readProjectFile(joined.projectDir);
+    const lanes = readLanes(joined.projectDir);
+    if (verb === 'list' || !verb) {
+        if (!lanes.length)
+            deps.print('No lanes yet. cspeach project lane add <id> --owner "<name>" --packages "ZFI_*"');
+        for (const l of lanes)
+            deps.print(`${l.id.padEnd(12)} ${l.owner.padEnd(20)} ${[...l.packages, ...l.namePatterns.map((n) => `name:${n}`)].join(', ')}`);
+        return 0;
+    }
+    requireLead(project, deps);
+    const id = positional[0];
+    if (!id)
+        throw new RegisterError('Usage: cspeach project lane add <id> --owner "<name>" --packages "ZFI_*" [--names "ZCL_TAX_*"]  |  lane remove <id>');
+    if (verb === 'remove') {
+        writeLanes(joined.projectDir, project.projectId, lanes.filter((l) => l.id !== id));
+        deps.print(`✓ Lane ${id} removed.`);
+        return 0;
+    }
+    if (verb !== 'add')
+        throw new RegisterError('lane: use add, remove or list.');
+    const next = { id, owner: opts.owner ?? '', packages: list(opts.packages), namePatterns: list(opts.names) };
+    if (!next.owner || (!next.packages.length && !next.namePatterns.length)) {
+        throw new RegisterError('A lane needs --owner and at least one of --packages or --names.');
+    }
+    writeLanes(joined.projectDir, project.projectId, [...lanes.filter((l) => l.id !== id), next]);
+    const reg = registerFor(joined.projectDir, joined.outboxDir);
+    const mine = reg.register.lanes.find((l) => l.id === id);
+    deps.print(`✓ Lane ${id}: ${next.owner}, ${mine.objects} objects.`);
+    if (reg.register.totals.overlapping)
+        deps.print(`  ! ${reg.register.totals.overlapping} objects now sit in more than one lane.`);
+    if (reg.register.totals.unowned)
+        deps.print(`  ${reg.register.totals.unowned} objects still have no owner.`);
+    return 0;
+}
+// ── status ──────────────────────────────────────────────────────────────────
+function registerFor(projectDir, outboxDir) {
+    const project = readProjectFile(projectDir);
+    const collected = collectRecords(projectDir);
+    // This laptop's own outbox counts too, so a developer sees their work before handing it in.
+    const own = outboxDir && path.resolve(outboxDir) !== path.resolve(projectDir) ? collectRecords(outboxDir) : { records: [], unreadable: 0, files: 0 };
+    const register = buildRegister({
+        project, baseline: readBaseline(projectDir), lanes: readLanes(projectDir),
+        records: [...collected.records, ...own.records],
+    });
+    return { register, files: collected.files + own.files, unreadable: collected.unreadable + own.unreadable };
+}
+const STATE_WORDS = [
+    ['verified', 'verified'], ['clean', 'clean'], ['claimed', 'claimed, not measured since'], ['working', 'in work'],
+    ['decided', 'decided, not started'], ['untouched', 'untouched'], ['did-not-hold', 'fix did not hold'],
+    ['regressed', 'regressed'], ['retired', 'retired'],
+];
+function status(args, deps) {
+    const { positional } = flags(args);
+    const joined = activeProject();
+    const projectDir = positional[0] ? path.resolve(positional[0]) : joined?.projectDir;
+    if (!projectDir)
+        throw new RegisterError('Usage: cspeach project status [<project folder>]');
+    const project = readProjectFile(projectDir);
+    const { register: r, files, unreadable } = registerFor(projectDir, positional[0] ? undefined : joined?.outboxDir);
+    const t = r.totals;
+    deps.print(`${project.name}  (${project.type}, lead ${project.lead.name})`);
+    deps.print(`${t.objects} objects, ${t.active} active. ${t.decided} decided. ${t.byState.verified} verified, ${t.byState.clean} clean.`);
+    deps.print(r.lastMeasuredAt ? `Last measured ${r.lastMeasuredAt.slice(0, 16).replace('T', ' ')} UTC.` : 'Not measured yet: "verified" and "clean" need an ATC run.');
+    deps.print('');
+    for (const [state, word] of STATE_WORDS)
+        if (t.byState[state])
+            deps.print(`  ${String(t.byState[state]).padStart(6)}  ${word}`);
+    deps.print('');
+    if (r.lanes.length) {
+        deps.print('Lane         Owner                Objects  Done  Last record');
+        for (const l of r.lanes) {
+            const done = l.byState.verified + l.byState.clean + l.byState.retired;
+            deps.print(`${l.id.padEnd(12)} ${l.owner.padEnd(20)} ${String(l.objects).padStart(7)} ${String(done).padStart(5)}  ${l.lastRecordAt ? l.lastRecordAt.slice(0, 10) : 'nothing yet'}`);
+        }
+        deps.print('');
+    }
+    if (t.unowned)
+        deps.print(`! ${t.unowned} objects have no owner.`);
+    if (t.overlapping)
+        deps.print(`! ${t.overlapping} objects sit in more than one lane.`);
+    if (t.conflicts) {
+        deps.print(`! ${t.conflicts} objects have conflicting decisions. The lead settles each with: cspeach project rule <TYPE> <NAME> <decision>`);
+        for (const o of r.objects.filter((x) => x.decision?.conflict).slice(0, 10)) {
+            deps.print(`    ${o.key}: ${Object.entries(o.decision.conflict).map(([w, c]) => `${w} says ${c}`).join(', ')}`);
+        }
+    }
+    const s = r.skipped;
+    if (unreadable)
+        deps.print(`  ${unreadable} of ${files} files could not be read yet (still syncing, or damaged).`);
+    if (s.rowsNotInBaseline)
+        deps.print(`  ${s.rowsNotInBaseline} rows named objects that are not in this project: ${r.unknownKeys.slice(0, 5).join(', ')}`);
+    if (s.otherProject)
+        deps.print(`  ${s.otherProject} files belong to another project and were ignored.`);
+    if (s.rulingsNotFromLead)
+        deps.print(`  ${s.rulingsNotFromLead} rulings were not from the lead and were ignored.`);
+    return 0;
+}
+// ── outbox / rule ───────────────────────────────────────────────────────────
+function outbox(_args, deps) {
+    const joined = joinedOrThrow();
+    const dir = path.join(joined.outboxDir, 'writers', joined.writerId, 'records');
+    const files = fs.existsSync(dir) ? fs.readdirSync(dir).filter((f) => f.endsWith('.json')).sort() : [];
+    deps.print(`Records this laptop has written for ${joined.projectId}: ${files.length}`);
+    deps.print(`  ${dir}`);
+    for (const f of files.slice(-15)) {
+        let rows = '?';
+        try {
+            rows = String(JSON.parse(fs.readFileSync(path.join(dir, f), 'utf8')).rows.length);
+        }
+        catch { /* listed anyway */ }
+        deps.print(`  ${f}  (${rows} rows)`);
+    }
+    deps.print('Each file is plain JSON: object names, decisions, statuses. No source code. Open one in Notepad to check.');
+    return 0;
+}
+function rule(args, deps) {
+    const { positional, opts } = flags(args);
+    const [type, name, classification] = positional;
+    if (!type || !name || !CLASSIFICATIONS.includes(classification)) {
+        throw new RegisterError(`Usage: cspeach project rule <TYPE> <NAME> ${CLASSIFICATIONS.join('|')} [--reason "<why>"]`);
+    }
+    const joined = joinedOrThrow();
+    requireLead(readProjectFile(joined.projectDir), deps);
+    const res = writeRecord(joined, 'ruling', [{ key: objectKey(type, name), classification, ...(opts.reason ? { reason: opts.reason } : {}) }], deps.identity(), { dir: path.join(joined.projectDir, 'rulings'), now: deps.now?.() });
+    if (!res.file)
+        throw new RegisterError(`${objectKey(type, name)} is not in this project's baseline.`);
+    deps.print(`✓ Ruled ${objectKey(type, name)} = ${classification}.`);
+    return 0;
+}