feat(shell): add interactive cya shell session (CYA-WP-0007)

Implement the full interactive shell REPL with session persistence,
opt-in capped/redacted shell history, State Hub orientation and
explicit slash-command writes, orchestrator/safety wiring, end-session
learning hooks, weakness hints, docs, and tests.

SCOPE.md

@@ -6,7 +6,7 @@
 
 It allows users to express intent in natural language from the terminal and receive safe, explainable, context-aware assistance while keeping memory, history, preferences, and adaptation under explicit user control.
 
-## Current Status (Post CYA-WP-0004 Packaging & Distribution Slice)
+## Current Status (Post CYA-WP-0007 Interactive Shell Session Slice)
 
 Four implementation slices have been delivered:
 
@@ -16,6 +16,7 @@ Four implementation slices have been delivered:
 - **Profile 0 baseline (post-0003, formalized in CYA-WP-0005 T02)**: The current shipped memory implementation (local JSON + kinds + activation_context + provenance + retrospection helper) is now explicitly documented as **Profile 0** — the stable, high-quality foundation for future self-improving profiles 1–3. See MemoryVision.md for the full baseline description.
 - **CYA-WP-0005 (Agentic Memory Profiles + first self-improvement capability)**: Complete profile model (Profile 0 baseline + detailed definitions + integration plans + Capability Matrix for Profiles 1–3) plus initial **Profile 1** delivery. **CYA-WP-0006** hardened Profile 1 to production quality: guided 1–3 lesson capture with preview in `cya retrospect`, `cya memory reflections`, near-duplicate compaction, and surfacing in responses / `--explain-context`. See MemoryVision.md and `docs/CYA-WP-0006-profile-1-gap-checklist.md`.
 - **CYA-WP-0004 (Dev-Head Install & Release Packaging)**: Reliable installation from development head (`make dev-install`, direct `git+` installs), dynamic versioning via `setuptools_scm`, clean distribution package building (`python -m build` + verification), lightweight release process, and supporting documentation/Makefile.
+- **CYA-WP-0007 (Interactive Shell Session)**: `cya shell` REPL, session JSONL artifacts, optional capped/redacted shell history, read-only State Hub orientation, explicit hub slash-command writes, end-session learning/export, and deterministic weakness hints.
 
 Core capabilities now include:
 - Natural language request handling via clean Typer CLI.
@@ -26,7 +27,8 @@ Core capabilities now include:
 - Automatic memory activation based on working directory/git root.
 - `cya retrospect` for structured reflection and goal setting, with production Profile 1 verbal lesson capture, review (`cya memory reflections`), and compaction.
 - Full developer workflow: dev-head install, testing, building distribution packages, and a documented release process.
-- Transparent, inspectable behavior via `--explain-context`.
+- Transparent, inspectable behavior via `--explain-context` and shell `/explain`.
+- Stateful `cya shell` sessions with local JSONL artifacts, slash commands, optional history context, hub orientation, export, and opt-in learning.
 
 All LLM interaction flows through the documented adapter seam. Memory flows through explicit ports. Packaging and distribution are now first-class concerns with a clear path forward. No production path bypasses the defined boundaries.
 
@@ -39,7 +41,8 @@ All LLM interaction flows through the documented adapter seam. Memory flows thro
 - Orchestration of the request → context → safety → LLM adapter → response pipeline.
 - The stable `LLMAdapter` Protocol and the contract for how `cya` talks to LLM backends.
 - Explicit, now real (persisting) integration with user-controlled memory via `phase-memory` ports.
-- Transparent, inspectable behavior (especially via `--explain-context`).
+- Transparent, inspectable behavior (especially via `--explain-context` and shell `/explain`).
+- Interactive `cya shell` sessions: prompt loop, session state, local artifacts, slash commands, optional shell-history context, hub orientation, export, and end-session learning prompts.
 - User-facing documentation, examples, and safety guarantees for the CLI tool.
 
 ## Does Not Own
@@ -51,7 +54,7 @@ All LLM interaction flows through the documented adapter seam. Memory flows thro
 - Deep repository indexing, embeddings, or large-scale content analysis (explicit non-goal of the first slice).
 - Voice, speech, phone-bridge, or non-terminal interfaces (future work).
 - Production PyPI publishing and automated release CI (documented process and local tooling exist; actual publication is future work).
-- Long-lived conversational REPL or session state (one-shot + very lightweight session only).
+- Hosted, team-shared, or background session state; `cya shell` artifacts remain local and user-owned.
 
 ## Integrates With
 
@@ -80,7 +83,7 @@ See the individual workplans for detailed scope per slice.
 - Deep llm-connect features beyond basic `execute_prompt` delegation (adaptive routing, cost dashboards, structured output schemas).
 - Deep semantic repository understanding or large-scale content analysis.
 - Automatic command execution (even "safe" suggestions) — explicit user confirmation remains mandatory for anything non-safe.
-- Rich multi-turn conversational state beyond lightweight scoped memory + retrospection.
+- Hosted/team-shared shell sessions or autonomous background agents.
 - Cost tracking, token budgeting, or usage dashboards.
 - Team/shared memory or collaboration features.
 - Plugin system or domain-specific extensions.
@@ -93,6 +96,7 @@ See the individual workplans for detailed scope per slice.
 - `cya/safety/risk.py` — the `_RULES` table and `classify()` function (memory-aware).
 - `cya/context/collector.py` — collection functions and ignore policy.
 - `cya/orchestrator.py` — the main coordination entry point.
+- `cya/shell_session.py` — interactive shell runtime, slash commands, session artifacts, optional history, hub orientation, and weakness hints.
 - Packaging & distribution: `Makefile`, `pyproject.toml`, `docs/release-process.md`, and `MANIFEST.in` (first-class concern with registered future work).
 
 ## Success Criteria (Current State)
@@ -101,6 +105,7 @@ A new user or contributor can:
 - Install the latest development code easily (`make dev-install` or direct git+) and use `cya` for realistic tasks after reading the README.
 - Understand exactly what context and memory influenced a response via `--explain-context`.
 - Trust that dangerous actions will never execute without explicit confirmation.
+- Start `cya shell` for multi-turn help, inspect `/explain`, export a redacted session, and opt in explicitly before shell history or session-turn memory is used.
 - Use `cya retrospect` to reflect on usage and set goals that influence future behavior.
 - Build and verify distribution packages locally.
 - See a clear path for how real `llm-connect`, deeper `phase-memory`, and future PyPI releases will integrate.
@@ -109,7 +114,7 @@ Sibling project owners (llm-connect, phase-memory, State Hub) can read the workp
 
 ---
 
-**This SCOPE document reflects the state after CYA-WP-0008 (llm-connect Adapter Integration).**
+**This SCOPE document reflects the state after CYA-WP-0007 (Interactive Shell Session) and CYA-WP-0008 (llm-connect Adapter Integration).**
 
 It remains intentionally narrower than the long-term vision in INTENT.md and MemoryVision.md, but now incorporates significant advances in contextual memory activation, user-driven retrospection/optimization loops, and proper packaging & distribution capabilities.