cc-os/docs/plans/c3-spike-findings.md

# C3 spike findings: `--setting-sources` interaction + overlay file placement

_Task: C3 in [system-prompt-profiles-tasks.md](system-prompt-profiles-tasks.md). Feeds B2._

## Method note (important correction mid-spike)

Initial attempts asked the model to self-report whether ORCHESTRATION.md/skills were
injected ("ORCH=yes/no SKILL=yes/no"). This was **unreliable** — a default run that the
transcript later proved *did* receive the orchestration injection had the model answer
`ORCH=no`. Model self-report is not a valid signal for this spike.

Switched to a deterministic signal: the session transcript JSONL at
`~/.claude/projects/<slug>/<session_id>.jsonl` records hook execution as
`attachment.type == "hook_additional_context"` entries (one per SessionStart hook that
returned `additionalContext`) and the full injected skill list as
`attachment.type == "skill_listing"`. Both are populated *before* the model ever sees the
turn, so they're a ground-truth substitute for `/context`.

## Spike (a): `--setting-sources` vs symlinked local plugins + absolute-path hooks

4 headless haiku runs from an empty scratch dir
(`/tmp/claude-1000/.../scratchpad/c3spike`), `claude -p --model haiku --output-format json
"reply OK"`, varying `--setting-sources`. For each, inspected the resulting transcript
JSONL for hook-injected additionalContext count and whether plugin-specific skills
(`os-adr`, `os-vault`) appear in the injected skill listing (built-in skills like
`autoresearch`/`caveman` appear regardless — only plugin skill presence is diagnostic).

| `--setting-sources` value | additionalContext entries (hooks fired) | os-adr/os-vault skills present |
|---|---|---|
| (no flag, default) | 1 (confirmed in first exploratory run) | yes |
| `""` (none) | 0 | no |
| `user` | 1 | yes |
| `project,local` | 0 | no |

Interpretation:

- Hooks in this setup are wired **only** in `~/.claude/settings.json` (a **user**-scope
  settings file), by absolute path into `cc-os/`. They fire if and only if the `user`
  settings source is included. `--setting-sources ""` and `--setting-sources
  project,local` both silently drop them — no error, no warning, just no
  `additionalContext`. This is a real footgun for a future `cyolo` profile wrapper: any
  profile that passes `--setting-sources` explicitly must include `user` or it silently
  loses ORCHESTRATION.md injection, os-status checks, os-vault hooks, and every other
  hook in the plugin family.
- Plugin skill registration (the `os-adr:find` style slash-command/skill listing) tracks
  the same axis: present with `user` included, absent without it. This makes sense —
  `enabledPlugins` lives in the user-scope `~/.claude/settings.json`, so a
  `--setting-sources` value that excludes `user` also excludes plugin enablement, not
  just hooks.
- Symlinks themselves are a non-issue: once the `user` settings source is included, the
  symlinked plugin (`~/.claude/plugins/os-adr -> cc-os/plugins/os-adr`) resolves and
  loads identically to the default case — no special-casing needed for the symlink or
  for the hooks' absolute paths into `cc-os/`. The failure mode is entirely about which
  settings **source** is included, not about symlinks or path resolution.

**Verdict (a):** `--setting-sources` interacts cleanly with symlinked plugins and
absolute-path hooks in the sense that nothing breaks or errors — but it is an all-or-
nothing gate: excluding `user` from `--setting-sources` silently disables every cc-os
plugin (hooks AND skills) with no error surfaced. Any profile wrapper must always include
`user` in `--setting-sources` (or simply not pass the flag) to keep the plugin family
alive; only `project`/`local` inclusion should be varied per profile.

## Spike (b): where should per-profile settings overlay files live?

Read `bin/refresh-plugins` (Ruby). It touches exactly these paths, all read-only except
for the plugin cache itself:

- Reads `~/.claude/plugins/known_marketplaces.json` (marketplace list/config)
- Reads `~/.claude/plugins/installed_plugins.json` (which plugins are installed per
  marketplace)
- For each installed plugin under a `directory`-source marketplace, shells out to
  `claude plugin uninstall <plugin>@<marketplace>` / `claude plugin install
  <plugin>@<marketplace>` — this rewrites `~/.claude/plugins/cache/<marketplace>/
  <plugin>/<version>/` (via Claude Code's own plugin manager, not directly) and updates
  `installed_plugins.json`'s install record for that plugin.
- Verifies via `diff -rq` between the cache dir and the plugin's source dir under
  `source_path` (from marketplace config, e.g. `~/dev/cc-os/plugins` or
  `~/dev/cc-plugins`).

It never touches `~/.claude/settings.json`, never touches any file under a
`~/.claude/profiles/` style directory, and never touches arbitrary `--settings <file>`
overlays — its blast radius is strictly `known_marketplaces.json`,
`installed_plugins.json`, and the `plugins/cache/<marketplace>/<plugin>/` tree.

**Recommendation:** put per-profile settings overlay JSONs at `~/.claude/profiles/*.json`
(e.g. `~/.claude/profiles/cc-os-design.json`, `client-dev.json`, `brainstorm.json`),
passed via `claude --settings ~/.claude/profiles/<name>.json`. This path is structurally
disjoint from everything `refresh-plugins` reads or writes (`plugins/cache/`,
`plugins/known_marketplaces.json`, `plugins/installed_plugins.json`) — there is no
plausible future edit to `refresh-plugins` that would need to reach into
`~/.claude/profiles/`, since that script's whole job is cache-vs-source verification for
marketplace-installed plugins, not settings resolution.

Interaction with `enabledPlugins`: `--settings <file>` is merged with (not a full
replacement for) the resolved settings from the sources selected by `--setting-sources`
(per spike (a), keep `user` in the source list so the base `~/.claude/settings.json`
`enabledPlugins`/hooks/env still apply). The profile overlay should therefore only need
to express a *diff* — an `enabledPlugins` map with the profile's unwanted plugins set to
`false` (or, if this repo prefers positive lists, the full set with only the
wanted ones `true`) — rather than duplicating the whole settings file. This diff-only
overlay is exactly what B2 should generate per profile. One caution to carry into B2:
verify at build time whether CC deep- or shallow-merges the `enabledPlugins` object
across `--settings` sources (not tested in this spike) — either way, a plugin disabled
via the overlay's `enabledPlugins: {"name": false}` does not require touching
`known_marketplaces.json` or `installed_plugins.json`, since `enabledPlugins` toggles are
independent of the marketplace/install-record identity those files hold (the files
`refresh-plugins` owns).

**Verdict (b):** `~/.claude/profiles/*.json` (passed via `--settings`) is safe — it lives
entirely outside the three paths `refresh-plugins` reads/writes/rewrites
(`known_marketplaces.json`, `installed_plugins.json`, `plugins/cache/`), and
`enabledPlugins` toggles in an overlay are orthogonal to the marketplace/cache identity
`refresh-plugins` verifies, so cache refreshes and profile overlays can never clobber
each other.