linkedin-studio/config/edition-state.template.json

{
  "_doc": {
    "purpose": "Schema for edition-state.json — deterministic resumption state for a newsletter edition in production. Holds the current phase + per-article status so /linkedin:newsletter (Step 0) can resume exactly where a prior session stopped.",
    "decision": "G — production state lives in the series folder (e.g. $LTL_SERIES_ROOT/<slug>/linkedin/edition-state.json, default $HOME/linkedin-series/<slug>/...), NOT in the plugin. This file is the schema-defining TEMPLATE only; copy + fill it in the series folder when producing an edition.",
    "complements": "edition-config.json (static: calendar, freshness, captions) and <serie>/STATE.md (human-readable narrative state, overwritten each phase per the ONE-system continuity rule — there is no edition-HANDOVER.md). edition-state.json is the machine-readable companion: deterministic resumption + the durable fact-check log, immutable rules, and persona verdicts that the old HANDOVER §4/§5 used to carry.",
    "lifecycle": "/linkedin:newsletter reads this in Step 0 and rewrites it at every phase transition. Article keys mirror edition-config.json (zero-padded strings: \"01\", \"02\", ..., or \"samle\").",
    "phases": [
      "load-context — read <serie>/STATE.md, voice profile, persona library, series brief (Step 0)",
      "brief-calibration — angle, voice, audience personas, key points, leader-takeaway (Step 1)",
      "lived-specifics — elicitation interview (3–5 sharp questions, vagueness refused) → add lived material to the specifics-bank + populate articles.NN.livedSpecifics slot-map (each load-bearing key-point bound specific/abstrakt/ekstern/unresolved) → render NN-kilder.md; BETWEEN brief (Step 1) and research (Step 2). The grounded-sourcing layer (Fix #2, kilde-så-draft; never fabricated — invariant 3). The BLOCKing «vaghet avvises» gate (validateBinding) is enforced at the Step 2.5 skeleton-gate (Step 1.5)",
      "research — parallel scoped mandates → verified notes, triangulation; scoped BY the binding (fills ekstern/unresolved slots + verifies the operator's own numbers, regel 6/7) (Step 2)",
      "skeleton-pitch — five-line skeleton (premise/problem/recommendation/payoff/forward) + section pitches, operator gate + persona-skjelett-sweep BEFORE prose (Step 2.5)",
      "spine-prose — one paragraph per section against the gated skeleton, operator gate BEFORE full expansion (Step 3a)",
      "draft — full prose expansion against the gated spine; may span sessions (Step 3b)",
      "consistency-quality — threads, premise→conclusion arc, AI-slop removal, formatting dose (Step 4)",
      "contract-gate — deterministic §B/§C1 rule-gate over the draft (scripts/contract-gate, rules.ts), bound 1:1 to the maskinrommet skrivekontrakt §E-manifest via ratify; mechanical violations die here before the AI sweeps (Step 4.5)",
      "factcheck-sweep — risk-sorted, guilty-until-disproven, verification log (Step 5)",
      "editorial-review — editor's craft gate: prose-craft (em-dash density, verbatim repetition, postulated numbers, contradictions, versal-tic) + narrative-architecture (concrete instantiation, theory-anchored hypotheses, series-title symmetry, equal action per addressee, un-overloaded conclusion), ≤10 flags BLOCK/REWORK/NICE, operator-gated via SendUserFile BEFORE the persona sweep (Step 5.5)",
      "persona-sweep-prelock — reader jury, primary wins, convergence to clean YES (Step 6)",
      "headless-review — adversarial review package run COLD on a FROZEN draft (no drafting-session context): content-reviewer (argument integrity) + language-reviewer (Norwegian language) + fact-reviewer (cold re-verification incl. pivot premises) + persona-reviewer in resonance & conversion modes. Fan-out from Step 6.5 or the standalone /linkedin:headless-review command; consolidated report operator-gated via SendUserFile BEFORE lock (Step 6.5)",
      "annotation — optional annotatable review HTML for a manual pass (Step 7)",
      "visual-assets — cover (+ optional inline figures) or carousel deck: brief → generate → operator-gate → approve, BEFORE lock so build-linkedin.mjs picks them up (Step 7.5)",
      "lock-delivery — LOCK → POST.html all-in-one-place deliverable (Step 8)",
      "hook-conversion-gate — persona gate on distribution text post-lock: hook-forge, would YOU click?, and who forwards this and why (Step 9)",
      "scheduling — register edition in plugin queue/state for native LinkedIn scheduling (Step 10)",
      "retro — close the loop (≤5 min, AFTER scheduling): promote the pending articles.NN.foldIns with an explicit operator JA/NEI (mechanical → a contract-gate rule; judgment → the language-rules file / craft checklist), summarize the MEASURED effort from articles.NN.phaseLog, and ask ONE process-friction question. The corrections made in this edition become enforced before the next one starts (Step 11)"
    ],
    "articleStatusValues": ["pending", "in-progress", "locked", "scheduled"],
    "phaseLog": "Per-article phase-transition log (N12 / A1-12) — the raw material for measuring lead time. Additive-optional (default [], NO schemaVersion bump — same pattern as sourceTrendId/targetLevel/language; an edition produced before N12 simply has none and the register treats its absence as \"not measured\"). Shape: [ { phase, completedAt } ] in transition order, where phase is one of the canonical _doc.phases identifiers and completedAt is an ISO-8601 timestamp. Written DETERMINISTICALLY, never by hand: every /linkedin:newsletter phase transition runs `scripts/editions` (`node --import tsx src/cli.ts register-upsert --edition-state <path>`), which appends the entry for the just-written currentPhase AND mirrors the edition into the editions register (${LINKEDIN_STUDIO_DATA}/editions/register.json) in one call — the log and the register cannot drift apart because nothing writes one without the other. Idempotent against an immediately repeated transition (a re-run of the same step logs once), but a phase that recurs AFTER another one is logged again: /linkedin:pivot legitimately sends an edition back through cleared gates, and that second pass is real production time. Per-article rather than top-level because lead time is a property of an edition, mirroring articles.NN.phase. The register is a MIRROR of this file, never a source of truth — losing it costs telemetry, not an edition.",
    "editorialReview": "Per-article editorial-review record written by Step 5.5 (editorial-review phase). Runs AFTER fact-check (Step 5) and BEFORE the persona sweep (Step 6): the editorial-reviewer agent judges CRAFT (prose-craft + narrative-architecture), not reader-response, mirroring the Maskinrommet skrivekontrakt §C2. The report (≤10 flags, each with kategori P1–P5/A1–A5, quote/line-ref, direction, severity BLOCK/REWORK/NICE) is surfaced to the operator via SendUserFile; the operator decides which flags fold in. Shape: { reportPath, flagCount, byAxis: { prosa, arkitektur }, bySeverity: { block, rework, nice }, foldedIn, waived, status }. status ladder: pending → reviewed → folded. null until Step 5.5 runs. This is the craft companion to factcheckLog (truth) and personaSweep (response).",
    "visualAssets": "Per-article visual-asset record written by Step 7.5 (visual-assets phase). Runs BEFORE lock because render/build-linkedin.mjs picks up linkedin/NN/cover.png + the edition-config credit/caption when it builds POST.html — generating images after lock would force a re-render. Shape: { format: \"standard\" | \"carousel\"; cover: { brief, route, candidates[], approved, status }; figures: [ { id, brief, placement, status } ]; carousel: null | { source, pdf, status } }. format \"standard\" = cover + optional inline figures (cover.png is mandatory per the KTG cover-directive); format \"carousel\" = typografisk deck via render/build-carousel.mjs instead of cover+inline (cover/figures stay empty). route: \"mcp-image\" (default, via mcp__mcp-image__generate_image) | \"external\" (DALL·E / Midjourney / photographer → linkedin/NN/cover-raw.png). status ladder: pending → briefed → generated → approved. candidates[] holds the cover-v<N>-kandidat.png attempts; approved is the fixed approved name (\"cover.png\") once the operator-gate passes. figures[].id = \"fig1\"..; placement = section reference in NN-utkast.md (figures are referenced in the draft via ![alt](linkedin/NN/figN.png) and uploaded manually in the LinkedIn editor — build-linkedin.mjs does NOT embed them). Naming convention: cover.png (approved, fixed — what build-linkedin.mjs reads) | cover-v<N>-kandidat.png (attempts) | cover-raw.png (optional external pre-edit source) | fig<N>.png (inline). credit + caption are recorded in <serie>/linkedin/image-credit-caption.md and flow into edition-config.json coverCredit + captions[NN].",
    "livedSpecifics": "Per-article lived-specifics binding (Fix #2 slice 2, kilde-så-draft). A slot-map binding each LOAD-BEARING key-point (or, later, section) of this edition to either a real specific from the specifics-bank OR an explicit escape decision — so a draft starts grounded in the operator's real material instead of inventing plausible filler. Resolved at Step 1.5 (lived-specifics extraction, BETWEEN brief (Step 1) and research (Step 2); wired in slice 3) via a guided interview that REFUSES vague answers. THE GATE (drømme-spec G4, «vaghet avvises», enforced at the Step 2.5 skeleton-gate): every slot must resolve to \"specific\" (grounded), \"abstrakt\" (deliberately abstract here, with a rationale), or \"ekstern\" (backed by research, not lived material) — a slot left \"unresolved\" is the vagueness that BLOCKs. Numbers stay guilty-until-checked: a slot backed by an UNVERIFIED number is allowed but WARNED (regel 6/7), so Step 2 research verifies it before the draft asserts it. The deterministic validator + the rendered NN-kilder.md artifact live in scripts/specifics-bank (binding.ts/kilder.ts; `node --import tsx src/cli.ts validate-binding|render-kilder --edition <edition-state.json>`). Shape: { slots: [ { slotId, kind: \"key-point\" | \"section\", label, binding: ({ type: \"specific\", specificId } | { type: \"abstrakt\", rationale } | { type: \"ekstern\", source? } | { type: \"unresolved\" }) } ], status: \"pending\" | \"bound\" }. Default { slots: [], status: \"pending\" }: populated on first Step 1.5. Companion artifact: <serie>/linkedin/NN-kilder.md, rendered from this + the bank (regenerated, never hand-edited). This is the per-edition consumer of the global specifics-bank.",
    "personas": "Per-article resolved reader-persona set (input config), written/confirmed in Step 1. This makes personas configurable PER ARTIFACT, not just from one global plugin library: Step 1 resolves them in order — (1) already present here → use as-is; (2) <serie>/linkedin/personas.md (per-series file) → load; (3) plugin config/personas.local.md (or personas.template.md) library → select a subset; (4) none/insufficient → DEFINE interactively via AskUserQuestion. Exactly one entry has tier \"primær\" (the rest \"sekundær\"); «primær trumfer» on conflict. This set feeds BOTH the in-session sweep (Step 6) and the headless package (Step 6.5 / persona-reviewer). Each entry: { name, tier: \"primær\" | \"sekundær\", rolle, avkobler, overbeviser, ekspertise, sjargong, source: \"edition-state\" | \"series-file\" | \"plugin-library\" | \"interactive\" }. Default []: resolved on first Step 1.",
    "personaSweep": "Per-article reader-persona verdicts — one key per sweep point, all written by persona-reviewer. skeleton: the sweep on the five-line skeleton BEFORE prose (Step 2.5), so a premise that does not land is caught while a rewrite is still cheap. resonance: the pre-lock sweep on the full draft (Step 6), including the recorded wordCount that /linkedin:pivot's >20 % heuristic compares a later draft against. conversion: the post-lock «would YOU click?» verdict on the chosen hook (Step 9, primær persona, konverter mode). deling: the post-lock shareability verdict (N24, Step 9 — the second binary next to conversion): «who forwards this to a colleague, and why», plus which action the edition actually earns — RESHARE | SAVE | SEND. A plausible answer must name a ROLE the reader could point at AND a sender-motive (signals their judgment / saves a colleague a decision / settles a running argument); «useful for anyone in tech» names nobody and is a NEI. Shape of deling: { verdict: \"JA\" | \"NEI\", role, motive, action: \"RESHARE\" | \"SAVE\" | \"SEND\", operatorDecision? }. Two failed re-framings → a recorded operator decision (/linkedin:pivot, or ship + an articles.NN.foldIns row for the Step 11 retro) — there is never a silent pass, and the gate is never resolved by re-reading the same copy more generously. All four keys additive-optional (default null, NO schemaVersion bump — an edition produced before the step that writes one simply has none).",
    "hookForge": "Per-article hook-forge record written by Step 9 (hook-conversion-gate, N24). Additive-optional (default null, NO schemaVersion bump — same pattern as phaseLog/retro; an edition produced before N24 simply has none). The hook competes against alternatives instead of shipping the one the draft happened to end on: 5–8 variants are forged for the distribution copy (the body stays locked, as everywhere in this step). The 110–140-character band is enforced PER VARIANT and MEASURED — `perl -CSD -ne 'chomp; printf \"%d\\n\", length($_)'`, never `awk length`/`wc -c`, which count BYTES and over-report on æ/ø/å. A variant outside the band is DISQUALIFIED, not ranked lower (a cutoff, not a preference). The surviving set must span ≥3 hook types, or it is a set of rewrites and the operator has no real choice; every variant must trace to a claim the body actually makes (no bait hook — an unearned promise is what the randsone fact gate exists to catch). Fewer than five survivors ⇒ forge again. Shape: { variants: [ { text, measuredChars, hookType, bodyTrace, disqualified: null | \"band\" | \"body-trace\" } ], typesSpanned, chosen, chosenAt }. NO PREDICTED SCORE: a variant carries only its measured length, its hook type and its body trace. A predicted-engagement ranking would be a fabricated composite — exactly the class removed in N22 — and a ranked list only LOOKS more helpful. The ranking is the operator's; the plugin does not rank what it cannot measure.",
    "randsoneGate": "Per-article randsone-gate record written by Step 9 (hook-conversion-gate, N9). Additive-optional (default null, NO schemaVersion bump). The «randsone» is the distribution copy AROUND a locked edition — delingstekst hook, samle post, carousel slide text, edition title — text that ships with the edition but never passed the body's fact and language gates. Two scoped reviewers judge it (fact-reviewer F1/F3, language-reviewer L1/L2), plus a title-strength verdict on the distribution title. The gate NEVER reopens the locked body: a 🔴 that traces to the body (or a canonical-title weakness) is a pivot finding — STOP and run /linkedin:pivot; everything else is fixed in the distribution copy and re-checked. The chosen hook-forge variant goes THROUGH this gate, never around it. Shape: { surfaces: [ { surface, factVerdict, languageVerdict, revised } ], titleStrength, pivotTriggered, resolvedAt }.",
    "headlessReview": "Per-article headless-review record written by Step 6.5 (headless-review phase). Runs AFTER the in-session persona sweep (Step 6) and BEFORE lock (Step 8), on a FROZEN snapshot of the publish-ready (or pivoted) draft, fanned out from the command layer (foreground) or invoked standalone via /linkedin:headless-review in a fresh/cold session. Five archetypes judge independently with NO drafting-session context: content-reviewer (argument integrity), language-reviewer (Norwegian language), fact-reviewer (cold re-verification incl. claims a late pivot bolted on), persona-reviewer mode=resonans (per active persona), persona-reviewer mode=konverter (primær, hook only). The consolidated report is surfaced to the operator via SendUserFile; the operator decides which flags fold in. Shape: { frozenDraft, reviewers: { content, language, fact, personaResonance, personaConversion } (each { reportPath, summary, status }), consolidatedReport, foldedIn, waived, status }. status ladder: pending → run → folded. null until Step 6.5 runs. This is the adversarial-independence companion to the in-session gates (editorialReview, personaSweep, factcheckLog) — deliberately redundant: a cold reader catches what the framing-biased in-session pass missed.",
    "pivots": "Per-article pivot log (Endring 9c). A pivot is a substantive change to a draft AFTER a gate had already cleared — e.g. a new argument anchor / section added late (the Del 4 Security Champions case: +~530 words, 2 new sections, +42 %). Each /linkedin:pivot invocation appends one entry and moves currentPhase back so the cleared gates (Steps 5–6.5) re-run on the pivoted version before lock. Heuristic (documented, checked at the Step 8 lock precondition): if the current draft's word count differs > 20 % from the version that last cleared Step 6, OR it has > 2 new sections, a pivot-reopen is suggested/required. Each entry: { timestamp, reason, fromPhase, toPhase, wordCountBefore, wordCountAfter, deltaPct, newSections, gatesToRerun: [phase…] }. Default [].",
    "foldIns": "Per-article accumulation queue (slice 2 of fix #1 — «rettelser fester seg»). Each correction the operator makes during an edition that is NOT yet a contract rule is captured here, then routed by the JA-promoter (maskinrommet/docs/skrivekontrakt.md §E) to a permanent home so it never has to be re-discovered: a MECHANICAL correction → a rules.ts gate rule (BLOCK/WARN) + a §B-row/§C1/§C2-box + a §E-manifest row (the contract-gate `ratify` check then asserts rules.ts ↔ §E-manifest stay in bijection); a JUDGMENT correction → a §C2-box only (stays with editorial-reviewer, no gate rule). Capture is per-article (provenance = which article surfaced it); promotion is series/contract-wide. Each entry: { id, date (ISO-8601), correction (what the operator corrected, near-verbatim), trigger (where/why it surfaced), classification: \"mechanical-block\" | \"mechanical-warn\" | \"judgment\" | null (set at the classify step), decision: \"pending\" | \"promoted\" | \"rejected\" (the JA-promoter outcome), ruleId: <rules.ts id> | null (set on promote for mechanical), note?: where a judgment/rejected fold-in landed }. Default []. Rejected fold-ins are kept for traceability, never deleted.",
    "retro": "Per-article retro record written by Step 11 (retro phase), the step that makes a correction STICK. Additive-optional (default null, NO schemaVersion bump — same pattern as phaseLog/sourceTrendId/targetLevel; an edition produced before N14 simply has none). Runs AFTER scheduling (Step 10) because the retro is about the NEXT edition, not this one's delivery. Three jobs, all recorded here: (1) fold-in promotion — every articles.NN.foldIns row with decision \"pending\" gets an explicit operator JA/NEI; JA on a mechanical correction promotes it atomically to a scripts/contract-gate rule (rules.ts + contract row + manifest row, `--ratify` green or the promotion does not count), JA on a judgment correction appends it to the user language-rules file (${LINKEDIN_STUDIO_DATA}/language-rules/<lang>.md) or the craft checklist; NEI marks the row \"rejected\" and KEEPS it. (2) effort summary — read from the MEASURED articles.NN.phaseLog (N12), never re-estimated: number of transitions, phases that recurred (a re-run gate), and the elapsed lead time. (3) ONE process-friction question, whose answer is handed BACK to the operator — the plugin never writes the operator's own notes/register. Shape: { promoted, rejected, ruleIds: [<rules.ts id>…], languageRulesAppended, effort: { transitions, recurredPhases: [phase…], leadTimeDays }, frictionNoted: boolean, completedAt }. The full loop (capture → classify → promote → enforce) is documented domain-generally in references/fold-in-loop.md.",
    "language": "Review language for this series/edition (additive, default \"en\"). Threads into the long-form review agents so they grade against THIS language's rules: language-reviewer applies Norwegian-specific checks (anglicism→Norwegian idiom, «kanselli-stil») only when language == \"no\"; voice-scrubber's gold standard is the approved editions IN this language; any other value → the agents apply that language's equivalents and never grade prose against Norwegian idiom. \"no\" = Norwegian (the author's case). Resolved at Step 1 / load-context and passed to the language-dependent agents.",
    "sourceTrendId": "Per-article provenance link to the trend this edition was started from (N7 trend→newsletter bridge, MR-F3). Additive-optional (default null, NO schemaVersion bump — an edition started manually never sets it, and Step 10 reads its absence as \"no source trend\"). Set at the Step 1.5 checkpoint when Step 1's trend-intake read a candidate from the trends store (scripts/trends) to prefill the brief (angle / targetLevel / key-points / source-URLs). Its ONE runtime consumer is Step 10 (scheduling): when the article reaches scheduling AND sourceTrendId is set, the command flips that trend's store status to \"acted\" (trends CLI `act --id <sourceTrendId>`), closing the discovery→production loop deterministically instead of by hand. Value = the trend's store id (normalized title+url, as shown in the /linkedin:trends brief and `CLI list --json`).",
    "targetLevel": "Per-article target-level for the edition (N10 / C-8). Additive-optional (default null, NO schemaVersion bump — same pattern as sourceTrendId/language; an edition that never resolves one leaves it null and the reader agents fall back to each persona's own `ekspertise` field). Fixes WHERE this edition sits on the configured target-level span (references/longform-quality-rules.md + config/personas.template.md): it tells persona-reviewer which end is the reader-facing (primær) end and which is the mandatory-secondary end, so «practically usable at all levels» is judged from both ends rather than one baked-in reader role. Set at Step 1 of /linkedin:newsletter — the N7 trend bridge / N6 proposal layer pre-fills it from the trend record's `targetLevel` (scripts/trends), the operator confirms or edits it during calibration, and it is persisted here at the Step 1.5 checkpoint (alongside sourceTrendId). Free-text level descriptor (e.g. \"line leader → solution engineer\", \"beginner → practitioner\"), NOT an enum — the span is domain-general and defined by the operator's persona set, never hardcoded."
  },
  "schemaVersion": 1,
  "series": {
    "slug": "<series-slug>",
    "title": "<Series title>"
  },
  "language": "en",
  "currentArticle": "01",
  "currentPhase": "load-context",
  "updatedAt": "<ISO-8601 timestamp>",
  "articles": {
    "01": {
      "title": "<Article 1 title>",
      "phase": "load-context",
      "status": "pending",
      "phaseLog": [],
      "personas": [],
      "livedSpecifics": {
        "slots": [],
        "status": "pending"
      },
      "immutableRules": null,
      "factcheckLog": null,
      "editorialReview": null,
      "personaSweep": {
        "skeleton": null,
        "resonance": null,
        "conversion": null,
        "deling": null
      },
      "headlessReview": {
        "frozenDraft": null,
        "reviewers": {
          "content": null,
          "language": null,
          "fact": null,
          "personaResonance": null,
          "personaConversion": null
        },
        "consolidatedReport": null,
        "foldedIn": null,
        "waived": null,
        "status": "pending"
      },
      "visualAssets": {
        "format": "standard",
        "cover": {
          "brief": null,
          "route": null,
          "candidates": [],
          "approved": null,
          "status": "pending"
        },
        "figures": [],
        "carousel": null
      },
      "hookForge": null,
      "randsoneGate": null,
      "pivots": [],
      "foldIns": [],
      "retro": null,
      "locked": false,
      "scheduled": null,
      "sourceTrendId": null,
      "targetLevel": null
    }
  }
}