# Implementation Plan — SB-S0 (Foundation)

> **Status:** revised after adversarial plan-review (`plan-critic` + `scope-guardian`, both code-verified) → all findings folded in. Ready for operator approval.
> **Brief:** `brief.md` §5–§10. **Architecture:** `architecture.md`.
> **Scope:** SB-S0 only — the `brain/` scaffold, the two-layer `profile.md` + lossless user-profile fold, the entity-id/provenance module, the `ingest/` seam dirs. **No loop, no ingest logic, no connector, no cross-silo threading, no session-start wiring** (brief §7).
> **Review delta (2026-06-23):** B1 test convention → real TS idiom (`tests/*.test.ts` via tsx, `.js` specifiers); M2 profile format → **defined line-grammar (no YAML dep)**; M3 data-root → inline per-package resolver (repo idiom, not a new seam); M4 fold extraction rule pinned against the real template; m1 gate rationale corrected; m2 npm-install-before-gate; m3 provenance throws; m4 id keyed on stable slug; G1 push-confirm; C1 identity now whole-file.

---

## 1. What SB-S0 delivers (recap)

A new TS package `scripts/brain/` (an exact structural copy of `scripts/specifics-bank/`) exposing an idempotent `brain init` CLI that scaffolds the `brain/` + `ingest/` tree at the runtime data-path, a pinned two-layer `profile.md` **line-grammar** with parse/serialize round-trip, a lossless+idempotent user-profile fold (source-absent + populated), and a deterministic entity-id + provenance module. All unit-tested, TDD (failing test first). Gate stays green.

## 2. Package layout (`scripts/brain/`) — exact copy of `scripts/specifics-bank/` conventions

```
scripts/brain/
  package.json          # copy specifics-bank/package.json; "test": "node --import tsx --test tests/*.test.ts"; devDeps tsx + typescript ONLY (no yaml — see §3.3)
  tsconfig.json         # copied VERBATIM from scripts/specifics-bank/tsconfig.json (rootDir ./src, include src/**/*)
  src/
    types.ts            # Provenance, FactStatus, ProfileFact, ProfileDoc, constants
    id.ts               # mintEntityId(), slugify(), normalizeProvenance()
    profile.ts          # parseProfile(), serializeProfile(), foldUserProfile()
    dataRoot.ts         # inline resolver (repo idiom — §3.5)
    cli.ts              # `brain init`
  tests/                # NOTE: tests/*.test.ts, run via tsx; import source via .js specifiers (e.g. "../src/id.js")
    id.test.ts
    profile.test.ts
    scaffold.test.ts
    fold.test.ts
  fixtures/
    user-profile.populated.md   # synthetic populated user-profile mirroring the template's extractable constructs (§3.4)
```

**B1 fix (verified):** all three sibling TS packages use `tests/*.test.ts` via `node --import tsx --test tests/*.test.ts` and import source through `.js` specifiers (`specifics-bank/package.json:8`, `specifics-bank/tests/bank.test.ts:15` `from "../src/bank.js"`). The `__tests__/*.test.mjs` idiom is the HOOKS convention (no tsx loader) and cannot import `.ts` source — NOT used here.

## 3. Module designs

### 3.1 `types.ts`
```ts
export type Provenance = 'human' | 'published' | 'ai-draft';
export type FactStatus = 'active' | 'superseded';
export interface ProfileFact {
  id: string;            // canonical entity id (id.ts), keyed on a stable slug
  value: string;         // single-line (no embedded newline)
  first_seen: string;    // YYYY-MM-DD
  last_seen: string;     // YYYY-MM-DD
  evidence_count: number;
  provenance: Provenance;
  status: FactStatus;
}
export interface ProfileDoc { schemaVersion: 1; static: ProfileFact[]; dynamic: ProfileFact[]; }
export const PROVENANCE_VALUES = ['human','published','ai-draft'] as const;
```

### 3.2 `id.ts`
- `slugify(label: string): string` → lowercase, trim, non-alphanumeric → `-`, collapse repeats. Stable across value edits.
- `mintEntityId(seed: {kind: string; key: string}): string` → `sha256(`${kind}:${slugify(key)}`).slice(0,12)` (matches trends/specifics `sha256[:12]`; confirm the exact hash call against `scripts/specifics-bank/src/bank.ts` in step 1). Deterministic, pure.
- `normalizeProvenance(raw: string): Provenance` → trim+lowercase; return the match or **throw** on anything outside `PROVENANCE_VALUES`. (m3: throws — SC4 asserts `assert.throws`; "normalises" dropped.)

### 3.3 `profile.ts` — pinned line-grammar (M2 decision: NO YAML dep)
**Verified:** the repo has no YAML parser (`state-updater.mjs:43` `extractField` is per-field regex on single scalars; zero `yaml` dependency in-tree). Frontmatter-with-nested-arrays would force a new dep + an untested hand-rolled emitter. **Decision — a defined line-grammar that round-trips with the regex idiom and needs no dep:**

```
# Profile

schemaVersion: 1

## Static

- [<provenance>|<status>|<first_seen>|<last_seen>|<evidence_count>|<id>] <value>

## Dynamic

- [<provenance>|<status>|<first_seen>|<last_seen>|<evidence_count>|<id>] <value>
```

- The bracket holds six pipe-joined **constrained** tokens (two enums, two ISO dates, an int, a 12-hex id) — none can contain `]` or `|`. `<value>` is the rest of the line after `] ` (free single-line text; may contain `]`/`|`/quotes).
- `parseProfile(text)`: split into `## Static` / `## Dynamic` sections; each `- [...]` line parsed by
  `^- \[(human|published|ai-draft)\|(active|superseded)\|(\d{4}-\d{2}-\d{2})\|(\d{4}-\d{2}-\d{2})\|(\d+)\|([0-9a-f]{12})\] (.*)$`.
  `schemaVersion` read by the existing scalar-regex idiom.
- `serializeProfile(doc)`: deterministic token order → `- [...] value`, sections in fixed order.
- **`parseProfile(serializeProfile(doc)) === doc`** over the WHOLE file (C1 resolved: there is no derived/ignored body — the lines ARE the authoritative representation). SC2 tests this identity.

### 3.4 `profile.ts` — `foldUserProfile()` (M4: extraction rule pinned against the real template)
`config/user-profile.template.md` is heterogeneous (`config/user-profile.template.md:15-147`: bold-label scalars, a numbered expertise group, checkbox lists, non-labeled bullets, prose guidance). **Pinned extraction — exactly two productions:**
- **P1 (labeled scalar):** any line matching `^\s*(?:- )?\*\*(.+?):\*\*\s*(.*)$` → `label`=g1, `value`=g2 (the `[placeholder]` text; treated as *unfilled/empty* when it is a bracketed placeholder, literal otherwise). One `ProfileFact` per match. Covers Name/Role/Organization/Industry, the `- **Primary:**` etc. sub-labels, Signature Elements, Writing Quirks, Current LinkedIn Status.
- **P2 (expertise group):** under the `**Core Expertise Areas (...)**:` label, each `^\d+\.\s*(.*)$` line → one fact, label `expertise-area-N`.
- **Excluded (deferred, noted §8):** checkbox lines (`- [ ] …` — Tone, LinkedIn Goals, Research MCPs, Asset Utilization), non-labeled bullet lists (Content Style Mix), the Voice-Profile-Summary numbered `1. **[Quality N]:**` items, prose guidance blocks (Universal anti-patterns 95-104, Research-Tooling explainer), and headers.

```
foldUserProfile({ templateText, instanceText?, existing? }): ProfileDoc
```
1. Apply P1+P2 to `templateText` → the canonical field-set (id = `mintEntityId({kind:'profile-field', key: label})`, value empty, `provenance:'human'`, `evidence_count:0`, `status:'active'`, dates = run date). → `static[]`. (`dynamic[]` empty in S0.)
2. **Source-absent (common):** no `instanceText` → return that field-set with empty values.
3. **Populated:** `instanceText` present → re-run P1+P2 on it, copy filled values onto the matching id.
4. **Idempotent:** if `existing` passed → merge by `id`; never duplicate, never overwrite a non-empty value, bump `last_seen` only.
Pure; the CLI supplies the file texts. (m4: id keyed on `slugify(label)`, stable across value edits; label-text stability is a known S0 limit — §8.)

### 3.5 `dataRoot.ts` — inline resolver (M3: repo idiom, NOT a new seam)
**Verified:** no shared util; cross-package import not configured (`specifics-bank/tsconfig.json` rootDir `./src`, no path map/workspace); siblings each inline it (`trends/src/store.ts:180`, `specifics-bank/src/bank.ts:150`, plus `analytics/src/utils/storage.ts:54`). Match the idiom:
```ts
import { homedir } from 'node:os'; import { join } from 'node:path';
export const dataRoot = (sub: string) =>
  join(process.env.LINKEDIN_STUDIO_DATA ?? join(homedir(), '.claude', 'linkedin-studio'), sub);
```
This is a **private package resolver, not an exported seam function** → SC6 (no new seam, twin-sync untouched) holds. True de-duplication of the now-4 copies is an explicit out-of-scope refactor.

### 3.6 `scaffold.ts` — `initBrain(rootSub?)` (D1, D5) + `cli.ts`
- Create idempotently (mkdir-recursive; **compare-then-skip**, never blind-write): `brain/journal/`, `ingest/inbox/`, `ingest/published/`; `brain/profile.md` (IF absent → `serializeProfile(foldUserProfile({templateText}))`), `brain/index.md` (IF absent → MOC seed: one line per tributary [voice-samples, specifics-bank, trends, analytics, ingest] with `freshness: —`), `brain/operations.md` (IF absent → `## Who I am now (anchor)` + empty `## Plans` / `## Ideas`).
- Returns `{created[], skipped[]}`. **No session-start wiring** (SB-S2). `cli.ts`: `brain init` → `initBrain()`, print report. Dispatch shape copied from `specifics-bank/src/cli.ts`.

## 4. Files created / edited

**Created:** `scripts/brain/{package.json,tsconfig.json}` · `scripts/brain/src/{types,id,profile,dataRoot,cli}.ts` · `scripts/brain/tests/{id,profile,scaffold,fold}.test.ts` · `scripts/brain/fixtures/user-profile.populated.md`.

**Edited (minimal):**
- `scripts/test-runner.sh` — add a `BRAIN_TESTS_FLOOR` block copied from the `TRENDS_TESTS_FLOOR` block (`scripts/test-runner.sh:681-694`): cd `scripts/brain`, run the suite, grep `ℹ tests N` (`grep -oE 'tests [0-9]+' | tail -1`), assert `≥ BRAIN_TESTS_FLOOR`, emit one `pass()` line. Bump Section 18's anti-erosion note (`:770`, `TOTAL_CHECKS >= 74` grows by 1).
- `docs/second-brain/architecture.md` — flip SB-S0 row to "landed" (DoD).
- (NO change to `data-root.mjs`/`storage.ts` — no seam function added, SC6.)

## 5. TDD test plan (failing-first) → success criteria

| Test (`tests/*.test.ts`) | Asserts | SC |
|---|---|---|
| `id.test.ts` | `mintEntityId` deterministic (same in→same id; diff→diff); `slugify` stable; `normalizeProvenance` returns the 3 values, `assert.throws` on others | SC4 |
| `profile.test.ts` | `parseProfile(serializeProfile(doc)) === doc` over the whole file incl. a value containing `]`/`|`/quotes; sections `## Static`/`## Dynamic` present | SC2 |
| `fold.test.ts` | (a) source-absent → field-set from template (P1+P2), values empty; (b) populated fixture → every filled field carried (diff none-dropped); (c) re-run → no dup, no overwrite | SC3 |
| `scaffold.test.ts` | `LINKEDIN_STUDIO_DATA`=tmp → init creates all dirs+files at runtime path; second init = no-op (skipped[] covers them, files byte-identical) | SC1 |
| (gate) `scripts/test-runner.sh` | green; trends ≥24, specifics ≥28, contract ≥33, **brain ≥ floor**; hooks pass | SC5 |
| (n/a) | no new seam fn; unchanged `data-root.test.mjs` twin-sync still passes | SC6 |

Each test written **before** its module (iron law): red → implement → green.

## 6. Step sequence

1. **Confirm idioms in code (verify-first):** read `scripts/specifics-bank/{package.json,tsconfig.json,src/bank.ts,tests/bank.test.ts}` → copy the package/test scaffolding + the exact sha256 call. `npm install` in `scripts/brain` so tsx is present (m2: the gate `warn`-skips a suite if `node_modules/.bin/tsx` is absent — "green" must not mean green-because-skipped).
2. `types.ts` (no logic).
3. TDD `id.ts` (`id.test.ts`). → SC4.
4. TDD `profile.ts` parse/serialize line-grammar (`profile.test.ts`). → SC2.
5. Write `fixtures/user-profile.populated.md` mirroring the P1+P2 constructs; TDD `foldUserProfile` (`fold.test.ts`, 3 cases). → SC3.
6. TDD `scaffold.ts` `initBrain` (`scaffold.test.ts`, temp-dir idempotency). → SC1.
7. `cli.ts` `brain init`; smoke-run against a temp `LINKEDIN_STUDIO_DATA`.
8. Wire `scripts/test-runner.sh` BRAIN floor (+ Section 18 note); run the FULL gate green. → SC5/SC6.
9. Flip `architecture.md` SB-S0 → landed. **Commit; confirm before push (PUBLIC `open/` Forgejo) and only inside the push window; STATE.md stays gitignored** (G1).

## 7. Scope fence (echo — SB-S0 does NOT)

No consolidation loop · no ingest file parsing · no LinkedIn API · no id threading into tributaries · no session-start wiring · no tributary-schema edits · no state-file/two-roots reconciliation · no `content-history.md` retirement · no GUI.

## 8. Known limits / deferred (honest)

- **Fold covers only P1 labeled-scalars + P2 expertise group.** Checkbox preference lists (tone, goals, MCPs, assets), non-labeled bullets, and the Voice-Profile-Summary qualities are NOT folded in S0 — they are template *guidance/preferences*, foldable in a later slice when the profile schema grows. Stated so SC3a's field-set is finite + testable.
- **Profile-field id keyed on `slugify(label)`** — stable across value edits (fixes the raw-label non-idempotency). A *renamed template label* would still mint a new id; acceptable in S0 (template is fixed) — re-confirm if SB-S1+ lets users edit labels.
- **`parse∘serialize` identity holds for single-line values.** A value with an embedded newline is out of grammar; the fold never produces one (template/instance fields are single-line), but `addFact` paths in later slices must enforce it.
- **Gate "green" is honest only with deps installed** (m2) — fresh clone must `npm install scripts/brain` or the brain suite `warn`-skips.

## 9. Risks

- **Fold under-specification** → mitigated: P1+P2 pinned + `fold.test.ts` covers source-absent + populated + re-run before the CLI wires it.
- **Idempotency edge:** `initBrain` + fold merge must compare-then-skip (never blind-write); tested in `scaffold.test.ts` / `fold.test.ts` (c).
- **Gate mechanics (corrected, m1):** 89 is the gate's own `PASS+FAIL` tally; each suite contributes exactly ONE `pass()` line (not its internal `tests N`); the only total guard is the growable `TOTAL_CHECKS >= 74` floor (`:770`). Adding BRAIN raises that floor by 1 — no `==89` guard exists, so no regression flag. The risk is the warn-skip (m2), handled in step 1/8.