linkedin-studio/docs/fix2/slice2-binding.md

Fix #2 slice 2 — per-edition lived-specifics binding

Kilde-så-draft. Slice 1 built the global store (scripts/specifics-bank). Slice 2 builds the per-EDITION binding: the bridge that ties one edition's load-bearing claims to real material before any prose exists. Slice 3 wires it into /linkedin:newsletter (Step 1.5 + the skeleton-gate); slice 4 touches the maskinrommet contract. This doc is the design record slice 3 implements against.

Why (retning §3, drømme-spec «Lived-Specifics Extraction» [CORE])

Sourcing, not styling, is where authenticity is won. A draft that starts from the operator's real number / named case / what-actually-broke is forwardable; a draft that invents plausible filler is hollow, and every downstream voice gate then polishes hollow content. So before prose, each load-bearing claim of an edition must be bound to real inventory — or the operator must consciously decide it does not need a concrete instance. The binding is that ledger; vagueness is rejected.

The slot-map (articles.NN.livedSpecifics in edition-state.json)

A per-article field, resolved at Step 1.5 (between brief and research). Each slot is one load-bearing key-point (kind: "key-point") or, after the skeleton exists, a section (kind: "section" — the same shape serves both, no migration):

"livedSpecifics": {
  "slots": [
    { "slotId": "kp1", "kind": "key-point", "label": "<claim>",
      "binding": { "type": "specific", "specificId": "<bank id>" } },
    { "slotId": "kp2", "kind": "key-point", "label": "<claim>",
      "binding": { "type": "abstrakt", "rationale": "<why abstract here>" } },
    { "slotId": "kp3", "kind": "key-point", "label": "<claim>",
      "binding": { "type": "ekstern", "source": "<research ref, optional>" } },
    { "slotId": "kp4", "kind": "key-point", "label": "<claim>",
      "binding": { "type": "unresolved" } }
  ],
  "status": "pending"   // pending → bound (set by the command when the gate passes)
}

The gate — validateBinding(livedSpecifics, bank) (drømme-spec G4, «vaghet avvises»)

Deterministic, pure (scripts/specifics-bank/src/binding.ts). BLOCK iff any slot:

reason	when
unresolved	binding type is unresolved — the vagueness the gate exists to reject
dangling-specific	a specific binding points at a specificId absent from the bank
unjustified-abstrakt	an abstrakt escape with a blank rationale (= vagueness wearing an escape hatch)

Otherwise PASS. Escape hatches are legitimate: abstrakt (with a rationale) and ekstern (research-backed, not lived; source optional — Step 2 fills it).

WARN (does not block) — regel 6/7: a slot backed by an unverified number specific surfaces as unverified-number. Numbers stay guilty-until-checked; Step 2 research must verify them before the draft asserts them as fact.

coverage counts by binding TYPE (total / specific / abstrakt / ekstern / unresolved); a dangling specific still counts under specific (the binding type is specific, the problem is separately reported). Empty slot-map → PASS, total 0 — whether an edition needs ≥1 slot is the command layer's call (slice 3).

The NN-kilder.md artifact

Read-only, deterministically rendered from livedSpecifics + the bank (scripts/specifics-bank/src/kilder.ts, renderKilder) — regenerated like POST.html, never hand-edited. Lives at <serie>/linkedin/NN-kilder.md. Per load-bearing slot: binding type, the material (KTG's words, verbatim), provenance

• capture date, topic tags, and the number-verification marker (✓ / ⚠); then a coverage block + a «Tall som må verifiseres (regel 6/7)» line. The coverage block and the number list are computed by validateBinding, so the artifact and the skeleton-gate can never disagree. (Golden-tested; pure + dateless on purpose.)

CLI surface (the seam slice 3 calls)

Run from the package dir (tsx lives there); pass absolute paths:

cd "${CLAUDE_PLUGIN_ROOT}/scripts/specifics-bank"
node --import tsx src/cli.ts validate-binding --edition "<abs>/linkedin/edition-state.json"   # exit 1 = BLOCK
node --import tsx src/cli.ts render-kilder    --edition "<abs>/linkedin/edition-state.json" \
                                              --out     "<abs>/linkedin/NN-kilder.md"

--article <id> overrides currentArticle; --bank <path> overrides the default data-dir bank; --json emits machine output for validate-binding. A missing livedSpecifics field is treated as an empty slot-map (back-compat with older editions / the template default).

Step 2 (research) re-scope spec — for slice 3 to wire

Today Step 2 decomposes the edition's key points into scoped research sub-questions and triangulates verified notes. Once Step 1.5 + the slot-map exist, Step 2 is scoped by the binding rather than by the raw key-points:

1. Fill the gaps, don't re-research the grounded. Research targets slots bound ekstern (and any still unresolved at entry) — the claims that explicitly need an external source. Slots bound to a specific are already grounded in lived material and do not need their substance re-sourced (research may still corroborate, but it is not the gap).
2. Verify KTG's own numbers (regel 6/7). Every unverified-number warning from validateBinding is a research target: confirm the operator's own figure against a primary source where possible, then flip the bank specific unverified → verified (cli.ts add/a verify path). A number that cannot be verified stays unverified and is carried to the Step 5 fact-check sweep as 🟡 — never silently asserted.
3. Re-render after research. When research resolves an ekstern source or a number flips to verified, regenerate NN-kilder.md so the ledger stays current.

Boundary: slice 2 ships the data model, the gate, the artifact renderer, and the CLI. Slice 3 adds Step 1.5 (the elicitation interview + add to the bank + populating the slot-map), wires validate-binding into the Step 2.5 skeleton-gate, applies this Step 2 re-scope, and bumps the pipeline 17 → 18 phases.

Tests & verification

cd scripts/specifics-bank && npm test (binding + kilder suites) and npm run build (tsc) stay clean. The gate's three BLOCK reasons + the number WARN + the golden NN-kilder.md render are all covered.