feat(linkedin-studio): N12 — editions-register CLI + phaseLog-telemetri (TDD) [skip-docs]

Two things were structurally invisible: WHICH editions are in flight (readable
only by opening every series folder's edition-state.json by hand) and HOW LONG an
edition takes (not recorded anywhere). At two editions a week both are
load-bearing — a production line cannot be dimensioned on numbers never collected.

Register (scripts/editions, new module beside distillate.ts): one row per edition
in ${LINKEDIN_STUDIO_DATA}/editions/register.json — series, edition, title, series
path, current phase, next action, slot, startedAt/completedAt. Data-dir placement
(M0) because the register spans ALL series; the distillate is per-series and stays
in the series root. Verbs: register-upsert / register-list / register-complete.

phaseLog: articles.NN.phaseLog[{phase, completedAt}] in edition-state, additive so
schemaVersion stays 1 — pre-N12 editions load unchanged and their absence reads as
"not measured", never as zero. Per-article, mirroring articles.NN.phase: lead time
is a property of an edition.

One call per transition, both writes: newsletter.md gains a phase-transition
protocol defined once beside the resumption table, and all 16 canonical phases
invoke it. register-upsert appends the phase-log entry AND mirrors the register
row. Deliberately one command, not two — telemetry the command layer must remember
to write separately is incomplete inside a week, and an incomplete log measures
nothing. Step 10 closes the row and prints the measured lead time.

Mirror discipline: resumption still reads edition-state.json and only that. Delete
the register and the next transition rebuilds it; a failed upsert is reported, never
a reason to stop the pipeline. startedAt is the one unrecoverable value, so it never
moves — re-upserting a completed edition reactivates the same row (what
/linkedin:pivot does), keeping the clock on real elapsed production time.

Deterministic: no clock in the core (now passed in, --at/--now at the edge, as the
distillate takes lockedAt). Idempotent where a re-run is legitimate (repeated
transition logs once; completing twice keeps the first completedAt), not where it is
real work (a phase recurring after another one is logged again — a pivot back through
cleared gates is production time that happened). Missing facts are refused at the
edge, not defaulted: a row naming the wrong phase is worse than no row.

TDD (Iron Law): all three test files written first and verified red before any
implementation existed (register.test.ts + editionState.test.ts failed on missing
modules, cli-register.test.ts on "unknown command: register-upsert").

Suites: editions 27 -> 72 (floor raised) · test-runner 173 -> 184 (Section 16s: 11
unconditional greps incl. a 16-phase coverage sweep + non-vacuity self-test;
anti-erosion floor 155 -> 166) · trends 300/0 · brain 134/0 · specifics-bank 45/0 ·
hooks 140/0 · tests 35/0 · render 60/0. tsc --noEmit clean.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QxvWAjte7vPcF79QeSRvRJ

scripts/editions/src/editionState.ts

@@ -0,0 +1,106 @@
+/**
+ * The edition-state side of the register (N12 — A1-12).
+ *
+ * Two jobs, both deterministic:
+ *   1. read the handful of facts the register mirrors (series, edition, title,
+ *      phase) — refusing to guess when any of them is missing;
+ *   2. append the `phaseLog` entry that makes lead time measurable.
+ *
+ * Why code and not the command layer: the phase log is only useful if it is
+ * complete, and "remember to append the right JSON object at all ~17 transitions"
+ * is exactly the discipline a model quietly drops mid-pipeline. One CLI call at
+ * each transition writes both the log and the register, or neither.
+ *
+ * The state file is read and written whole — this package touches `phaseLog` and
+ * nothing else. `edition-state.json` stays owned by /linkedin:newsletter.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+
+import type { EditionFacts, EditionStateFile, PhaseLogEntry } from "./types.js";
+
+/** Read the state file. A missing file throws — the register mirrors state, it never invents it. */
+export function readEditionState(path: string): EditionStateFile {
+  return JSON.parse(readFileSync(path, "utf8")) as EditionStateFile;
+}
+
+/** Write the state back, preserving everything this package did not touch. */
+export function saveEditionState(path: string, state: EditionStateFile): void {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify(state, null, 2) + "\n", "utf8");
+}
+
+/**
+ * Extract what the register mirrors. Every missing field is an error rather than
+ * a default: a row naming the wrong phase is worse than no row, because the
+ * whole point is that the operator trusts the list without opening files.
+ * The title is the one exception — it is telemetry, not a gate.
+ */
+export function editionFacts(state: EditionStateFile): EditionFacts {
+  const series = state.series?.slug;
+  if (typeof series !== "string" || series.trim().length === 0) {
+    throw new Error("edition-state is missing series.slug");
+  }
+
+  const editionId = state.currentArticle;
+  if (typeof editionId !== "string" || editionId.trim().length === 0) {
+    throw new Error("edition-state is missing currentArticle");
+  }
+
+  const article = state.articles?.[editionId];
+  if (!article || typeof article !== "object") {
+    throw new Error(`edition-state has no articles entry for currentArticle ${editionId}`);
+  }
+
+  const currentPhase = state.currentPhase;
+  if (typeof currentPhase !== "string" || currentPhase.trim().length === 0) {
+    throw new Error("edition-state is missing currentPhase");
+  }
+
+  return { series, editionId, title: typeof article.title === "string" ? article.title : "", currentPhase };
+}
+
+export interface AppendPhaseResult {
+  state: EditionStateFile;
+  /** false iff the same transition was already the newest entry. */
+  appended: boolean;
+}
+
+/**
+ * Append one completed phase to the article's log.
+ *
+ * Idempotent against an immediately repeated transition (a re-run of the same
+ * step), but NOT against a phase that recurs after another one: `/linkedin:pivot`
+ * legitimately sends an edition back through cleared gates, and that second pass
+ * is real production time — collapsing it would understate the lead time of
+ * exactly the editions that cost the most.
+ */
+export function appendPhase(
+  state: EditionStateFile,
+  editionId: string,
+  phase: string,
+  at: string,
+): AppendPhaseResult {
+  const article = state.articles?.[editionId];
+  if (!article || typeof article !== "object") {
+    throw new Error(`edition-state has no articles entry for ${editionId}`);
+  }
+
+  const log: PhaseLogEntry[] = Array.isArray(article.phaseLog) ? article.phaseLog : [];
+  article.phaseLog = log;
+
+  if (log.length > 0 && log[log.length - 1].phase === phase) return { state, appended: false };
+
+  log.push({ phase, completedAt: at });
+  return { state, appended: true };
+}
+
+/**
+ * Derive the series root from the conventional
+ * `<serie>/linkedin/edition-state.json` layout, so a transition does not have to
+ * repeat a path the state file's own location already carries.
+ */
+export function seriesRootFromStatePath(statePath: string): string {
+  return dirname(dirname(statePath));
+}