docs: add HANDOFF.md — backlog workflow for local agent + Gitea supervision
This commit is contained in:
AJ
+86
@@ -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/<issue-number>-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.
|
||||||
Reference in New Issue
Block a user