dgf1988/codewhale
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

docs: drop stale handoff/migration/parity docs

Browse Source 
Removed:

- `.claude/next-agent-prompt.md` (111 lines) — v0.4.6-era session prompt
  describing slices A/B/C that have all shipped. Successive sessions use
  fresh prompts (e.g. .deepseek/v0.6.0-overnight-review.md); this one is
  pure history.

- `docs/archive/workspace_migration_status.md` (92 lines) — explicitly
  archived (April 11), describes a one-time migration that's complete.
  Removed enclosing `docs/archive/` directory too (was the only file).
  CHANGELOG entry from v0.4.x still narrates the archival as history.

- `docs/parity_release_and_ci.md` (38 lines) — duplicates what
  `.github/workflows/parity.yml` and CONTRIBUTING.md already say
  authoritatively. Single source of truth wins.

- `AI_HANDOFF.md` + `todo.md` (untracked, no commit needed) — `todo.md`
  was a 7-line pointer to AI_HANDOFF.md, which itself was an April 11
  snapshot listing "remaining work" that's mostly delivered. CLAUDE.md
  is the live developer guide now.

1004/1004 tests still green; no doc/code references broken.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Hunter Bown
2026-04-26 00:27:58 -05:00
parent d6bfcda474
commit ca7ca9f75f
3 changed files with 0 additions and 241 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.claude/next-agent-prompt.md
-111
View File
@@ -1,111 +0,0 @@
You are working in /Volumes/VIXinSSD/deepseek-tui.
Goal:
Continue improving deepseek-tui as a first-class DeepSeek V4 coding harness, building directly on the previous overnight slice (commit f190ab74 + merge aa356e8b + import fix f9ede57c, plus release commit d7944421 / tag v0.4.6). This time, ACTUALLY read /Volumes/VIXinSSD/mathcode — the previous run claimed it wasn't mounted and adapted patterns from the work-order description instead. mathcode IS mounted; the directory exists and is readable.
What already shipped (do not redo):
- Slice A: setup --status, setup --clean (with --force gate), setup --tools, setup --plugins, doctor --json, init_tools_dir / init_plugins_dir scaffolding with frontmatter examples (# name: / # description: / # usage: in tools/example.sh; ----delimited YAML in plugins/example/PLUGIN.md). Code in crates/tui/src/main.rs.
- Slice B: fake-wrapper hostility — TOOL_CALL_START_MARKERS/END_MARKERS + filter_tool_call_delta promoted to pub(crate); FAKE_WRAPPER_NOTICE + contains_fake_tool_wrapper(); per-turn fake_wrapper_notice_emitted flag in handle_deepseek_turn. Code in crates/tui/src/core/engine.rs. Locked by crates/tui/tests/protocol_recovery.rs.
- Slice C: docs in docs/CONFIGURATION.md (Setup status, clean, and extension dirs section + Why the engine strips XML/[TOOL_CALL] text section) and README.md quick-checks block.
- 37 new tests landed (23 unit + 14 integration). All green.
Read first (in this order):
1. AGENTS.md
2. git status --short --branch (expect clean tree on main, 0 ahead of origin/main; a stash from a prior session may exist — leave it alone)
3. README.md
4. docs/ARCHITECTURE.md
5. docs/CONFIGURATION.md (note the new Setup status / extension dirs / Why the engine strips ... sections)
6. docs/RUNTIME_API.md
7. crates/tui/src/main.rs (large file; pay attention to the new run_setup_status, run_setup_clean, init_tools_dir, init_plugins_dir, run_doctor, run_doctor_json helpers — do not duplicate them)
8. crates/tui/src/core/engine.rs (new: TOOL_CALL_START_MARKERS, TOOL_CALL_END_MARKERS, filter_tool_call_delta, FAKE_WRAPPER_NOTICE, contains_fake_tool_wrapper)
9. crates/tui/src/core/engine/tests.rs
10. crates/tui/tests/protocol_recovery.rs
11. crates/tui/src/client.rs
12. crates/tui/src/tui/widgets/mod.rs
13. crates/tui/src/core/capacity.rs (existing compaction decisions — relevant for issue #6)
Then ACTUALLY read mathcode (it IS mounted):
14. /Volumes/VIXinSSD/mathcode/README.md
15. /Volumes/VIXinSSD/mathcode/setup.sh (~10KB; full status/clean/help flag matrix and error messages worth borrowing)
16. /Volumes/VIXinSSD/mathcode/run (763B; thin wrapper that loads .env and dispatches)
17. /Volumes/VIXinSSD/mathcode/.env.example (~6KB; clear provider/backend comments — note our codebase only loads .env via dotenvy::dotenv() in crates/tui/src/main.rs:475 and has no .env.example)
18. /Volumes/VIXinSSD/mathcode/skills/README.md
19. /Volumes/VIXinSSD/mathcode/plugins/README.md
20. /Volumes/VIXinSSD/mathcode/tools/ (list contents; look for self-describing tool scripts)
21. /Volumes/VIXinSSD/mathcode/bin/ (list contents)
Open GitHub issue spine (use as roadmap):
- #6 Coherence as plain-language session health ← previous slice's recommended next step
- #7 Long-session evals for coherence/context handling
- #8 Workspace extraction/runtime seams
- #9 Thread/turn/item protocol stability
- #10 Sandboxing, approvals, server safety
- #11 Skills/plugins/MCP installability and management (partly done; doctor + status now report tools/plugins; install/manage UX still missing)
- #12 DeepSeek API key setup/provider drift (partly done; setup --status surfaces source — but no .env.example, no provider-aware setup wizard)
- #13 Observability for agent quality/coherence events (partly done; fake-wrapper strip emits a status event — coherence ladder still missing)
- #14 Whale/DeepSeek TUI design system
- #15 Thin IDE companions over runtime API
- #16 Public roadmap/docs rewrite
Pick 1-3 high-leverage slices that can be finished and tested tonight. Strongly preferred (in priority order):
Slice 1 (recommended — issue #6 + #13): Plain-language coherence ladder.
- The runtime already emits compaction events (CompactionStarted/Completed/Failed) and capacity decisions live in crates/tui/src/core/capacity.rs.
- Add an Event::CoherenceState variant with a small fixed ladder: Healthy / GettingCrowded / RefreshingContext / VerifyingRecentWork / ResettingPlan.
- Emit it from one place (engine), driven by existing capacity decisions and compaction events. Do NOT add a new background task.
- Surface it in the TUI footer as a single chip (right-aligned, terminal-native, no emoji) and on the runtime API thread shape.
- Snapshot-test the footer chip for each state and unit-test the state transitions from a synthetic capacity event log.
- Land docs in docs/RUNTIME_API.md (CoherenceState shape) and docs/CONFIGURATION.md (footer chip).
Slice 2 (issue #12 + mathcode reference): .env.example + setup wizard messages.
- Adapt /Volumes/VIXinSSD/mathcode/.env.example structure (provider/backend grouping, comment style) to a deepseek-tui .env.example at repo root.
- Cover: DEEPSEEK_API_KEY, DEEPSEEK_BASE_URL (global vs china), DEEPSEEK_MODEL, NVIDIA_API_KEY (NIM), NIM_BASE_URL, RUST_LOG, sandbox toggles.
- Update setup --status to point at .env.example when no .env is found ("Run `cp .env.example .env` and edit").
- Do NOT add a `run` wrapper — dotenvy handles .env loading inside the binary, the wrapper is redundant and introduces drift.
- Lock the .env.example shape with a test that asserts every documented variable is referenced from at least one source file.
Slice 3 (issue #14 / TUI render polish): Whale/DeepSeek design tokens.
- Extract the current TUI color/border/padding choices into a single deepseek_theme module (light + dark variants), without changing any visible output yet.
- Add a snapshot test or two that lock the existing rendering of one plan cell and one tool cell.
- Out of scope for tonight: actually changing colors. Goal is to make a future skin-swap a 5-line change.
DO NOT pick:
- Anything that re-touches NIM provider, V4 reasoning context accounting, or tool-call routing — that work is finished and protected by tests.
- Anything that re-introduces multi_tool_use.parallel.
- Anything that introduces an alternate fake-wrapper code path (XML, [TOOL_CALL], <function_calls>, ```tool_code, ```python, etc.). The engine's contract is: API tool channel only, all five wrapper shapes get stripped + emit a notice.
- Broad rewrites of main.rs, the engine, or the TUI app loop.
- A `run` shell wrapper. (.env loading is already in-binary via dotenvy.)
Hard rules / hostility budget:
- Prompts must never instruct or imply that the assistant should emit XML/markdown/Replit-style fake tool calls. If you touch crates/tui/src/prompts/*.txt, the rule is: API tool channel only, never wrapped tool calls in assistant text.
- Protocol recovery must remain visible. If you change how filter_tool_call_delta or FAKE_WRAPPER_NOTICE works, update crates/tui/tests/protocol_recovery.rs in the same commit and keep at least one assertion that all 5 marker pairs are present.
- UI must stay dense and terminal-native. No emoji, no decorative box drawing for data, no gratuitous color. DeepSeek-specific copy (Whale, V4) is welcome.
- Show, don't hide, runtime problems. New events should be compact (single-line where possible) and machine-readable as structured fields.
Stop rules:
- Do not revert any user/unrelated work; the previous run already merged and pushed (current main HEAD: d7944421, tag v0.4.6).
- Do not push tags or trigger releases. Local commits + push to a feature branch is fine; the maintainer handles release decisions.
- Do not delete or modify the existing stash (if any).
- If a live provider is down/unpaid, use fixtures/mocks and say so explicitly in the report.
- If a gate fails from pre-existing unrelated work, isolate it with evidence — don't paper over.
- Pre-existing test cluster (8 tests in tools::git*, tools::diagnostics, tui::ui::tests::workspace_context_refresh*) fails because of a sandbox commit-signing issue with `git commit ... -S`. Document but do not "fix" by globally setting commit.gpgsign=false — fix narrowly inside init_git_repo at crates/tui/src/tui/ui/tests.rs:158 if you touch it.
Required verification before final report:
- cargo fmt --all -- --check
- cargo check --workspace --all-targets --locked
- cargo test --workspace --all-features --locked
- cargo clippy --workspace --all-targets --all-features --locked -- -D warnings
- cargo build --release --locked -p deepseek-tui-cli -p deepseek-tui
Live smoke (optional, time-boxed at 60s):
- If DEEPSEEK_API_KEY or NVIDIA_API_KEY is set in the env, run a single bounded turn against the relevant provider with a hard token cap and report the first 30 lines of output. Otherwise skip and say so.
Final report headings (use exactly these):
1. Summary
2. Implemented Changes
3. GitHub Issues Advanced
4. MathCode Reference Points Used (be honest: list which mathcode files you actually read and which patterns you adapted vs deliberately skipped, with one-sentence rationale per skip)
5. Tests/Gates
6. Live Smoke Result
7. Remaining Risks
8. Next Best Slice
docs/archive/workspace_migration_status.md
-92
View File
@@ -1,92 +0,0 @@
# DeepSeek Workspace Migration Status
This document is a historical snapshot of the initial workspace migration implementation for Linear issues `SHA-1554` to `SHA-1568`.
It is not maintained as a live status board. Some items below describe work that was still in progress at the time this patch landed and may no longer reflect the current codebase. For current behavior, use the active docs in `docs/` and the current source tree.
## Implemented in the initial patch
- `SHA-1554`:
- Root converted to Cargo workspace.
- New crate boundaries added:
- `crates/core`
- `crates/cli`
- `crates/app-server`
- `crates/protocol`
- `crates/config`
- `crates/agent`
- `crates/tui`
- `crates/tui` (TUI binary pointing at monolith source)
- Stable entry binaries now follow `cli` + `app-server` + `tui` split.
- `SHA-1555`:
- Added `deepseek-config` crate with `ConfigToml` schema.
- Added provider-aware env precedence (`DEEPSEEK_API_KEY`, `OPENAI_API_KEY`, provider/base-url/model overrides).
- Added config read/write/list/set/unset operations.
- `SHA-1556`:
- Added codex-style command grouping in `deepseek` CLI:
- `run`
- `auth`
- `config`
- `model`
- `app-server`
- `completion`
- Added global runtime override flags (`provider`, `model`, logging/telemetry/output/sandbox/approval controls).
- `SHA-1557`:
- Added dual-provider auth model (`deepseek` + `openai`) with clear precedence and CLI management commands.
- Added `auth status|set|clear` command flow.
- `SHA-1558`:
- Added `deepseek-protocol` crate with `thread/app/prompt` request-response framing and event frames.
- Added `deepseek-app-server` with `/thread`, `/app`, `/prompt`, `/healthz`.
- Added `/tool`, `/jobs`, and `/mcp/startup` transport endpoints for tool/job/MCP parity flows.
- Added stdio JSON-RPC 2.0 parity framing (`id`/`method`/`params` -> `result`/`error`) for `thread/*`, `app/*`, `prompt/*`, plus `healthz`/capabilities handlers.
- `SHA-1560`:
- Added `deepseek-agent` model/provider registry with alias resolution and fallback strategy.
- `SHA-1564`:
- Added `deepseek-tui-core` event-driven state machine scaffold (`UiState::reduce`).
- Expanded reducer with job/approval states and deterministic snapshot support.
- `SHA-1559`:
- Added `deepseek-state` crate with persistent thread/session metadata in SQLite.
- Added thread list/read/archive/unarchive/name persistence operations and session index mirror.
- `SHA-1561`:
- Added `deepseek-tools` crate with typed tool specs, call lifecycle, mutating gate, timeout handling, and read/write lock parallelism model.
- `SHA-1562`:
- Added `deepseek-mcp` crate with server lifecycle events, qualified tool naming, filter support, resource listing/reads, and proxy call API.
- Added MCP stdio JSON-RPC 2.0 server mode parity for `tools/list`, `tools/call`, `resources/list`, `resources/read`, and server lifecycle operations.
- Added persisted MCP server definition round-trip through existing config APIs so server-mode definitions survive restarts.
- `SHA-1563`:
- Added `deepseek-execpolicy` crate with approval mode model and policy decision/requirement evaluation.
- `SHA-1565`:
- Added durable-style `JobManager` abstraction in core for queue/progress/cancel/recovery semantics.
- `SHA-1566`:
- Added `deepseek-hooks` crate with stdout/jsonl/webhook sinks and standardized lifecycle events.
- `SHA-1567`:
- Added parity tests for protocol/state/tools and TUI snapshot behavior.
- `SHA-1568`:
- Added parity CI workflow at `.github/workflows/parity.yml` with workspace fmt/check/clippy/test gates, lockfile drift guard, and explicit snapshot/protocol/state parity tests.
- Added matching release preflight parity gates in `.github/workflows/release.yml`.
- Updated release artifact naming to include explicit `deepseek` entrypoint compatibility.
## Open items at the time of the initial patch
- Codex-level protocol field-by-field parity for every `thread/*` operation remains in progress.
- MCP transport now provides stdio JSON-RPC compatibility flows; external subprocess execution remains scaffolded.
- Execution policy supports decision modeling and command gating; full user-interactive approval UX remains in progress.
- Background jobs are persisted conceptually at runtime boundary; cross-process recovery orchestration is still in progress.
## Migration strategy note
`crates/tui` intentionally points at existing `src/main.rs` to preserve current behavior while new workspace crates are phased in. This enables incremental replacement without blocking ongoing feature work.
docs/parity_release_and_ci.md
-38
View File
@@ -1,38 +0,0 @@
# Parity CI and release checks
This repository now includes parity-oriented CI checks under `.github/workflows/parity.yml`.
## Workflow coverage
- `cargo fmt --all -- --check`
- `cargo check --workspace --all-targets --locked`
- `cargo clippy --workspace --all-targets --all-features --locked -- -D warnings`
- `cargo test --workspace --all-features --locked`
- TUI snapshot parity test:
- `cargo test -p deepseek-tui-core --test snapshot --locked`
- protocol parity smoke test:
- `cargo test -p deepseek-protocol --test parity_protocol --locked`
- state persistence parity smoke test:
- `cargo test -p deepseek-state --test parity_state --locked`
- lockfile drift guard:
- `git diff --exit-code -- Cargo.lock`
The tag-based release workflow now runs the same parity preflight before building artifacts.
For the full operator-facing publish flow, see [docs/RELEASE_RUNBOOK.md](./RELEASE_RUNBOOK.md).
## Expected contributor flow
1. Treat `crates/tui` as the current runtime source of truth for shipped behavior, even while workspace extraction continues.
2. Update workspace crates (`core`, `app-server`, `protocol`, `state`, `tools`, `mcp`, `execpolicy`, `hooks`, `tui`, `cli`) as needed.
3. Keep protocol and persistence tests green for parity-sensitive changes.
4. Ensure thread/tool/mcp event contracts remain backward-compatible across app-server endpoints.
## Release readiness checklist
- CLI and app-server binaries compile from workspace members.
- Session persistence schema changes include migration-safe SQL updates.
- Protocol changes include test updates in `crates/protocol/tests`.
- New tool/runtime lifecycle behavior includes tests in the crate that owns the implementation, which is frequently `crates/tui` today.
- TUI reducer/runtime changes include deterministic snapshot or integration updates in `crates/tui/tests`.
- Root-level `tests/` is intentionally empty; workspace-executed TUI integration coverage lives under `crates/tui/tests`.
- Release artifacts include `deepseek` (CLI) and `deepseek-tui` (TUI) binaries for all platforms.