@cspeach/cli 1.1.30 → 1.1.32

package/dist/commands/team-plan.js

@@ -0,0 +1,585 @@
+/**
+ * Steering a team project (spec 2026-10-06 §7, D3): the lane proposal, the
+ * focus, the priority rules and the per-object plan changes.
+ *
+ *   lane propose --developers "…" [--apply]   lead: a first cut of the lanes
+ *   focus "<label>" (--packages|--objects|--lane) --reason "…"   lead: what the team works on now
+ *   focus list | clear <id|label>
+ *   priority show | set … --reason | reset --reason
+ *   plan move|scope|defer|set|note|history
+ *
+ * Every change is one append-only record in the lead's `plan/` folder, written
+ * whole then renamed. Lanes stay patterns in `lanes.json`; everything per object
+ * is a plan record, and the register folds them on read. Nothing here edits a
+ * record or reaches SAP, and none of it is reachable from a model tool.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { buildRegister, DEFAULT_WEIGHTS, inLane, objectKey, proposeLanes, utcWords, } from '@cspeach/register-core';
+import { RegisterError, collectRecords, readBaseline, readLanes, readProjectFile, writeLanes, } from '../register/store.js';
+import { diffPlan, readPlanSheet } from '../register/plan-import.js';
+import { writeLeadRecord } from '../register/records.js';
+import { registerFor } from '../register/picture.js';
+import { shown, shownUpTo } from '../register/atc-file.js';
+import { flags, heldReportLine, joinedOrThrow, list, requireLead, whoAmI, writeReports } from './team.js';
+const MAX_REASON = 300;
+export const NEEDS_REASON = '--reason needs words: what changed and why.';
+const NO_FOCUS = 'No focus set. Working lists follow the suggested order.';
+const NO_MATCH = 'That selector matches no object in this team project.';
+const NOTHING_REPLANNED = 'Nothing has been re-planned. Lists follow the suggested order.';
+const WEIGHT_PARTS = ['effort', 'risk', 'shared', 'usage', 'disposition'];
+const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+const plural = (count, one, many) => `${count} ${count === 1 ? one : many}`;
+/** "7 Oct" — a record's day, in UTC like every time the team project shows. */
+export const dayMonth = (iso) => {
+    const d = new Date(iso);
+    return Number.isNaN(d.getTime()) ? '' : `${d.getUTCDate()} ${MONTHS[d.getUTCMonth()]}`;
+};
+const nameOf = (key) => key.slice(key.indexOf('|') + 1);
+const matches = (pattern, value) => new RegExp(`^${pattern.trim().replace(/[.+?^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*')}$`, 'i').test(value);
+/**
+ * The reason, the way `decide` reads one: trimmed, a bare flag refused, at most
+ * 300 characters. `required` refuses an empty one with the one sentence.
+ */
+export function reasonFrom(opts, required) {
+    if (opts.reason === 'true')
+        throw new RegisterError(NEEDS_REASON);
+    const reason = (opts.reason ?? '').trim();
+    if (required && !reason)
+        throw new RegisterError(NEEDS_REASON);
+    if (reason.length > MAX_REASON)
+        throw new RegisterError(`Keep the reason under ${MAX_REASON} characters.`);
+    return reason;
+}
+/** Anything a verb does not know is a typo, refused rather than ignored. */
+function onlyOptions(opts, known, usage) {
+    for (const name of Object.keys(opts))
+        if (!known.includes(name))
+            throw new RegisterError(`Unknown option --${name}.\n${usage}`);
+}
+/** The joined team project, checked to be led from this laptop. */
+function asLead(deps) {
+    const joined = joinedOrThrow();
+    const project = readProjectFile(joined.projectDir);
+    requireLead(project, deps);
+    return { projectDir: joined.projectDir, outboxDir: joined.outboxDir, project, by: { name: whoAmI(deps), writer: joined.writerId } };
+}
+/** One plan record into `plan/`; the file NAME comes back, never the path. */
+function writePlan(lead, header, rows, deps) {
+    const { file } = writeLeadRecord(path.join(lead.projectDir, 'plan'), lead.project.projectId, 'plan', header, rows, lead.by, {
+        ...(deps.now ? { now: deps.now() } : {}), ...(deps.rand ? { rand: deps.rand } : {}),
+    });
+    return path.basename(file);
+}
+const writtenLine = (file) => `  Written to the plan folder: ${file}`;
+/** `TYPE NAME` → the key, refused by name when the baseline does not hold it. */
+function keyIn(projectDir, type, name, usage) {
+    if (!type || !name)
+        throw new RegisterError(usage);
+    const key = objectKey(type.toUpperCase(), name.toUpperCase());
+    if (!readBaseline(projectDir).some((o) => objectKey(o.type, o.name) === key)) {
+        throw new RegisterError(`${shown(type.toUpperCase())} ${shown(name.toUpperCase())} is not in this team project's object list.`);
+    }
+    return key;
+}
+const lanesWords = (lanes) => lanes.map((l) => `${l.owner} (${l.id})`).join(', ') || 'none yet';
+function laneOrThrow(lanes, id) {
+    const lane = lanes.find((l) => l.id.toLowerCase() === id.trim().toLowerCase());
+    if (!lane)
+        throw new RegisterError(`There is no lane "${shown(id)}". Lanes: ${lanesWords(lanes)}.`);
+    return lane;
+}
+// ── lane propose, and the record beside lane add / remove ──────────────────
+const PROPOSE_USAGE = 'Usage: cspeach team lane propose --developers "Sarah Davis,James Miller" [--apply] [--reason "<why>"]';
+export async function laneProposal(args, deps) {
+    const { positional, opts } = flags(args, ['apply']);
+    onlyOptions(opts, ['developers', 'apply', 'reason'], PROPOSE_USAGE);
+    if (positional.length || !opts.developers || opts.developers === 'true')
+        throw new RegisterError(PROPOSE_USAGE);
+    const reason = reasonFrom(opts, false);
+    const lead = asLead(deps);
+    const seen = new Set();
+    const developers = list(opts.developers).map((d) => d.slice(0, 80)).filter((d) => {
+        const k = d.toLowerCase();
+        return seen.has(k) ? false : (seen.add(k), true);
+    });
+    if (!developers.length)
+        throw new RegisterError(PROPOSE_USAGE);
+    const { register } = registerFor(lead.projectDir, lead.outboxDir);
+    const proposal = proposeLanes(register, developers);
+    for (const l of proposal.lanes) {
+        deps.print(`${l.owner} (${l.id}): ${l.packages.join(', ') || 'no package'} — ${plural(l.objects, 'object', 'objects')}, `
+            + `${plural(l.findings, 'finding', 'findings')}, ${l.share}% of the work`);
+    }
+    deps.print(proposal.note
+        ? `  ${proposal.note[0].toUpperCase()}${proposal.note.slice(1)}.`
+        : '  Balanced by the work: objects with findings count three times, then findings, then objects.');
+    deps.print(`Unowned after this proposal: ${proposal.unowned}`);
+    const existing = readLanes(lead.projectDir);
+    let yes = opts.apply === 'true';
+    if (!yes) {
+        if (!deps.ask) {
+            deps.print(`Nothing was written. To apply it: cspeach team lane propose --developers "${developers.join(',')}" --apply`);
+            return 0;
+        }
+        if (existing.length)
+            deps.print(`  Applying replaces the lanes there are now: ${lanesWords(existing)}.`);
+        const answer = (await deps.ask('Apply this proposal? [y/n]')).trim().toLowerCase();
+        yes = answer === 'y' || answer === 'yes';
+        if (!yes) {
+            deps.print('Nothing was written.');
+            return 0;
+        }
+    }
+    const next = proposal.lanes.map((l) => ({ id: l.id, owner: l.owner, packages: l.packages, namePatterns: [] }));
+    writeLanes(lead.projectDir, lead.project.projectId, next);
+    const files = [];
+    // A lane the proposal drops is a removal in the history, so nothing leaves lanes.json unrecorded.
+    for (const gone of existing.filter((e) => !next.some((l) => l.id === e.id))) {
+        files.push(writePlan(lead, {
+            action: 'lane',
+            lane: { id: gone.id, change: 'remove', before: { owner: gone.owner, packages: gone.packages }, after: null },
+            ...(reason ? { reason } : {}),
+        }, [], deps));
+    }
+    for (const l of next) {
+        const was = existing.find((e) => e.id === l.id);
+        files.push(writePlan(lead, {
+            action: 'lane',
+            lane: { id: l.id, change: 'propose', before: was ? { owner: was.owner, packages: was.packages } : null, after: { owner: l.owner, packages: l.packages } },
+            ...(reason ? { reason } : {}),
+        }, [], deps));
+    }
+    deps.print(`✓ ${plural(next.length, 'lane', 'lanes')} written to lanes.json.`);
+    if (existing.length)
+        deps.print(`  Replaced: ${lanesWords(existing)}.`);
+    deps.print(`  Written to the plan folder: ${files.join(', ')}`);
+    return 0;
+}
+/** `lane add|remove`: the history beside the lanes file. Returns the line to print. */
+export function laneChangeRecord(deps, change, before, after, id, reason) {
+    const lead = asLead(deps);
+    const side = (l) => (l ? { owner: l.owner, packages: l.packages, namePatterns: l.namePatterns } : null);
+    const file = writePlan(lead, { action: 'lane', lane: { id, change, before: side(before), after: side(after) }, ...(reason ? { reason } : {}) }, [], deps);
+    return writtenLine(file);
+}
+// ── focus ───────────────────────────────────────────────────────────────────
+const FOCUS_USAGE = 'Usage: cspeach team focus "<label>" (--packages "ZFI_*" | --objects "TYPE NAME,…" | --lane <id>) --reason "<why>" [--order <n>]\n'
+    + '   or: cspeach team focus list | clear <label>';
+/** "Finance first" → "finance-first": the same label is the same focus, so setting it again replaces it. */
+export const focusIdOf = (label) => label.trim().toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40).replace(/-+$/g, '');
+function focusLine(f) {
+    return `${f.label} — set by ${f.by} on ${dayMonth(f.at)}${f.reason ? ` because ${f.reason}` : ''}; ${f.proven} of ${f.active} done`;
+}
+/** The status line: the focus the team works on now, or the sentence for none. */
+export function nowLine(register) {
+    const f = register.plan.focuses[0];
+    return f ? `Now: ${focusLine(f)}` : NO_FOCUS;
+}
+export function focusCommand(args, deps) {
+    const { positional, opts } = flags(args);
+    const [first, ...more] = positional;
+    if (first === 'list' && !more.length && !Object.keys(opts).length)
+        return focusList(deps);
+    if (first === 'clear')
+        return focusClear(more, opts, deps);
+    onlyOptions(opts, ['packages', 'objects', 'lane', 'reason', 'order'], FOCUS_USAGE);
+    if (!first || more.length)
+        throw new RegisterError(FOCUS_USAGE);
+    const label = first.trim().slice(0, MAX_REASON);
+    const id = focusIdOf(label);
+    if (!id)
+        throw new RegisterError(`A focus label needs letters or digits, for example: "Finance first"\n${FOCUS_USAGE}`);
+    const selectors = ['packages', 'objects', 'lane'].filter((k) => opts[k] !== undefined);
+    if (selectors.length !== 1)
+        throw new RegisterError(`Say which objects, one of: --packages "ZFI_*"   --objects "PROG ZFI_POST,CLAS ZCL_FI_TAX"   --lane <id>\n${FOCUS_USAGE}`);
+    const sel = selectors[0];
+    if (opts[sel] === 'true' || !opts[sel].trim())
+        throw new RegisterError(`--${sel} needs a value.\n${FOCUS_USAGE}`);
+    const reason = reasonFrom(opts, true);
+    let order;
+    if (opts.order !== undefined) {
+        if (!/^\d+$/.test(opts.order) || Number(opts.order) < 1)
+            throw new RegisterError('--order is a whole number from 1, for example: --order 1');
+        order = Number(opts.order);
+    }
+    const lead = asLead(deps);
+    const { register } = registerFor(lead.projectDir, lead.outboxDir);
+    let keys;
+    let selector;
+    if (sel === 'packages') {
+        const patterns = list(opts.packages);
+        keys = register.objects.filter((o) => patterns.some((p) => matches(p, o.package))).map((o) => o.key);
+        selector = { packages: patterns };
+    }
+    else if (sel === 'objects') {
+        const named = list(opts.objects).map((pair) => {
+            const [type, name, ...rest] = pair.split(/\s+/);
+            if (!type || !name || rest.length)
+                throw new RegisterError(`"${shown(pair)}" is not TYPE NAME, for example: --objects "PROG ZFI_POST,CLAS ZCL_FI_TAX"`);
+            return keyIn(lead.projectDir, type, name, FOCUS_USAGE);
+        });
+        keys = [...new Set(named)];
+        selector = { objects: keys };
+    }
+    else {
+        const lane = laneOrThrow(readLanes(lead.projectDir), opts.lane);
+        keys = register.objects.filter((o) => inLane(o, lane.id)).map((o) => o.key);
+        selector = { lane: lane.id };
+    }
+    if (!keys.length)
+        throw new RegisterError(NO_MATCH);
+    // The same label again REPLACES the focus (same id) and keeps its place in the
+    // stack unless --order moves it; a new label goes to the end.
+    const had = register.plan.focuses.find((f) => f.id === id);
+    const finalOrder = order ?? had?.order ?? (register.plan.focuses.reduce((m, f) => Math.max(m, f.order), 0) + 1);
+    const file = writePlan(lead, { action: 'focus-set', focus: { id, label, reason, order: finalOrder }, selector, reason }, keys.map((key) => ({ key })), deps);
+    const after = registerFor(lead.projectDir, lead.outboxDir).register;
+    deps.print(`✓ Focus set: ${plural(keys.length, 'object', 'objects')}. Now: ${after.plan.focuses[0]?.label ?? label}.`);
+    if (had)
+        deps.print(`  This replaces the focus "${had.label}" set on ${dayMonth(had.at)}.`);
+    deps.print(writtenLine(file));
+    return 0;
+}
+function focusList(deps) {
+    const joined = joinedOrThrow();
+    const { register } = registerFor(joined.projectDir, joined.outboxDir);
+    if (!register.plan.focuses.length) {
+        deps.print(NO_FOCUS);
+        return 0;
+    }
+    register.plan.focuses.forEach((f, i) => {
+        deps.print(`${i + 1}. ${focusLine(f)} (${f.donePct}%)`);
+    });
+    return 0;
+}
+function focusClear(positional, opts, deps) {
+    onlyOptions(opts, ['reason'], FOCUS_USAGE);
+    const said = positional.join(' ').trim();
+    if (!said)
+        throw new RegisterError(FOCUS_USAGE);
+    const reason = reasonFrom(opts, false);
+    const lead = asLead(deps);
+    const { register } = registerFor(lead.projectDir, lead.outboxDir);
+    const f = register.plan.focuses.find((x) => x.id === said || x.id === focusIdOf(said) || x.label.toLowerCase() === said.toLowerCase());
+    if (!f) {
+        throw new RegisterError(`There is no focus "${shown(said)}". Focuses: ${register.plan.focuses.map((x) => x.label).join(', ') || 'none set'}.`);
+    }
+    const file = writePlan(lead, { action: 'focus-clear', focusId: f.id, ...(reason ? { reason } : {}) }, [], deps);
+    const after = registerFor(lead.projectDir, lead.outboxDir).register;
+    deps.print(`✓ Focus cleared: ${f.label}. ${after.plan.focuses[0] ? `Now: ${after.plan.focuses[0].label}.` : NO_FOCUS}`);
+    deps.print(writtenLine(file));
+    return 0;
+}
+// ── priority ────────────────────────────────────────────────────────────────
+const PRIORITY_USAGE = 'Usage: cspeach team priority show\n'
+    + '   or: cspeach team priority set --effort <n> --risk <n> --shared <n> --usage <n> --disposition <n> --reason "<why>"\n'
+    + '   or: cspeach team priority reset --reason "<why>"';
+const weightsWords = (w) => WEIGHT_PARTS.map((p) => `${p} ${w[p]}`).join(', ');
+export function priorityCommand(args, deps) {
+    const [verb, ...rest] = args;
+    const { positional, opts } = flags(rest);
+    if (positional.length)
+        throw new RegisterError(PRIORITY_USAGE);
+    if (verb === 'show' || verb === undefined) {
+        onlyOptions(opts, [], PRIORITY_USAGE);
+        const joined = joinedOrThrow();
+        const { plan } = registerFor(joined.projectDir, joined.outboxDir).register;
+        deps.print(`Rule weights: ${weightsWords(plan.weights)}`
+            + `${plan.weightsFrom === 'set' ? ` — set by ${plan.weightsBy ?? 'the lead'} on ${dayMonth(plan.weightsAt ?? '')}.` : ' — the defaults.'}`);
+        deps.print('Bands: 1 at a score of 80 or more, 2 at 60 or more, 3 at 40 or more, 4 at 20 or more, 5 below 20.');
+        deps.print('A priority the lead sets by hand wins, then the focus, then these weights.');
+        deps.print('To change them: cspeach team priority set --effort n --risk n --shared n --usage n --disposition n --reason "<why>"');
+        return 0;
+    }
+    if (verb === 'set') {
+        onlyOptions(opts, [...WEIGHT_PARTS, 'reason'], PRIORITY_USAGE);
+        const weights = {};
+        for (const part of WEIGHT_PARTS) {
+            const v = opts[part];
+            if (v === undefined || !/^\d+$/.test(v) || Number(v) > 100) {
+                throw new RegisterError('priority set needs all five, each a whole number from 0 to 100: '
+                    + '--effort n --risk n --shared n --usage n --disposition n');
+            }
+            weights[part] = Number(v);
+        }
+        const reason = reasonFrom(opts, true);
+        const lead = asLead(deps);
+        const file = writePlan(lead, { action: 'weights', weights, reason }, [], deps);
+        deps.print(`✓ Rule weights set: ${weightsWords(weights)}.`);
+        deps.print(writtenLine(file));
+        return 0;
+    }
+    if (verb === 'reset') {
+        onlyOptions(opts, ['reason'], PRIORITY_USAGE);
+        const reason = reasonFrom(opts, true);
+        const lead = asLead(deps);
+        const file = writePlan(lead, { action: 'weights', weights: { ...DEFAULT_WEIGHTS }, reason }, [], deps);
+        deps.print(`✓ Rule weights back to the defaults: ${weightsWords(DEFAULT_WEIGHTS)}.`);
+        deps.print(writtenLine(file));
+        return 0;
+    }
+    throw new RegisterError(PRIORITY_USAGE);
+}
+// ── plan ────────────────────────────────────────────────────────────────────
+const PLAN_USAGE = 'Usage: cspeach team plan move <TYPE> <NAME> (--lane <id> | --unassign) --reason "<why>"\n'
+    + '   or: cspeach team plan scope (<TYPE> <NAME> | --package <pkg>) (--out | --in) --reason "<why>"\n'
+    + '   or: cspeach team plan defer <TYPE> <NAME> --reason "<why>"\n'
+    + '   or: cspeach team plan set <TYPE> <NAME> --priority 1-5|clear [--reason "<why>"]\n'
+    + '   or: cspeach team plan note <TYPE> <NAME> [--target 2026-11-30] [--note "<text>"]\n'
+    + '   or: cspeach team plan import <file.xlsx> [--yes]\n'
+    + '   or: cspeach team plan history [--object <TYPE> <NAME>]';
+/** A real calendar day, YYYY-MM-DD. */
+const isDay = (s) => /^\d{4}-\d{2}-\d{2}$/.test(s) && new Date(`${s}T00:00:00Z`).toISOString().slice(0, 10) === s;
+export function planCommand(args, deps) {
+    const [verb, ...rest] = args;
+    switch (verb) {
+        case 'import': return planImport(rest, deps);
+        case 'move': return planMove(rest, deps);
+        case 'scope': return planScope(rest, deps);
+        case 'defer': return planDefer(rest, deps);
+        case 'set': return planSet(rest, deps);
+        case 'note': return planNote(rest, deps);
+        case 'history': return planHistory(rest, deps);
+        default: throw new RegisterError(PLAN_USAGE);
+    }
+}
+function planMove(args, deps) {
+    const { positional, opts } = flags(args, ['unassign']);
+    onlyOptions(opts, ['lane', 'unassign', 'reason'], PLAN_USAGE);
+    if (positional.length !== 2)
+        throw new RegisterError(PLAN_USAGE);
+    if ((opts.lane === undefined) === (opts.unassign === undefined) || opts.lane === 'true') {
+        throw new RegisterError(`Say where it goes, one of: --lane <id>   --unassign\n${PLAN_USAGE}`);
+    }
+    const reason = reasonFrom(opts, true);
+    const lead = asLead(deps);
+    const key = keyIn(lead.projectDir, positional[0], positional[1], PLAN_USAGE);
+    const lane = opts.lane !== undefined ? laneOrThrow(readLanes(lead.projectDir), opts.lane) : null;
+    const file = writePlan(lead, { action: 'assign', reason }, [{ key, lane: lane ? lane.id : null, reason }], deps);
+    deps.print(lane
+        ? `✓ Moved ${nameOf(key)} to ${lane.owner} (${lane.id}).`
+        : `✓ ${nameOf(key)} goes back to the lane patterns.`);
+    deps.print(writtenLine(file));
+    return 0;
+}
+function planScope(args, deps) {
+    const { positional, opts } = flags(args, ['out', 'in']);
+    onlyOptions(opts, ['package', 'out', 'in', 'reason'], PLAN_USAGE);
+    if ((opts.out === undefined) === (opts.in === undefined))
+        throw new RegisterError(`Say --out or --in.\n${PLAN_USAGE}`);
+    const inScope = opts.in !== undefined;
+    const byPackage = opts.package !== undefined;
+    if (byPackage ? positional.length || opts.package === 'true' : positional.length !== 2)
+        throw new RegisterError(PLAN_USAGE);
+    const reason = reasonFrom(opts, true);
+    const lead = asLead(deps);
+    let keys;
+    if (byPackage) {
+        keys = readBaseline(lead.projectDir).filter((o) => matches(opts.package, o.package)).map((o) => objectKey(o.type, o.name));
+        keys = [...new Set(keys)];
+        if (!keys.length)
+            throw new RegisterError(`No object of this team project is in package ${shown(opts.package)}.`);
+    }
+    else {
+        keys = [keyIn(lead.projectDir, positional[0], positional[1], PLAN_USAGE)];
+    }
+    const file = writePlan(lead, { action: 'scope', reason }, keys.map((key) => ({ key, inScope, reason })), deps);
+    const what = keys.length === 1 ? nameOf(keys[0]) : plural(keys.length, 'object', 'objects');
+    deps.print(inScope ? `✓ ${what} back in scope.` : `✓ ${what} taken out of scope. ${keys.length === 1 ? 'It stays' : 'They stay'} on the map, with the reason.`);
+    deps.print(writtenLine(file));
+    return 0;
+}
+function planDefer(args, deps) {
+    const { positional, opts } = flags(args);
+    onlyOptions(opts, ['reason'], PLAN_USAGE);
+    if (positional.length !== 2)
+        throw new RegisterError(PLAN_USAGE);
+    const reason = reasonFrom(opts, true);
+    const lead = asLead(deps);
+    const key = keyIn(lead.projectDir, positional[0], positional[1], PLAN_USAGE);
+    const file = writePlan(lead, { action: 'priority', reason }, [{ key, priority: 'defer', reason }], deps);
+    deps.print(`✓ ${nameOf(key)} deferred: it goes to the end of every working list.`);
+    deps.print(writtenLine(file));
+    return 0;
+}
+function planSet(args, deps) {
+    const { positional, opts } = flags(args);
+    onlyOptions(opts, ['priority', 'reason'], PLAN_USAGE);
+    if (positional.length !== 2)
+        throw new RegisterError(PLAN_USAGE);
+    const said = (opts.priority ?? '').trim().toLowerCase();
+    if (said !== 'clear' && !/^[1-5]$/.test(said))
+        throw new RegisterError('--priority is 1 to 5, or clear. 1 is done first.');
+    const reason = reasonFrom(opts, false);
+    const lead = asLead(deps);
+    const key = keyIn(lead.projectDir, positional[0], positional[1], PLAN_USAGE);
+    const priority = said === 'clear' ? null : Number(said);
+    const file = writePlan(lead, { action: 'priority', ...(reason ? { reason } : {}) }, [{ key, priority, ...(reason ? { reason } : {}) }], deps);
+    deps.print(priority === null
+        ? `✓ Priority of ${nameOf(key)} cleared: it follows the focus and the rules again.`
+        : `✓ Priority of ${nameOf(key)} set to ${priority}.`);
+    deps.print(writtenLine(file));
+    return 0;
+}
+function planNote(args, deps) {
+    const { positional, opts } = flags(args);
+    onlyOptions(opts, ['target', 'note'], PLAN_USAGE);
+    if (positional.length !== 2)
+        throw new RegisterError(PLAN_USAGE);
+    if (opts.target === undefined && opts.note === undefined)
+        throw new RegisterError(`Say --target 2026-11-30 or --note "<text>" (clear empties either).\n${PLAN_USAGE}`);
+    const row = {};
+    if (opts.target !== undefined) {
+        const t = opts.target.trim();
+        if (t.toLowerCase() === 'clear')
+            row.targetDate = '';
+        else if (isDay(t))
+            row.targetDate = t;
+        else
+            throw new RegisterError('--target is a day written 2026-11-30, or clear.');
+    }
+    if (opts.note !== undefined) {
+        if (opts.note === 'true')
+            throw new RegisterError('--note needs words, or clear.');
+        const n = opts.note.trim();
+        if (n.length > MAX_REASON)
+            throw new RegisterError(`Keep the note under ${MAX_REASON} characters.`);
+        row.note = n.toLowerCase() === 'clear' ? '' : n;
+    }
+    const lead = asLead(deps);
+    const key = keyIn(lead.projectDir, positional[0], positional[1], PLAN_USAGE);
+    const file = writePlan(lead, { action: 'note' }, [{ key, ...row }], deps);
+    deps.print(`✓ Plan note for ${nameOf(key)} recorded.`);
+    deps.print(writtenLine(file));
+    return 0;
+}
+const HISTORY_SHOWN = 50;
+function planHistory(args, deps) {
+    const { positional, opts } = flags(args);
+    onlyOptions(opts, ['object'], PLAN_USAGE);
+    const joined = joinedOrThrow();
+    const { register } = registerFor(joined.projectDir, joined.outboxDir);
+    let changes = register.plan.history;
+    if (opts.object !== undefined) {
+        if (opts.object === 'true' || positional.length !== 1)
+            throw new RegisterError(PLAN_USAGE);
+        const key = keyIn(joined.projectDir, opts.object, positional[0], PLAN_USAGE);
+        const all = changes;
+        changes = changes.filter((c) => c.keys.includes(key));
+        // A bulk change names its first 20 objects only, so "nothing" may not be the whole truth.
+        if (!changes.length && all.some((c) => c.more)) {
+            deps.print('Nothing has been re-planned for this object (bulk changes list their first 20 objects only).');
+            return 0;
+        }
+    }
+    else if (positional.length)
+        throw new RegisterError(PLAN_USAGE);
+    if (!changes.length) {
+        deps.print(NOTHING_REPLANNED);
+        return 0;
+    }
+    for (const c of changes.slice(0, HISTORY_SHOWN)) {
+        deps.print(`${dayMonth(c.at)} ${c.at.slice(11, 16)} UTC  ${c.by}: ${c.what}${c.why ? ` — because ${shownUpTo(c.why, MAX_REASON)}` : ''}`);
+    }
+    if (changes.length > HISTORY_SHOWN)
+        deps.print(`and ${changes.length - HISTORY_SHOWN} more`);
+    return 0;
+}
+// ── plan import ─────────────────────────────────────────────────────────────
+const IMPORT_USAGE = 'Usage: cspeach team plan import <file.xlsx> [--yes]';
+/** "1 priority, 0 moves, 1 scope change, 2 notes" — the four kinds of change, always all four. */
+const changeWords = (c) => [
+    plural(c.priorities, 'priority', 'priorities'), plural(c.moves, 'move', 'moves'),
+    plural(c.scope, 'scope change', 'scope changes'), plural(c.notes, 'note', 'notes'),
+].join(', ');
+/**
+ * Lead only (spec 2026-10-06 §8). Reads the Plan sheet of a workbook `team
+ * report` wrote, prints the diff, asks once, and writes ONE `excel` plan record
+ * with the accepted rows. Then the workbook and the status file are made again,
+ * so the lead sees the new export stamp. A workbook held open keeps the import:
+ * the record is written first, and one line says which file was not updated.
+ */
+async function planImport(args, deps) {
+    const { positional, opts } = flags(args, ['yes']);
+    onlyOptions(opts, ['yes'], IMPORT_USAGE);
+    if (positional.length !== 1)
+        throw new RegisterError(IMPORT_USAGE);
+    const lead = asLead(deps);
+    const fileName = path.basename(positional[0]);
+    let buffer;
+    try {
+        buffer = fs.readFileSync(path.resolve(positional[0]));
+    }
+    catch {
+        throw new RegisterError(`"${shown(fileName)}" could not be read. Check the file name.`);
+    }
+    const sheet = readPlanSheet(buffer);
+    // The plan now and the plan as the export saw it, both from the team project
+    // folder (the files report reads). Clashes also count this laptop's own records
+    // not handed in yet: a newer word of the lead's is still newer.
+    const folder = collectRecords(lead.projectDir).records;
+    const own = path.resolve(lead.outboxDir) !== path.resolve(lead.projectDir) ? collectRecords(lead.outboxDir).records : [];
+    const input = { project: lead.project, baseline: readBaseline(lead.projectDir), lanes: readLanes(lead.projectDir), progress: false };
+    const register = buildRegister({ ...input, records: folder });
+    const atOrBefore = (r) => {
+        const at = r?.at;
+        return typeof at === 'string' && at <= sheet.exportStamp;
+    };
+    const exported = buildRegister({ ...input, records: folder.filter(atOrBefore) });
+    const d = diffPlan(sheet, register, [...folder, ...own], { exported });
+    const c = d.counts;
+    deps.print(`${changeWords(c)}; ${plural(c.unchanged, 'row', 'rows')} unchanged; `
+        + `${plural(c.notInTeamProject, 'object', 'objects')} not in this team project; ${plural(c.clashes, 'clash', 'clashes')}`);
+    for (const x of d.clashes) {
+        deps.print(`  ${nameOf(x.key)} — ${x.field}: sheet says ${shown(x.sheet)}, now ${shown(x.now)} (set by ${shown(x.by)} at ${utcWords(x.at)}); skipped`);
+    }
+    for (const u of d.unknownLanes)
+        deps.print(`  ${nameOf(u.key)} — Lane: "${shown(u.lane)}" is not a lane in this team project; skipped`);
+    if (c.factEditsIgnored)
+        deps.print(`${plural(c.factEditsIgnored, 'edit in fact columns was', 'edits in fact columns were')} ignored.`);
+    if (c.unreadableCells) {
+        deps.print(c.unreadableCells === 1 ? '1 cell could not be read and was left as it is.'
+            : `${c.unreadableCells} cells could not be read and were left as they are.`);
+    }
+    if (c.blankCells) {
+        deps.print(c.blankCells === 1 ? '1 cell was left blank where a value is needed; nothing changed for it.'
+            : `${c.blankCells} cells were left blank where a value is needed; nothing changed for them.`);
+    }
+    if (!d.rows.length) {
+        deps.print('Nothing to import. Nothing was written.');
+        return 0;
+    }
+    if (opts.yes !== 'true') {
+        if (!deps.ask) {
+            deps.print(`Nothing was written. To import it: cspeach team plan import "${shown(fileName)}" --yes`);
+            return 0;
+        }
+        const answer = (await deps.ask('Import these changes? [y/n]')).trim().toLowerCase();
+        if (answer !== 'y' && answer !== 'yes') {
+            deps.print('Nothing was written.');
+            return 0;
+        }
+    }
+    const file = writePlan(lead, {
+        action: 'excel',
+        source: { file: fileName, sha256: createHash('sha256').update(buffer).digest('hex'), exportStamp: sheet.exportStamp },
+        clashesSkipped: c.clashes,
+        reason: `edited in the Plan sheet (${fileName})`.slice(0, MAX_REASON),
+    }, d.rows, deps);
+    deps.print(`✓ Imported from "${shown(fileName)}": ${changeWords(c)}.`);
+    deps.print(writtenLine(file));
+    // The record is kept whatever happens next; a failure here is one plain line, never a stack.
+    try {
+        const { saved, held } = writeReports(lead.projectDir, lead.project, path.join(lead.projectDir, 'reports'), deps);
+        if (saved.length)
+            deps.print(`✓ Saved ${saved.map((n) => `"${n}"`).join(' and ')} in the reports folder of the team project.`);
+        for (const name of held)
+            deps.print(heldReportLine(name));
+    }
+    catch {
+        deps.print('  ! The workbook and the status file could not be made again. The import is kept. Run cspeach team report for the reason.');
+    }
+    return 0;
+}