linkedin-studio/docs/research-engine/plan-re-r3f.md

# Plan — RE-R3f: unattended AI discovery (`--headless`, slice e)

> **Brief:** `docs/research-engine/brief-re-r3f.md`. **Slice:** RE-R3f (research-engine rung-2 — R3
> slice (e), the AI-capture unattended-run slice). No new source/test file: this is a prompt-file
> (`commands/trends.md`) contract change plus documentation. There is nothing here for
> `scripts/test-runner.sh` to gain a new floor for — the plan's "TDD" is a direct-read verification
> against the brief's SC1–SC5, not a unit-test suite.

## Files touched (exhaustive)

| File | Change | SC |
|---|---|---|
| `commands/trends.md` | EDIT — `--headless` flag row + new **Step 0.5** contract section; Step 1's missing-profile branch forks on `--headless`; Step 2D refuses `--demand --headless`; Step 5 header states the unconditional skip | SC1, SC2 |
| `scripts/trends/README.md` | EDIT — new `## Unattended AI discovery — --headless (RE-R3f, slice e)` section: Desktop Scheduled Tasks (recommended) + the fallback `claude -p` recipe + `ANTHROPIC_API_KEY` + wait-ceiling + artifact-grounded success check + cost visibility | SC3 |
| `CLAUDE.md` | EDIT — `/linkedin:trends` command-table row gains a `--headless` clause | SC4 |
| `CHANGELOG.md` | EDIT — `[Unreleased]` entry naming MR-F5 | SC4 |
| `docs/research-engine/{brief,plan}-re-r3f.md` | NEW — tracked slice docs (mirrors R3c/R3e/etc.) | — |
| `STATE.md` | EDIT at land — Telling-block reconcile (no new counts; note MR-F5 landed) | — |

**Not touched (scope fence):** `scripts/trends/src/*.ts` (no code — Desktop Scheduled Tasks is the
mechanism, not a repo-owned wrapper); `scripts/trends/run-daily.sh` (RE-R3c stays deterministic-only,
untouched); `agents/trend-spotter.md` (the agent's own contract — poll/score — is unchanged by who
fires it; `--headless` is a command-level concern); `config/*`; `references/*`; command/agent counts
(no new command, no new agent — `--headless` is a flag on an existing command); `scripts/test-runner.sh`
(no new floor — nothing here is `tsx`-tested source).

## Step 1 — `commands/trends.md`: the `--headless` contract

Edited already this session (verify against brief SC1/SC2 by direct read):
1. Step 0 flags table gains the `--headless` row.
2. New **Step 0.5** section states the full contract: `--demand --headless` refusal, Step 1
   fail-fast, Step 5 unconditional skip, Steps 2–4/6 unchanged, artifact-grounded success.
3. Step 1's pillar-loading paragraph forks explicitly: `--headless` → error + stop; else → ask.
4. Step 2D gains the refusal clause for `--demand --headless` before its existing demand-sweep
   delegation text.
5. Step 5's header and lead line state the `--headless` skip condition (not buried only in Step 0.5
   — a reader working step-by-step must see it at the step itself).

**Verification:** `grep -n -- '--headless' commands/trends.md` shows the table row + Step 0.5 + the
three per-step cross-references (≥5 matches, SC1); re-read Steps 1/2D/5 end-to-end to confirm each
fork is unambiguous (no branch left to model inference under ambiguity, SC2).

## Step 2 — `scripts/trends/README.md`: the unattended-discovery section

Edited already this session. New section placed after the existing RE-R3c ("Autonomous trigger +
headless entry") section, explicit that RE-R3f is a **different mechanism** (full agent turn, not a
bash wrapper): Desktop Scheduled Tasks recommended; the fallback `claude -p …` recipe with all four
required flags; `ANTHROPIC_API_KEY` under `--bare`; `CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS`; the
artifact-grounded success check (never trust `$?`/prose); `total_cost_usd` cost-visibility note.

**Verification:** `grep -n -- '--bare\|--permission-mode dontAsk\|--allowedTools\|ANTHROPIC_API_KEY\|Desktop Scheduled Tasks' scripts/trends/README.md` — each present (SC3).

## Step 3 — `CLAUDE.md` + `CHANGELOG.md`

- `CLAUDE.md`: append a `--headless` clause to the existing `/linkedin:trends` row (one line, no
  restructuring of the table).
- `CHANGELOG.md`: `[Unreleased]` gains an entry — MR-F5 landed, the gate-opening decision named, the
  scope (command contract + docs, no new code), matching this repo's existing changelog voice (see
  the 0.8.0 entries for tone/format).

**Verification:** `grep -n -- '--headless' CLAUDE.md`; `grep -n 'MR-F5' CHANGELOG.md`.

## Step 4 — gate + regression sanity

`bash scripts/test-runner.sh` → `FAIL=0`, every existing floor unchanged (no new source/test file to
raise a floor for); Section 17 de-niche green (no vendor/sector token in any edit — the README's
`claude -p` recipe names a placeholder plugin-dir path, never an operator-specific one);
command/agent/reference counts unchanged, recounted live (`--headless` is a flag, not a new
surface).

## Step 5 — land

Recount counts live; reconcile `STATE.md`'s Telling block (no count change; note MR-F5 landed at
commit); quit the feedback register kvittering per `CLAUDE.local.md`'s protocol ("landed
feedback:MR-F5 @ `<commit>`" — Maskinrommet flips 🔵→🟢 on relay, never written here). Commit order:
**(1)** docs commit — `docs/research-engine/{brief,plan}-re-r3f.md` (tracked, no suffix); **(2)** one
code^H^H^H^Hprompt commit — `commands/trends.md` + `scripts/trends/README.md` + `CLAUDE.md` +
`CHANGELOG.md` (there is no code in this slice — "code commit" here means the prompt-file + docs
edit, landed together since it is one coherent contract change). Push after operator go (public
`open/` remote — confirm before push per the repo's own push-topology memory).

## Verification (testable)

| SC | Check | Command | Expected |
|---|---|---|---|
| SC1 | `--headless` documented | `grep -c -- '--headless' commands/trends.md` | ≥ 5 |
| SC2 | Per-step forks unambiguous | direct read of Steps 1, 2D, 5 | each states the `--headless` branch explicitly, no inference required |
| SC3 | README recipe complete | `grep` for the four flags + `ANTHROPIC_API_KEY` + `Desktop Scheduled Tasks` | all present |
| SC4 | CLAUDE.md + CHANGELOG updated | `grep -- '--headless' CLAUDE.md`; `grep 'MR-F5' CHANGELOG.md` | both present |
| SC5 | Gate green, counts unchanged | `bash scripts/test-runner.sh` | `FAIL=0`; all floors unchanged; Section 17 green |
| SC6 | (explicitly deferred) | — | consumer-side unattended proof is NOT claimed this session (`plugin-runtime-is-consumer-side`) |

## Risks

- **R1 — a scheduled task on the operator's actual machine can't reach Desktop Scheduled Tasks
  (older Claude Code version, disabled feature).** *Mitigated:* the fallback `claude -p` recipe is
  fully documented in the README, so the operator has a working path either way; not built as repo
  code because building an unused wrapper would be speculative (brief §3 D3).
- **R2 — the `--headless` contract is a prompt, so nothing enforces it mechanically; a future edit
  to `commands/trends.md` could silently reintroduce a blocking `AskUserQuestion` on the headless
  path.** *Accepted, stated honestly:* there is no code-level guard here (unlike RE-R3c's
  gate-tested `schedule.ts`). Claude Code's own `dontAsk` permission mode is the real backstop —
  `AskUserQuestion` is auto-denied unconditionally regardless of what the command file says — so a
  regression fails safe (the run aborts) rather than silently hanging on a phantom prompt.
- **R3 — unattended weekly AI research has a real, currently-uncapped per-run cost.** *Mitigated by
  visibility, not a cap* (brief §3 non-goal, D2): `--output-format json`'s `total_cost_usd` is
  documented as the thing to log; enforcing a hard ceiling is deferred as a real design question
  rather than an arbitrary number picked under this slice.
- **R4 — the gate-reopening decision itself is contestable** (research was explicitly deferred to
  v1.0.0 by a prior operator decision). *Mitigated:* the conflict was surfaced explicitly
  (AskUserQuestion, 2026-08-10) rather than silently built around or silently deferred; the operator
  chose to open it with the trade-off stated plainly. Recorded in the brief's header for future
  sessions reading this slice cold.