docs(workplans): add CYA-WP-0007 shell session and CYA-WP-0008 llm-connect

Define interactive cya shell mode with opt-in shell history, State Hub
orientation, session learning, and weakness hints. Pair with llm-connect
adapter integration for production multi-turn assistance.

workplans/CYA-WP-0008-llm-connect-adapter-integration.md

@@ -0,0 +1,161 @@
+---
+id: CYA-WP-0008
+type: workplan
+title: "llm-connect Adapter Integration for Production Assistance"
+domain: capabilities
+repo: can-you-assist
+status: ready
+owner: grok
+topic_slug: foerster-capabilities
+created: "2026-06-22"
+updated: "2026-06-22"
+---
+
+# CYA-WP-0008: llm-connect Adapter Integration
+
+## Goal
+
+Replace `FakeLLMAdapter` on production code paths with a real **llm-connect** client
+behind the existing `LLMAdapter` Protocol, so one-shot `cya "..."` and `cya shell`
+(CYA-WP-0007) can deliver genuinely useful multi-turn assistance.
+
+Preserve the seam: `cya` never hard-codes a vendor; all provider config lives in
+llm-connect. Credential routing via `warden route` before requesting secrets.
+
+## Background & References
+
+- **Seam:** `src/cya/llm/adapter.py` — `LLMAdapter` Protocol + `FakeLLMAdapter`
+- **INTENT.md:** `cya` asks; `llm-connect` reaches infrastructure
+- **SCOPE.md:** real client listed as explicit out-of-scope / future work
+- **CYA-WP-0007:** REPL usable with fake adapter for scaffolding; quality needs this slice
+- **Credential routing:** `AGENTS.md` / `warden route find` — no secrets in repo
+
+## Non-Goals
+
+- Provider-specific UI inside `cya` (model picker beyond minimal config)
+- Token billing dashboards or cost analytics
+- Embedding / RAG pipelines
+- Bypassing `LLMAdapter` Protocol for any production path
+
+## Dependencies
+
+- **llm-connect** package/API stability (coordinate with that repo owner)
+- Operator-provided credentials via OpenBao paths surfaced by `warden route`
+- CYA-WP-0007 T05 can proceed in parallel using `FakeLLMAdapter`
+
+## Task Breakdown
+
+### T01 — Adapter contract review and llm-connect API survey
+
+```task
+id: CYA-WP-0008-T01
+status: todo
+priority: high
+```
+
+Document mapping from `AssistanceRequest` / `AssistanceResponse` to llm-connect calls.
+Identify config surface (TOML keys, env vars). Note gaps requiring llm-connect changes.
+
+**Acceptance criteria:**
+- Short integration note in `docs/` or workplan appendix.
+- Credential route catalog id(s) documented via `warden route find`.
+
+### T02 — Implement `LLMConnectAdapter`
+
+```task
+id: CYA-WP-0008-T02
+status: todo
+priority: high
+```
+
+New class in `src/cya/llm/` implementing `LLMAdapter`:
+
+- Delegates to llm-connect client
+- Graceful degrade message when llm-connect unavailable / misconfigured
+- `FakeLLMAdapter` remains for tests and `--offline` mode
+
+**Acceptance criteria:**
+- Protocol-compliant; swap via config or env (`CYA_LLM_ADAPTER=connect|fake`).
+
+### T03 — Configuration and developer ergonomics
+
+```task
+id: CYA-WP-0008-T03
+status: todo
+priority: medium
+```
+
+- `~/.config/cya/config.toml` `[llm]` section (backend, model hints)
+- Document `warden route` steps in README
+- `make dev-install` optional extra `[llm]` dependency group if needed
+
+**Acceptance criteria:**
+- Operator can configure adapter without editing source.
+- No secrets committed; example config uses placeholders.
+
+### T04 — Orchestrator and shell integration
+
+```task
+id: CYA-WP-0008-T04
+status: todo
+priority: high
+```
+
+Wire `handle_request()` and CYA-WP-0007 shell turns to adapter selection:
+
+- Default fake when unconfigured (current behavior)
+- Real adapter when config present
+- Multi-turn context: pass recent session turns in `AssistanceRequest.context`
+
+**Acceptance criteria:**
+- One-shot and shell paths use same adapter factory.
+- Session context bounded (token/line budget documented).
+
+### T05 — Tests and offline CI strategy
+
+```task
+id: CYA-WP-0008-T05
+status: todo
+priority: high
+```
+
+- Mock llm-connect for unit tests (no live API in default `make test`)
+- Optional integration test marker `@pytest.mark.llm_live` for manual runs
+- Fake adapter remains default in CI
+
+**Acceptance criteria:**
+- `make test` passes without network or API keys.
+- Live test documented for operator manual verification.
+
+### T06 — Documentation and SCOPE update
+
+```task
+id: CYA-WP-0008-T06
+status: todo
+priority: medium
+```
+
+Update README, SCOPE.md (remove "only FakeLLMAdapter" where accurate), AGENTS.md.
+
+**Acceptance criteria:**
+- Clear "configured vs offline" operator paths documented.
+
+### T07 — Register, sync, and handoff
+
+```task
+id: CYA-WP-0008-T07
+status: todo
+priority: low
+```
+
+`make fix-consistency`, progress event, coordinate with llm-connect repo if API gaps found.
+
+## Success Criteria
+
+- Configured `cya` uses llm-connect for real inference.
+- Unconfigured / test environments behave exactly as today (fake adapter).
+- CYA-WP-0007 shell session becomes practically useful once both workplans complete.
+
+---
+
+**Status note:** `ready` on 2026-06-22. Can start T01–T03 in parallel with CYA-WP-0007 T02–T04.