linkedin-studio/docs/second-brain/plan-sb-s3e.md

Plan — SB-S3e: hygiene (retire dead content-history.md) + triple-post reconciliation (read-side)

Brief: docs/second-brain/brief-sb-s3e.md. Slice: SB-S3e — the LAST S3 slice (arc complete after; S4 optional). Recommendations pending the go-gate: (b) retire content-history · (c) read-side joiner (brain reconcile) · build now (not doc-only) · brain-CLI-only (no new plugin command/agent). Order is TDD: the failing reconcile test + gate self-test land BEFORE the reconcile code (iron law). The retirement is deletion — its proof is grep-zero + the migrate suite staying green.

Goal

Two coupled deliverables: (b) the dead, zero-reader content-history.md is removed across all eight of its plumbing surfaces (writer prose, template, migration entry+test, gitignore, gate guard, ref-doc, comment); (c) a new read-only brain reconcile reconciles silo 1 (## Recent Posts, auto-tracked creation) against the silo 2↔3 graph, surfacing the coverage gap (created posts never ingested into the brain) — without ever writing the state silo. No state-file write, no $-injection surface, no auto-capture.

Files touched (exhaustive — for scope-guardian)

(b) Retirement

File	Change	SC
hooks/prompts/state-update-reminder.md	remove Section 5 "Content History Log" (:67-86) — the sole writer	SC1
config/content-history.template.md	DELETE	SC1
hooks/scripts/migrate-data.mjs	remove the B1 MOVE_FILES entry (:33)	SC1
hooks/scripts/__tests__/migrate-data.test.mjs	drop content-history fixture (:37), its 2 assertions (:56,:61), trim test-(a) description (:50); cases a–e stay (count unchanged)	SC2
.gitignore	remove assets/analytics/content-history.md (:44)	SC1
scripts/test-runner.sh	narrow SC2_CLASSES (:592) — drop the content-history\.md alternative (check stays → gate count unchanged)	SC1/SC5
references/data-path-convention.md	remove content-history.md from the data-tree diagram (:26)	SC1
hooks/scripts/session-start.mjs	drop content-history from the comment list (:94)	SC1

(c) Reconciliation (read-side)

File	Change	SC
scripts/brain/tests/reconcile.test.ts	NEW — RED-first: coverage tiers + truncated-hook degradation + empty-state	SC3
scripts/brain/src/reconcile.ts	NEW — pure reconcileRecentPosts + parseRecentPosts + loadRecentPosts IO seam	SC3/SC4
scripts/brain/src/cli.ts	add reconcile subcommand (runReconcile) + dispatch (:312) + usage line	SC4
scripts/test-runner.sh	NEW Section 16f (2 unconditional checks) + ASSERT_BASELINE_FLOOR 82→84 + BRAIN_TESTS_FLOOR 114→recount + header enumeration	SC4/SC5
docs/second-brain/architecture.md	mark the SB-S3 build-row S3e ✅ (arc complete)	SC7

Not touched (scope fence): hooks/scripts/state-updater.mjs, ## Recent Posts, pruneContentHistory (S3e reads silo 1, never writes) · assemble.ts join heuristic (reconcile consumes the graph) · consolidate.ts/ingest.ts (no engine change) · consolidation-loop.md · CLAUDE.md command/agent tables (no new command/agent; brain reconcile is an internal CLI subcommand) · README :120 conceptual "content-history alignment" (concept, not the file — verify-then-leave).

Step 1 — (RED) Reconcile test against the absent module

scripts/brain/tests/reconcile.test.ts — model the IO/pure split on assemble.test.ts. The RED is a logic-RED, not an import-RED: land a stub reconcile.ts first that compiles + exports the symbols but mis-classifies (returns [] / a wrong tier), so the named tier assertions go red against logic, not a MODULE_NOT_FOUND. Cases:

1. parseRecentPosts extracts {date, hook, charCount, topic} from a ## Recent Posts block whose entries match the writer's exact format (updatePostTracking, state-updater.mjs:116: - [YYYY-MM-DD] "hook" (chars) - topic) — the format source of truth, NOT the date-only pruner regex (:145). A golden-string case feeds a literal writer-produced entry and asserts the round-trip. A non-## Recent Posts doc → []; a $-bearing topic/hook round-trips verbatim (capture/match on read — no String.replace → no regex injection).
2. reconcileRecentPosts({recentPosts, records, graph}) (the pinned 3-arg signature — records carry body, which PostGraphNode lacks) classifies each silo-1 entry:
   • in-graph — a published record matches (date + hook-prefix on record.body) AND its graph node has an analytics match → the full chain is observable.
   • in-brain-only — record matches but its graph node's analytics confidence==='none'.
   • orphaned-in-state — no record matches (created via the plugin, never brain ingest-ed) → the coverage gap.
   • summary counts (created N · in-graph M · orphaned K).
3. Truncated-hook degradation — a ≤60-char preview ending ... strips the marker before prefix-matching (mirror assemble.ts: stripTrailingEllipsis); a preview too short to discriminate (below a PREFIX_FLOOR-style guard) → orphaned, never a false in-graph.
4. Empty-state — empty/absent ## Recent Posts → empty report, no throw.

RED proof (recorded — logic-RED): with the mis-classifying stub in place, (cd scripts/brain && npm test) → the named tier assertions fail (e.g. "expected orphaned-in-state, got …"). Capture that transcript as the iron-law artifact in STATE/changelog — not a bare import error. Circuit-breaker: if the RED run is not recorded before the real reconcile.ts logic lands, halt and redo Step 1 (the RED proof is the only circuit breaker in this plan).

Step 2 — (GREEN) reconcile.ts — pure core + parser + IO seam

scripts/brain/src/reconcile.ts:

• parseRecentPosts(stateText: string): RecentPost[] — regex the ## Recent Posts section against the writer's format (updatePostTracking, state-updater.mjs:116: - [${postDate}] "${hookPreview}" (${charCount}) - ${postTopic}) → e.g. /^- \[(\d{4}-\d{2}-\d{2})\] "(.*)" \((\d+)\) - (.+)$/gm. NB: this is NOT pruneContentHistory's regex — that one (:145) is date-only (/^- \[(\d{4}-\d{2}-\d{2})\] .+$/gm) and captures no hook/chars/topic; parseRecentPosts is the first full-field reader of this section and tracks the writer, not the pruner. Pure.
• reconcileRecentPosts({recentPosts, records, graph}): ReconcileNode[] + summarize(...) — pure, no FS/clock. records is the full PublishedRecord[] (carry body); graph is PostGraphNode[] (carry contentId + analytics match, NO body). Reuse assemble.ts's normalize / stripTrailingEllipsis idiom (brain-local copy, NOT a new shared util — the repo's accepted duplication, dataRoot.ts header). Match recentPost.hook (ellipsis-stripped, normalized) as a prefix of record.body; confidence by date equality; below the prefix floor → orphaned. Then look up the matched record.id in graph to read its analytics tier (in-graph if the node's match.confidence !== 'none', else in-brain-only).
• loadRecentPosts(): RecentPost[] — the new cross-seam IO. Resolve the state file with the canonical precedence already exported as data-root.mjs: getStateFile() — process.env.STATE_FILE || join(resolveHome(), ".claude", "linkedin-studio.local.md") where resolveHome() = process.env.HOME || process.env.USERPROFILE || homedir() (data-root.mjs:17-19). NOT bare homedir() — that silently ignores a HOME/USERPROFILE override the writer honours (state-updater.mjs:12); and NOT dataRoot() (that is the dir under LINKEDIN_STUDIO_DATA). The brain TS copies getStateFile()'s chain because it cannot import the .mjs. Read read-only; absent → [] (fresh-clone safe). Header caveat: this is a new root-skew seam (state file via STATE_FILE, a different root than the brain dataRoot) — not a mirror of assemble.ts's ANALYTICS_ROOT note.

GREEN gate (brain): (cd scripts/brain && npm test) → reconcile cases pass; record the new live tests total → BRAIN_TESTS_FLOOR 114→that number (recorded, not guessed; update the inline breakdown comment test-runner.sh:718 with "+ SB-S3e N [reconcile]").

Step 3 — (GREEN) Wire brain reconcile into the CLI

scripts/brain/src/cli.ts:

• Add runReconcile() (model on runAssemble, :161-191). Loader (BLOCKER fix): do NOT use listPublished() — it takes no args and returns body-less PublishedSummary[] (ingest.ts:262-289). Instead reuse runAssemble's inline loader (cli.ts:163-174): readdirSync(pubDir).filter(.md).map(parsePublishedRecord) → real PublishedRecord[] (with body/specifics/trends). Then const analytics = loadAnalyticsRows(), const graph = assemblePostGraph({records, analytics}), const recentPosts = loadRecentPosts(), and call the core by its literal name reconcileRecentPosts({recentPosts, records, graph}) (no alias/re-export wrapper — Section 16f Check B greps cli.ts for the literal reconcileRecentPosts). Print per-post lines (· <date> · <tier> · "<hook>") + summary + nudge ("K created posts are not in the brain graph — brain ingest --file <p> to feed them"). Read-only.
• Dispatch: insert if (command === "reconcile") return runReconcile(flags); after the assemble dispatch line (:312, i.e. at the new :313 before usage(...)).
• Usage: add " reconcile" to the usage block after the " assemble" line (:94).

GREEN gate (lint): Section 16f Check B now passes (see Step 5).

Step 4 — (b) Retire content-history.md (deletions)

Apply the eight edits in the (b) table. Order: remove the writer (state-update-reminder.md Section 5) first, then template, migration entry, gitignore, gate guard, ref-doc, comment. Then trim migrate-data.test.mjs — drop the content-history fixture write + the two assertions + the words "content-history moved" from the test-(a) name; cases a–e remain.

Gate (hook suite — separate runner), recorded: node --test hooks/scripts/__tests__/migrate-data.test.mjs → cases a–e green (capture the transcript — R8 is demonstrated, not asserted). Confirm cases b–e never expected analytics/content-history.md as a present path (they don't — only the deleted case-(a) fixture/assertions referenced it; b–e exercise MOVE_DIRS / idempotency / collision / empty), so removing the B1 MOVE entry cannot regress them. SC1: grep -rn "content-history" hooks/ config/ scripts/test-runner.sh .gitignore references/data-path-convention.md → zero (the README :120 concept mention is out of this grep set; confirm it is the concept, leave it).

Step 5 — (RED→GREEN) Gate Section 16f + floors + SC2 narrow

Insert Section 16f after Section 16e (test-runner.sh:885, before Section 17 :886), modelled on 16e's two-check idiom (self-test + real-file grep, grep -qF fixed-string):

• Literals: RECON_CLI_LIT='command === "reconcile"', RECON_CORE_LIT='reconcileRecentPosts'.
• reconcile_wired() — wired iff a probe carries BOTH literals (echo twice; grep -qF — both literals contain regex-special chars, so -F is mandatory).
• Check A (self-test, unconditional, non-vacuous): a fully-wired probe MUST be detected; the rejected probes must each miss exactly one literal (the load-bearing discriminators), plus a specificity decoy:
  • D1 (discriminator): dispatch present, core call absent — command === "reconcile" but no reconcileRecentPosts → must REJECT (proves the core literal is load-bearing).
  • D2 (discriminator): core call present, dispatch absent — reconcileRecentPosts(...) but no command === "reconcile" → must REJECT (proves the dispatch literal is load-bearing).
  • D3 (specificity): a sibling command fully wired to the WRONG domain — command === "assemble" + assemblePostGraph (neither reconcile literal) → must REJECT (proves the predicate is reconcile-specific, not "any command + any core"). → pass/fail "reconcile self-test: full wiring detected; D1/D2 single-literal forms + D3 assemble specificity decoy rejected".
• Check B (real-file grep, unconditional): grep -qF "$RECON_CLI_LIT" scripts/brain/src/cli.ts && grep -qF "$RECON_CORE_LIT" scripts/brain/src/cli.ts → pass "brain CLI wired to reconcile (dispatch + core call by literal name)" else fail. Both literals live in cli.ts (the dispatch if + runReconcile's literal-name call to the core — Step 3 pins "no alias"), so one file carries both → deps-free, like 16e Check B.
• Header enumeration (:33-39): insert the 16f clause between the 16e clause's terminal "…in Section 16e;" (:38) and the "the assertion-count anti-erosion floor (SC6) in Section 18." tail — preserving 16e → 16f → 18 ordering. The range "Sections 8–18" is unchanged (16f is in range).
• ASSERT_BASELINE_FLOOR (:966): 82 → 84 (+2 deps-free unconditional checks — they lift the deps-absent minimum, NOT pinned to the deps-present TOTAL); extend the history comment ("+2 for SB-S3e's two Section-16f checks (reconcile self-test + brain-CLI reconcile grep) = 84").
• SC2_CLASSES (:592): delete the assets/analytics/content-history\.md| alternative (now retired). The SC2 check is still one pass/fail → gate TOTAL change comes only from 16f's +2.

RED proof: between Steps 1 and 3, a gate run shows Section 16f Check A passing (self-test is self-contained) and Check B FAILING (cli.ts not yet wired); after Step 3 both pass.

GREEN gate (full): bash scripts/test-runner.sh → FAIL=0; TOTAL recounted live. Recorded pre-change baseline (verified live this session, 2026-06-23): 97/0/0 → expected 99 after 16f's +2 (recount at land, never pin); ASSERT floor 84 honoured; SC2-dry-run green with the narrowed regex.

Step 6 — Doc reconciliation

Edit the architecture.md SB-S3 build-row: S3e ✅ — "dead content-history.md retired; brain reconcile reconciles post-tracking ↔ published ↔ analytics (read-side; auto-capture = follow-up)" — and note the arc is complete (S4 EØS-connector optional). No other architecture edit.

CLAUDE.md surface (open-Q4, resolved in-plan): brain reconcile is an internal brain-CLI subcommand, the same class as brain assemble/ingest/consolidate — none of which appear in CLAUDE.md's command/agent tables (those count plugin commands/agents). So no CLAUDE.md count change; the brain reconcile mention lives in the architecture.md build-row above. Confirm at the gate, but the default is no-plugin-surface.

Step 7 — Behavioural verification (manual, recorded — SC4/SC6)

Not unit-testable (operator-accepted command-testing gap). Honest procedure, result recorded at land:

• SC4 (e2e): seed a temp root — a ## Recent Posts block (via STATE_FILE), 1–2 ingest/published records (one matching a Recent-Posts entry, one not), an analytics batch — run brain reconcile; confirm it prints in-graph / orphaned tiers + the summary + nudge.
• SC6 (root-skew): with STATE_FILE=<tmp> it reads silo 1 from the temp file; unset → falls back to $HOME/.claude/linkedin-studio.local.md. Honesty hedge (verifiseringsplikt): if the per-call seam can't be exercised, record wiring-inspected-only, NOT a behavioural pass.

Step 8 — Land

STATE "Telling" + "👉 NESTE" updated (S3e done → arc complete; next = strategic checkpoint / product-maturity). Commit. Mixed: reconcile + retirement + gate are code ([skip-docs]); brief+plan+architecture are docs. Push only inside the window (date '+%u %H:%M' first; origin = PUBLIC open/ → confirm before push). No version bump (additive within v0.5.2 dev; release separate).

Verification (testable)

SC	Check	Command	Expected
SC1	content-history retired	grep -rn content-history hooks/ config/ scripts/test-runner.sh .gitignore references/ + ls config/content-history.template.md	zero hits; file gone
SC2	migration green	node --test hooks/scripts/__tests__/migrate-data.test.mjs	cases a–e pass
SC3	reconcile core (RED→GREEN)	(cd scripts/brain && npm test)	reconcile cases pass; floor recounted
SC4	reconcile wired	bash scripts/test-runner.sh + manual brain reconcile	Section 16f Check B passes; report prints
SC5	gate green + floor	same run	99/0/0 (confirm live); ASSERT floor 84; SC2-dry-run green
(red proof)	failing-test-first	gate + brain run BETWEEN Steps 1 and 3	reconcile test fails; 16f Check B fails
SC6	root-skew	manual, STATE_FILE set/unset	reads the pointed file / falls back (or honest fallback recorded)
SC7	counts reconciled	inspect	architecture S3e ✅; STATE telling updated; no CLAUDE.md command/agent count change

Risks

• R1 — vacuous gate. Mitigated by the 16e-style non-vacuity self-test with the assemble sibling-command decoy.
• R2 — seam-mismatch (the load-bearing one). loadRecentPosts() MUST resolve the state FILE via getStateFile()'s exact chain — STATE_FILE || join(resolveHome(), '.claude', 'linkedin-studio.local.md'), resolveHome() = HOME||USERPROFILE||homedir() (data-root.mjs:17-19,30-31) — NOT bare homedir() (ignores a HOME/USERPROFILE override) and NOT dataRoot() (the DIR under LINKEDIN_STUDIO_DATA). A divergence silently reads the wrong path. Mitigated: chain copied from the canonical getStateFile() (not state-updater.mjs:12, which falls through to '' — a latent bug data-root.mjs:14-16 warns against); SC6 exercises both STATE_FILE branches.
• R3 — parse drift. The reconcile entry regex must track the writer updatePostTracking (state-updater.mjs:116); if the writer's format changes, the reader silently misses. pruneContentHistory (:145) is date-only and would NOT catch such drift, so it is not a co-mover. Mitigated: a golden-string test feeds a literal writer-format entry through parseRecentPosts and asserts the round-trip — pinning the exact write format as the contract.
• R4 — retirement over-reach. Deleting a conceptual "content history" mention (README :120, or pruneContentHistory's name) would break live behaviour. Mitigated: the (b) table is file-plumbing-only; the scope fence + SC1's bounded grep set exclude the concept; pruneContentHistory (operates on ## Recent Posts) is explicitly out.
• R5 — $-injection on READ. parseRecentPosts uses match/capture (read), never String.replace with an untrusted replacement — so a $-bearing hook/topic round-trips verbatim (Step 1 case 1 pins it). No write path → no Section-13 state-updater surface touched.
• R6 — floor false-fail on fresh clone. 16f's two checks are deps-free (+2 → 84, correct). BRAIN_TESTS_FLOOR only checked when the brain suite runs (deps-present); a fresh clone warn-skips it.
• R7 — honest-limit overclaim. The brief/CLI must state plainly that read-side reports the coverage gap but cannot reconstruct un-captured specifics/trends (auto-capture = follow-up). Mitigated: §3 honest-limits + Step 7 verifiseringsplikt hedge.
• R8 — migrate idempotency. Removing the B1 MOVE entry must not break the .migrated marker / COPY-MOVE classes. Mitigated: cases b–e (idempotent re-run, collision, empty) stay green in Step 4's run.

Plan-critic — folded

voyage:plan-critic (3 blockers + 6 major + 4 minor) — each verified directly against the code before folding:

• B1 — body-less loader (load-bearing): listPublished() takes no args and returns PublishedSummary ({id,provenance,published_date,firstLine}, ingest.ts:262-289) — NO body. The reconcile prefix-match AND assemblePostGraph both need PublishedRecord.body. Folded Step 3: use runAssemble's inline readdirSync().map(parsePublishedRecord) loader (cli.ts:163-174), which yields real PublishedRecord[] (and already builds a bodyById Map). ✅
• B2 — core-signature contradiction: brief said {recentPosts, graph}; PostGraphNode has no body → graph-only can't prefix-match. Folded to the 3-arg {recentPosts, records, graph} in brief §3(c).1 + plan Steps 1/2 — one signature, agreed across brief/test/core. ✅
• B3 — regex misattribution: plan cited pruneContentHistory's :145 regex as full-field; it is date-only. Folded Step 2 + R3: the parser tracks the writer :116; parseRecentPosts is the first full-field reader; a golden-string test pins the write format. ✅
• M4 — HOME seam: loadRecentPosts must use getStateFile()'s resolveHome() chain (HOME||USERPROFILE||homedir()), not bare homedir() (ignores an override the writer honours). Folded Step 2 + R2, citing data-root.mjs:17-19,30-31 as canonical (not state-updater.mjs:12, which falls through to ''). ✅
• M5 — weak gate decoys: the both-absent assemble decoy was trivial. Folded Step 5: D1/D2 now miss exactly one literal each (the load-bearing discriminators); D3 (assemble sibling) is reframed as a specificity decoy. ✅
• M6 — Check-B literal name: reconcileRecentPosts appears in cli.ts only if runReconcile calls the core by its literal name. Folded Step 3 ("no alias/wrapper") + Step 5 Check-B wording. ✅
• M7 — unrecorded TOTAL: Folded Step 5 — recorded the live pre-change gate 97/0/0 (2026-06-23); 99 is the expected post-16f count, recount at land. ✅
• M8 — migrate idempotency asserted not shown: Folded Step 4 — require the recorded node --test migrate-data.test.mjs green run; confirm cases b–e never expected content-history present. ✅
• M9 — SC1 grep divergence: the brief's --include-filtered grep would skip .gitignore/.md. Folded — brief SC1 unified with the plan's unfiltered explicit-list grep. ✅
• m10 — header insertion point: Folded Step 5 — insert the 16f clause between the 16e clause terminal and the Section-18 tail. ✅
• m11 — :312/:94 line refs: Folded Step 3 — "after :312" / "after :94" (insertion, not the existing line). ✅
• m12 — CLAUDE.md deferred: Folded Step 6 — resolved in-plan: brain reconcile is internal brain-CLI (like assemble), no CLAUDE.md count change. ✅
• m13 — circuit-breaker: Folded Step 1 — "if RED not recorded before reconcile.ts logic lands, halt and redo Step 1." ✅

voyage:scope-guardian: ALIGNED — 0 creep / 0 gaps / 0 dependency issues. All 14 IN items map to a step; no NON-GOAL file touched; scope fence consistent (slightly broader/defensive); doc reconciliation proportional. Every file/line/symbol verified live.

Cross-checks confirmed sound: the (b) retirement arm was already nearly executable (all 8 surfaces verified); floor arithmetic (ASSERT 82→84 from 16f's +2; SC2-narrow nets 0; BRAIN 114→recount); the "read-side does not close the gap" honesty (auto-capture = the real closer, follow-up) stands; $-injection is absent on the read path (capture/match, never String.replace).