From e0eb3c2d1b136878cbe33e4b63c8ef0296615f0b Mon Sep 17 00:00:00 2001 From: AJ Date: Thu, 2 Jul 2026 00:35:46 -0400 Subject: [PATCH] =?UTF-8?q?docs:=20add=20HANDOFF.md=20=E2=80=94=20backlog?= =?UTF-8?q?=20workflow=20for=20local=20agent=20+=20Gitea=20supervision?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- HANDOFF.md | 86 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 86 insertions(+) create mode 100644 HANDOFF.md diff --git a/HANDOFF.md b/HANDOFF.md new file mode 100644 index 0000000..9f09b08 --- /dev/null +++ b/HANDOFF.md @@ -0,0 +1,86 @@ +# HANDOFF — BCC feature backlog implementation + +For the Claude Code agent working in this repo. Read this whole file, then +CLAUDE.md, before touching code. A supervising Claude session watches this +project through the Gitea MCP (issues, PRs, CI runs on git.avezzano.io), so +keep all state in Gitea where it can be seen: issues for work items, PRs for +changes, comments for decisions. + +## Step 0 — sync state + +`main` may contain local commits that aren't on origin yet (the previous +session couldn't push). Run `git status` / `git log origin/main..main`; if +there are unpushed commits, **push them first** and confirm CI goes green +before starting anything. + +## Step 1 — file the backlog as issues + +Create one Gitea issue per item in the backlog table below (`tea` CLI or the +API — you have full credentials). Prefix titles with the ID (e.g. +"[#2] Stdio server spawn-test"). Create labels P0/P1/P2 first if they don't +exist. Copy each item's full section from `../bcc-feature-requests.md` +(sibling of this repo folder) into the issue body — it has problem statements, +evidence, proposed fixes, and acceptance criteria. + +**Corrections to that document — do not re-implement:** +- "Doc correction: README Claude Code path" — DONE (commit `b16c0fd`). +- Item 1 (secret masking) — MOSTLY DONE (commit `6dee318`): env/header values + masked via delegate + Show-secrets toggle, Add-dialog password echo, + diagnostics args redaction (`redact_args`). **Only remainder:** the warning + badge when a secret-shaped value sits in `args` instead of `env`. File the + issue scoped to just that. + +## Step 2 — work the backlog + +| Order | ID | Item | Priority | Notes | +|---|---|---|---|---| +| 1 | 2 | Stdio server spawn-test | P0 | Spawn with timeout, capture stderr; core logic in bcc_core (GUI-free, testable) | +| 2 | 3 | Backup restore UI | P0 | List `.bcc_backups/`, preview/diff, restore through normal atomic-write path | +| 3 | 4 | Stale-file protection | P0 | mtime/hash at load, re-check before write, prompt on conflict | +| 4 | 1r | Secret-in-args warning badge | P0 | Remainder of item 1; `is_secret_key`/`_is_secret_value` already exist in bcc_core | +| 5 | 8 | Duplicate-name conflict on paste/import | P1 | VERIFY FIRST: check `paste_json`/`dropEvent` in bcc.py for silent overwrite; file findings on the issue before coding | +| 6 | 5 | Cross-client support (Cursor/Windsurf/VS Code) | P1 | VS Code uses `servers` not `mcpServers` — needs a read/write adapter, not just paths | +| 7 | 6 | In-app MCP log viewer | P1 | Platform log paths in the doc | +| 8 | 7 | Windows MSIX path detection | P1 | Can't test locally on macOS — unit-test the detection logic, note that in the PR | +| 9 | 9 | Restart Claude Desktop button | P1 | Platform-specific process handling; scope to Desktop only | +| 10 | 10 | Server catalog / one-click add | P2 | Design pass first — post a proposal as an issue comment before building | + +## Workflow rules + +- **Branch per issue** off `main`: `feat/-short-slug` (or + `fix/`). One issue per PR. Reference the issue in the PR description + (`Closes #N`). +- **Before every commit:** `python -m pytest` (all green), `ruff check .`, + `ruff format .`. CI enforces all three. +- **Conventional commits** (`feat:`, `fix:`, `test:`, `docs:`, `chore:`) — + match the existing history's style: body explains the why. +- **Merge only with green CI.** If the supervising session has flagged + something on the PR, resolve it before merging. + +## Architecture guardrails (violating these fails review) + +1. **The cardinal rule:** config writes only ever touch `mcpServers` and + `_disabledMcpServers`. Every other key is preserved verbatim, in order. + This matters extra for `~/.claude.json`, which holds conversation history + and project state. +2. **Core/GUI split:** all logic in `bcc_core.py` (no GUI imports, unit- + testable); `bcc.py` stays a thin PySide6 shell. New logic gets tests in + `tests/` — they run without PySide6, keep it that way. +3. **No new runtime dependencies** without posting the justification on the + issue first. PySide6 is currently the only one. +4. **Writes are atomic + backed up** — route any new disk writes through + `write_config()`. +5. Secrets never appear in diagnostics output or logs — use `redact_args`/ + `is_secret_key` from bcc_core. + +## Current state (as of this handoff) + +- 58 tests in `tests/`, ruff clean, CI = lint + pytest (py3.10/3.12) on push/PR. +- Recent features you should know exist: lenient JSON repair + (`repair_json_text`, `parse_pasted_json_verbose`, `repair_config_file` + + RepairDialog), ArgsEdit numbered gutter + `split_suspicious_args`, + resizable splitters with QSettings persistence, secret masking, Claude Code + profile at `~/.claude.json` (settings.json only as "legacy" when it holds + parked servers). +- GUI can't be smoke-tested in CI; note in each PR whether you ran + `python bcc.py` locally and what you checked.