ktg-plugin-marketplace/plugins/linkedin-studio/docs/voyage-build/dogfood-S13-friction.md

Dogfood S13 — friction log (/linkedin:newsletter end-to-end)

Step 14 (fasit S13) deliverable. A real end-to-end dogfood of the long-form pipeline against a throwaway fixture (operator decision 2026-05-27: throwaway fixture in docs/review/ scope, synthetic topic, no cross-repo write to maskinrommet). The fixture series lives at docs/review/dogfood-serie/ (gitignored — throwaway, not committed). This log is the only committed artifact.

This is a design-friction log, not a content-quality review. Per plan Step 14 "On failure: escalate — capture friction in the log, do not force a green check." The pipeline's deterministic backbone (render scripts, edition-state, queue) was executed for real; the gate layer (fact-check, persona sweep) is BLOCKED (see F1/F2) and its verdicts were not fabricated.

---

Order-proof (the headline assertion this step must record)

The persona sweep is wired to run FØR lås / before lock, exactly as fasit §0.4 mandates. Verified structurally (gate execution itself is blocked by F1/F2, so the proof is at the wiring level, not a live JA):

1. config/edition-state.template.json → _doc.phases orders the phases consistency-quality → factcheck-sweep → persona-sweep-prelock → annotation → lock-delivery. persona-sweep-prelock (Step 6) precedes lock-delivery (Step 8) in the canonical phase list.
2. commands/newsletter.md Step 6 and Step 8 each carry an explicit "Order assertion (enforced)" block stating the pipeline may not reach lock until the primær persona returns a clean JA from the pre-lock sweep.
3. The fixture linkedin/edition-HANDOVER.md physically records §5 persona-sweep (BEFORE lock) above §lås, and edition-state.json currentPhase never advances to lock-delivery because the persona JA precondition is unmet.

So the before-lock ordering holds in the wiring. What the dogfood could not do is execute the gate — because of F1/F2 below.

---

Friction points (numbered; ordered by severity)

F1 — [BLOCKER] Agents invoked by bare name; harness requires namespace

What: commands/newsletter.md issues every Task fan-out by bare agent name — subagent_type: fact-checker (Step 5), persona-reviewer (Steps 6, 9), and content-repurposer (Step 3). The Claude Code harness registers plugin agents namespaced as linkedin-thought-leadership:<name>. A bare name does not resolve. Evidence: Live test this session — Task(subagent_type: "content-repurposer") returned Agent type 'content-repurposer' not found, with the available list showing only linkedin-thought-leadership:content-repurposer. Same failure for fact-checker and persona-reviewer. Impact: Steps 3, 5, 6, 9 — the entire gate/draft fan-out machinery — fail as written. This is the core of the long-form pipeline. Implicates: commands/newsletter.md (lines ~299, 398–399, 467–469, 638) → Step 15 fix: namespace all subagent_type references to linkedin-thought-leadership:<name> (or confirm the intended invocation form and align the command to it).

F2 — [BLOCKER / ENV] fact-checker + persona-reviewer not registered this session

What: Even namespaced, neither fact-checker nor persona-reviewer appears in the harness's available-agents list, while every other LTL agent (incl. content-repurposer) does. The two agents were added in S4/S5 (commits be03d44, 1faffac) after the running session's plugin agent registry was built. Evidence: Available list this session contains linkedin-thought-leadership:content-repurposer etc. but not …:fact-checker or …:persona-reviewer. Their frontmatter is well-formed and structurally identical to content-repurposer (verified name/description/model/color/ tools) — so this is not a frontmatter defect; it is a registry/reload gap. Impact: Compounds F1 — even after namespacing, Steps 5/6/9 cannot run until the session reloads the plugin agent set. Implicates: environment (Claude Code reload to register new agents) + doc fix: note in CLAUDE.md/README.md that adding a plugin agent requires a session reload before it is invokable. Not a code defect in the agent files.

F3 — [MAJOR] No template for 3 of the 4 series-folder input artifacts

What: The pipeline depends on four artifacts in the series folder: edition-state.json, edition-config.json, edition-delingstekst.md, and the edition-HANDOVER.md. Only edition-state.json ships a template (config/edition-state.template.json). The formats of edition-config.json and edition-delingstekst.md are discoverable only by reading the render scripts. Evidence: To run the dogfood I had to reverse-engineer both formats from render/build-linkedin.mjs (loadEditionConfig shape; parseDelingstekst section grammar ## Del N — / ## Samle, **Første kommentar:**, #hashtag line). A new operator has no shipped reference. Impact: Step 8 says "confirm the delivery inputs exist" with no generation path — a fresh edition cannot produce these from anything the plugin ships. Implicates: config/ (add edition-config.template.json + edition-delingstekst.template.md + an edition-HANDOVER.template.md) and commands/newsletter.md Step 8 (point at the templates) → Step 15 fix.

F4 — [MAJOR] Draft filename/location is inconsistent across steps

What: Step 3 says write the draft to <serie>/linkedin/<article>.draft.md. Steps 7 and 8 expect NN-utkast.md (two-digit NN prefix) in the series root. build-linkedin.mjs silently skips any file without an NN prefix (↷ hopper over … (ikke NN-prefiks)). Evidence: render/build-linkedin.mjs line 357 regex ^(\d{2}); the command text uses two different paths/names for the same draft. Impact: Following Step 3 literally produces a file (*.draft.md, inside linkedin/) that Step 8 then silently skips — a green exit with no POST.html. Implicates: commands/newsletter.md (reconcile Step 3 vs Steps 7/8 on draft filename + location) → Step 15 fix.

F5 — [MAJOR] Series root hardcoded to maskinrommet

What: Step 0 resolves the series folder under /Users/ktg/repos/maskinrommet/serier/<slug>/ with no parameter to point elsewhere. Dogfooding (or any other repo / a throwaway fixture) requires a manual mental override of the documented path. Evidence: Step 0.1 and the architecture note both hardcode the maskinrommet path; the dogfood had to invent docs/review/dogfood-serie/ off-spec. Impact: The command is coupled to one specific external repo. Operator must deviate from the written procedure for any other location. Implicates: commands/newsletter.md Step 0 (accept/derive a series-root arg; keep maskinrommet as default, not the only path) → Step 15 fix (or deferred with operator note if maskinrommet-only is intentional).

F6 — [MINOR] build-linkedin.mjs carries Seres-specific hardcoding

What: CAROUSEL = new Set(["03","06"]) and the unconditional samle-post build are Seres-series assumptions baked into a script that S2 "generalized." Evidence: Dogfood produced linkedin/samle/POST.html for a single-edition fixture that has no series to summarize; the carousel set is dead for any series whose carousel editions aren't 03/06. Impact: Low for correctness (samle is harmless extra output), but it is generalization debt — the script still assumes the Seres shape. Implicates: render/build-linkedin.mjs (lines 63, 364–370) → likely defer to a later generalization pass; note for operator.

F7 — [MINOR] build-html.mjs returns exit 0 on a missing input file

What: A missing input arg prints Fant ikke: <path> to stderr and continues; the loop completes with exit 0 and no HTML produced. Evidence: render/build-html.mjs lines 1045–1048 (continue, no process.exit, no error accumulation). Impact: Step 7 already flags this (N3), but the script's silent exit-0 is a footgun: a typo'd filename looks like success. The command must check that the expected output file exists, not just the exit code. Implicates: render/build-html.mjs (exit non-zero if zero files written) +/or commands/newsletter.md Step 7 (verify output file, not just exit) → Step 15 fix candidate.

F8 — [MINOR] Fatal-vs-graceful asymmetry on missing delivery inputs (Step 8)

What: Step 8 says "if either file is absent the script throws on read." In fact edition-config.json is graceful (loadEditionConfig falls back to empty defaults), while edition-delingstekst.md is fatal — parseDelingstekst() runs unconditionally at the top of main() and ENOENT-throws before any POST.html is written, including the article POST that does not depend on it. Evidence: render/build-linkedin.mjs lines 45–59 (graceful config) vs 180 (fs.readFileSync(DELINGSTEKST_FILE) with no try) called at line 349. Impact: The command's description of the failure mode is inaccurate, and a missing delingstekst kills the whole build rather than degrading. Implicates: render/build-linkedin.mjs (guard parseDelingstekst like config)

• commands/newsletter.md Step 8 (correct the "either file throws" wording) → Step 15 fix candidate.

F9 — [MINOR] agents/README.md registered as an agent

What: The harness available list includes linkedin-thought-leadership:README — a non-agent README in agents/ is being picked up as an invokable agent. Evidence: Available-agents list this session contains …:README. Impact: Cosmetic/registry noise; not harmful but pollutes the agent namespace. Implicates: agents/README.md (relocate, or ensure it lacks agent frontmatter) → likely defer / doc-pass.

---

What ran clean (no friction)

• Step 7 annotation — build-html.mjs 01-utkast.md (cwd = serie-mappe) → wrote review/01-utkast.html (30.4 KB), exit 0. ✅
• Step 8 render — build-linkedin.mjs 01-utkast.md → linkedin/01/POST.html
  • linkedin/samle/POST.html, exit 0; body survived (headings/lists/strong present in POST.html). ✅ (Render works; the lock gate is blocked, not the renderer.)
• cwd contract — running both scripts from the series folder resolved linkedin/ and review/ correctly. The command's "cd to the series folder" instruction is right; the footgun is only if you forget (then output lands under the plugin).
• edition-state schema — the template's phase list and article-status values were sufficient to represent the walk; resumption table in Step 0 is coherent.

Friction summary for Step 15 (revert/fix targets)

#	Severity	Implicated file	Step 15 disposition	Status
F1	BLOCKER	commands/newsletter.md	namespace agent calls	✅
F2	BLOCKER/env	env + CLAUDE.md/README.md	reload + document	✅ (doc) / 🔶 (reload = operator)
F3	MAJOR	config/ + commands/newsletter.md	add 3 templates	✅
F4	MAJOR	commands/newsletter.md	reconcile draft path/name	✅
F5	MAJOR	commands/newsletter.md	de-hardcode series root	✅
F6	MINOR	render/build-linkedin.mjs	config-derive carousel; fix samle comment	✅
F7	MINOR	render/build-html.mjs (+ Step 7)	exit non-zero on no output	✅
F8	MINOR	render/build-linkedin.mjs (+ Step 8)	guard delingstekst + fix wording	✅
F9	MINOR	agents/README.md	relocate out of agents/	✅ (relocated) / 🔶 (de-register on reload)

Headline: the long-form pipeline's deterministic backbone is sound, but its gate layer is currently un-runnable (F1 + F2). Step 15 must close F1 (a concrete one-line-per-call edit) and F2 (reload + a doc note) before the pre-lock persona sweep can actually execute — the order is correctly wired, it just cannot fire yet.

---

Step 15 (S14) — re-test outcomes

All nine friction points were closed (operator elected to fix F6–F9 rather than defer). Each was re-tested with a concrete check, not a self-asserted "fixed."

• F1 — ✅ closed. All four Task call sites in commands/newsletter.md (content-repurposer Step 3, fact-checker Step 5, persona-reviewer Steps 6 + 9) now use the namespaced subagent_type: linkedin-thought-leadership:<name>, plus a canonical "Agent invocation form (required)" note near the foreground principle. Check: grep -nE 'subagent_type: (fact-checker|persona-reviewer|content-repurposer)' commands/newsletter.md → zero bare names; grep -nE 'linkedin-thought-leadership:(fact-checker|persona-reviewer|content-repurposer)' → all 4 sites namespaced.
• F2 — ✅ doc / 🔶 reload. Documented in CLAUDE.md (Agents section: invocation form + reload requirement) and README.md (Agent Architecture note). The environmental half — registering a newly-added agent — inherently requires a Claude Code session reload; that is an operator action, not a code change. Confirmed F2 persists across /clear: fact-checker/persona-reviewer were still absent from this fresh session's agent registry (only the 15 older agents + README appeared), proving it is a reload gap, not a per-session fluke.
• F3 — ✅ closed. Added config/edition-config.template.json, config/edition-delingstekst.template.md, config/edition-HANDOVER.template.md (formats reverse-engineered from the render scripts, now shipped as reference). Wired into newsletter.md Step 0 (HANDOVER), Step 8 (config + delingstekst), and the Reference Files footer. Check: all three exist under config/; edition-config.template.json parses as valid JSON.
• F4 — ✅ closed. Step 3 now writes the canonical <serie>/NN-utkast.md in the series root (the exact file Steps 7/8 render), with an explicit "do NOT write linkedin/<article>.draft.md" warning. Check: no .draft.md/<article> path refs remain except the intentional anti-pattern warning.
• F5 — ✅ closed. Step 0 resolves a series root via an order (explicit path arg → ${LTL_SERIES_ROOT:-…/maskinrommet/serier}/<slug>/ → ask once); maskinrommet is the default, not the only path. The architecture preamble was aligned to match.
• F6 — ✅ closed. CAROUSEL = new Set(["03","06"]) removed; carousel editions are now config-derived (config.carousel, a list of NN strings) via loadEditionConfig
  • EMPTY_CONFIG + the new config template. Misleading "samle bygges alltid" comment corrected (build has always been gated on shareMap.samle). Check: grep -n CAROUSEL render/build-linkedin.mjs → none; 20/20 render tests pass (one assertion updated to include the carousel: [] default).
• F7 — ✅ closed. build-html.mjs main() now counts files written, prints Ingen HTML produsert … and the CLI guard exits non-zero when zero files are produced (no more silent exit-0 on a typo'd filename). Step 7 wording updated to rely on the exit code AND verify the output file. Re-tested live: missing input → exit 1; valid input → exit 0 + review/NN-utkast.html written.
• F8 — ✅ closed. parseDelingstekst() wrapped in try/catch returning {} on ENOENT, matching loadEditionConfig's fail-soft contract; Step 8 wording corrected ("both inputs optional and graceful," not "either file throws"). Re-tested live: no delingstekst → build-linkedin.mjs exit 0 + linkedin/01/POST.html still built.
• F9 — ✅ relocated / 🔶 de-register on reload. git mv agents/README.md docs/agents-capability-matrix.md — the only reliable fix, since the file registers by filename (it had no frontmatter yet still appeared as linkedin-thought-leadership:README). The stale registration clears on the next Claude Code reload (env, same as F2). Check: no README in agents/; docs/agents-capability-matrix.md present.

Finding (out of Step 15 scope — recorded, not actioned)

plan.md Steps 16, 17, 18 hard-code agents/README.md as an explicit grep search path (plan.md:635, 727, 849). After F9's relocation that path no longer exists. The explicit arg is redundant with the recursive agents/ search those greps already include, so dropping it (or repointing to docs/agents-capability-matrix.md) is safe — but plan.md is outside Step 15's Files list (Hard Rule 2), so this is logged for the operator/those steps rather than edited here. Action for Steps 16–18: drop the dangling agents/README.md arg from their Verify greps, or repoint to the new path.