open/linkedin-studio
1
0
Fork 0
Code Issues Releases Activity

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

Browse source 
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
This commit is contained in:
Kjell Tore Guttormsen 2026-07-25 06:55:44 +02:00
commit 657539ef09
13 changed files with 1454 additions and 20 deletions
Download patch file Download diff file Expand all files Collapse all files

171
scripts/editions/src/cli.ts
View file

@ -1,18 +1,32 @@
#!/usr/bin/env node
/**
* CLI for the series distillate (N11 — serie-nivå-vern).
* CLI for series-level edition memory: the distillate (N11 — serie-nivå-vern)
* and the editions register (N12 — A1-11 / A1-12).
*
* node --import tsx src/cli.ts distil-append --distillate <path> --series <slug> --extract <extract.json>
* node --import tsx src/cli.ts distil-check --distillate <path> --skeleton <skeleton.json>
* [--threshold <0..1>] [--json]
* node --import tsx src/cli.ts distil-append --distillate <path> --series <slug> --extract <extract.json>
* node --import tsx src/cli.ts distil-check --distillate <path> --skeleton <skeleton.json>
* [--threshold <0..1>] [--json]
* node --import tsx src/cli.ts register-upsert --edition-state <path> [--next <text>] [--slot <text>]
* [--path <series-root>] [--register <path>] [--at <ISO>]
* node --import tsx src/cli.ts register-list [--all] [--json] [--register <path>] [--now <ISO>]
* node --import tsx src/cli.ts register-complete --series <slug> --edition <NN>
* [--register <path>] [--at <ISO>]
*
* `distil-append` runs at Step 8 lock: the command layer writes the AI extract
* (the anecdotes/arguments/hooks the edition actually spent) to a JSON file, and
* this folds it in deterministically. `distil-check` runs at Step 2.5, before
* prose, and reports re-use into the annotation gate.
*
* `register-upsert` runs at EVERY phase transition — it appends the `phaseLog`
* entry to the edition-state AND mirrors the row into the register in one call,
* so the telemetry cannot drift out of step with the state it describes.
* `register-complete` runs at Step 10 when the edition is scheduled.
*
* Clock at the edge only: `--at` / `--now` override it so runs are reproducible.
*
* Exit code: 0 on success (INCLUDING a REUSE verdict — the check is advisory by
* design, unlike the binding gate's BLOCK), 2 on usage error.
* design, unlike the binding gate's BLOCK), 1 on a failed operation, 2 on usage
* error.
*/
import { readFileSync } from "node:fs";
@ -24,7 +38,23 @@ import {
loadDistillate,
saveDistillate,
} from "./distillate.js";
import type { DistillateEntry, SkeletonCandidate } from "./types.js";
import {
appendPhase,
editionFacts,
readEditionState,
saveEditionState,
seriesRootFromStatePath,
} from "./editionState.js";
import {
completeEdition,
defaultRegisterPath,
elapsedDays,
listEditions,
loadRegister,
saveRegister,
upsertEdition,
} from "./register.js";
import type { DistillateEntry, EditionRow, SkeletonCandidate } from "./types.js";
function parseFlags(args: string[]): Record<string, string> {
const out: Record<string, string> = {};
@ -48,12 +78,22 @@ function usage(msg: string): never {
console.error(`error: ${msg}`);
console.error(
"usage:\n" +
" distil-append --distillate <path> --series <slug> --extract <extract.json>\n" +
" distil-check --distillate <path> --skeleton <skeleton.json> [--threshold <0..1>] [--json]",
" distil-append --distillate <path> --series <slug> --extract <extract.json>\n" +
" distil-check --distillate <path> --skeleton <skeleton.json> [--threshold <0..1>] [--json]\n" +
" register-upsert --edition-state <path> [--next <text>] [--slot <text>] [--path <series-root>]\n" +
" [--register <path>] [--at <ISO>]\n" +
" register-list [--all] [--json] [--register <path>] [--now <ISO>]\n" +
" register-complete --series <slug> --edition <NN> [--register <path>] [--at <ISO>]",
);
process.exit(2);
}
/** A failed operation (as opposed to a malformed invocation). */
function fail(msg: string): never {
console.error(`error: ${msg}`);
process.exit(1);
}
/** A flag that was given a real value (not absent, not a bare boolean flag). */
function value(flags: Record<string, string>, key: string): string | undefined {
const v = flags[key];
@ -92,6 +132,28 @@ function toEntry(raw: unknown): DistillateEntry {
};
}
/**
* One edition as the operator reads it: what it is, where it stands, what the
* one next move is, and how long it has been running. This block IS the WIP
* answer — if it needs a follow-up file to be useful, the register has failed.
*/
function renderRow(row: EditionRow, now: string): string {
const days = elapsedDays(row.startedAt, row.completedAt ?? now);
const age =
days === null
? "age unknown"
: row.status === "complete"
? `lead time ${days} day(s)`
: `${days} day(s) in flight`;
return (
`\n · ${row.series}/${row.editionId}${row.title ? ` — "${row.title}"` : ""}\n` +
` phase: ${row.currentPhase} → next: ${row.nextAction ?? "—"}\n` +
` ${age} · slot: ${row.slot ?? "—"}\n` +
` ${row.path}`
);
}
function main(): void {
const [command, ...rest] = process.argv.slice(2);
const flags = parseFlags(rest);
@ -161,6 +223,99 @@ function main(): void {
return;
}
if (command === "register-upsert") {
const statePath = value(flags, "edition-state");
if (!statePath) usage("register-upsert needs --edition-state <path>");
const at = value(flags, "at") ?? new Date().toISOString();
const registerPath = value(flags, "register") ?? defaultRegisterPath();
let state;
try {
state = readEditionState(statePath);
} catch (err) {
usage(`could not read edition-state at ${statePath}: ${(err as Error).message}`);
}
let facts;
try {
facts = editionFacts(state);
} catch (err) {
usage((err as Error).message);
}
// Log first, mirror second: the state file is the source of truth, and a
// register row for a transition that was never logged would be a lie.
const logged = appendPhase(state, facts.editionId, facts.currentPhase, at);
if (logged.appended) saveEditionState(statePath, logged.state);
const { register, row, created } = upsertEdition(
loadRegister(registerPath),
{
series: facts.series,
editionId: facts.editionId,
title: facts.title,
path: value(flags, "path") ?? seriesRootFromStatePath(statePath),
currentPhase: facts.currentPhase,
nextAction: value(flags, "next"),
slot: value(flags, "slot"),
},
at,
);
saveRegister(registerPath, register);
console.log(
`${created ? "Registered" : "Updated"} ${row.series}/${row.editionId} at phase ${row.currentPhase} ` +
`(${logged.appended ? "phase logged" : "phase already logged"}) — ${registerPath}`,
);
return;
}
if (command === "register-list") {
const registerPath = value(flags, "register") ?? defaultRegisterPath();
const includeComplete = flags.all === "true";
const now = value(flags, "now") ?? new Date().toISOString();
const rows = listEditions(loadRegister(registerPath), { includeComplete });
if (asJson) {
console.log(JSON.stringify(rows, null, 2));
return;
}
if (rows.length === 0) {
console.log(includeComplete ? "No editions in the register." : "No editions in flight.");
return;
}
console.log(
includeComplete
? `${rows.length} edition(s) in the register:`
: `${rows.length} edition(s) in flight:`,
);
for (const row of rows) console.log(renderRow(row, now));
return;
}
if (command === "register-complete") {
const series = value(flags, "series");
const editionId = value(flags, "edition");
if (!series || !editionId) usage("register-complete needs --series <slug> and --edition <NN>");
const at = value(flags, "at") ?? new Date().toISOString();
const registerPath = value(flags, "register") ?? defaultRegisterPath();
const { register, row } = completeEdition(loadRegister(registerPath), { series, editionId }, at);
if (!row) fail(`no register row for ${series}/${editionId} — nothing to complete`);
saveRegister(registerPath, register);
const lead = elapsedDays(row.startedAt, row.completedAt ?? at);
console.log(
`Completed ${row.series}/${row.editionId}` +
(lead === null ? "" : ` — lead time ${lead} day(s)`) +
` — ${registerPath}`,
);
return;
}
usage(command ? `unknown command: ${command}` : "no command given");
}