From 93682f9ce65aa8da9348a9ce47d1655930e9b103 Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Mon, 9 Nov 2026 23:38:57 +0000 Subject: [PATCH] Add the Feature workflow and its full-stack change guide MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit docs/feature-changes.md records how cross-layer features (protocol, persistence, server, harness adapters, web proxy, app, fixtures) were built and verified in this session; docs/workflows/feature.md is the reviewed prepare → plan → implement → review → ui-review → land definition that follows it, with a delivery gate for Go, web and app checks. --- docs/feature-changes.md | 79 +++++++++++++++ docs/workflows/feature.md | 201 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 280 insertions(+) create mode 100644 docs/feature-changes.md create mode 100644 docs/workflows/feature.md diff --git a/docs/feature-changes.md b/docs/feature-changes.md new file mode 100644 index 00000000..a6473a6d --- /dev/null +++ b/docs/feature-changes.md @@ -0,0 +1,79 @@ +# Full-stack feature changes + +How a Pipelines feature that crosses layers is built, checked and handed over. +The **Feature** workflow (`docs/workflows/feature.md`) follows this guide; it +records what worked for the chat, terminal, file and discovery features built on +2026-11-08/09 (turn diffs, shell commands and the interactive terminal, the +permanent terminal, Pipelines chat tools, thinking levels, file upload, rename, +move and delete, dismissible commands, connection recovery). + +## Layers and where a feature touches them + +| Layer | Where | Typical change | +|---|---|---| +| Protocol | `internal/protocol/` | New request/frame types in their own file; the `Message` field in `message.go` is additive and `omitempty` so older peers keep working | +| Persistence | `internal/pipeline/` | A new table in its own file with `init…` called from `store.go`; bounded rows; survives restarts | +| Server | `internal/server/` | Handlers in new files named for the area (`chat_*`, `terminal_*`, `home_files_*`), routed from `chat.go`/`websocket.go`; pushed frames to every client watching | +| Harness adapters | `internal/claude`, `internal/codex`, `internal/opencode` | Per-harness mechanism checked against the installed CLI or app-server schema; unsupported means no feature, never a fake | +| Web proxy | `web/serve.mjs`, `web/src/peerRelay.js` | Only for new HTTP paths: authenticated route plus the peer-relay allowlist | +| App | `app/lib/features//` | Small files; Material and Cupertino; reached through the chat's own gateway so multi-machine chats work | +| Fixture | `app/tool/perf/*_fixture.dart`, `app/tool/search_selection_probe_entry.dart` | A `?param=1` option that renders the new states for captures | + +Shared files every feature touches (`message.go`, `chat_hub.go`, `store.go`, +`chat_thread_view.dart`, `perf_fixture.dart`): keep edits there to a few lines +and put the logic in new files. Parallel features then merge with small, +additive conflicts. + +## Rules that held up + +- **Security boundary.** Everything goes through the authenticated `/connect` + websocket. Home-folder access uses `expandHomePath`, `resolveInsideHome` and + `specialFilesystem`; symlinks are operated on, not followed. Internal + endpoints (for example `/mcp`) must not be reachable through the web proxy; + add a proxy test. Typed input, passwords and tokens are never logged or + stored. Credentials never cross machines. +- **Bounds.** Every retained buffer, list and payload has a limit (for example + 1 MiB output, 50 runs, 512 KiB views, 5 notifications a minute) and reports + truncation instead of failing silently. +- **Platform reality.** Check what the installed tools accept (for example + `codex app-server generate-json-schema`, `claude` control requests, + OpenCode's API). Browsers reserve some shortcuts (Ctrl/Cmd+T, Ctrl+Tab); say + which ones work where. +- **Desktop vs phone.** Web themes are pinned to Android, so desktop checks use + `prefersCompactHitTargets` (device platform), not the theme platform. +- **Shared environments.** Never use the production server (127.0.0.1:8080, + web 8083), real chats, the personal Fold, or restart shared services. + +## Verification + +- **Focused tests while editing.** Go: `go test ./internal/ -run `. + App: `cd app && tool/memwatch/full.sh 'test/a_test.dart test/b'` (the whole + path list is one quoted argument) and `tool/analyze.sh`. Web: + `cd web && node --test test/`. Never bare `flutter test`. +- **Scratch end-to-end** for server behaviour: build `./cmd/pipelines-server`, + run it with an isolated `HOME`, a scratch `-db`, `-addr 127.0.0.1:0` (an OS-chosen port) and + `PIPELINES_MDNS=off`, drive it over the websocket, then stop every process. + Real harness runs need credentials; when they are missing, say so rather + than claim them. +- **Rendered evidence** for visible changes: build the full-app fixture once + (`flutter build web --target tool/search_selection_probe_entry.dart --output + build/probe-app`) and capture with `app/tool/capture/` at wide (1400x900) and + narrow (560x1000) sizes, light and dark, Material and Cupertino where + relevant. Open every PNG cited. +- **Known pre-existing failures** (as of 2026-11-09, on untouched main): 44 + tests in `app/test/application/*` (pending launch-update timer) and, under a + `umask 077` shell, `internal/claude` `TestServiceTokenIsPassedOnlyFromAPrivateFile` + and `internal/opencode` `TestStageDiscoveryRequiresPrivateRegistrationBeforeSessionWork`. + The installed server (and so the delivery gate) runs with `Umask 63` + (077), so the gate's Go check sets `umask 022` first. Compare against a + worktree of main before blaming a change. +- **Notes.** Each feature leaves `app/notes/.md` with behaviour, + protocol, limits, security and the exact verification output. + +## Delivery (manager, not the workflow) + +The workflow commits a reviewed candidate; the server's delivery gate checks it +and lands it on main. Deployment is separate and only on request: `./install` +(web and server), a restart only when no chat or run is active, then +`./install --apk` (native build), `./install --macos --publish --flutter +` and `./install --linux --publish`. diff --git a/docs/workflows/feature.md b/docs/workflows/feature.md new file mode 100644 index 00000000..a2fc1db5 --- /dev/null +++ b/docs/workflows/feature.md @@ -0,0 +1,201 @@ +# stage prepare + +```prompt +Prepare this branch for the task; do not implement it. Follow AGENTS.md. Preserve unfinished task edits in a local commit if any; a clean tree is a successful no-op, never an empty commit. Merge current main into this branch, resolving conflicts by keeping both intents and leaving unrelated files untouched. Run `cd app && /Users/alan/development/flutter/bin/flutter pub get` once. Run no test suites. Report HEAD and any task-owned paths. +``` + +```tools +read +glob +grep +edit +shell +``` + +```configs +provider=openai +model=gpt-5.6-luna +retries=1 +timeout=30m +``` + +```checks +none: preparation only; implement runs focused tests and the land delivery gate runs the suites +``` + +```edges +success -> plan +blocked -> #failure +error -> #failure +``` + +# stage plan + +```prompt +Plan the task as one full-stack Pipelines feature using docs/feature-changes.md. Read only the code the task touches. Produce a short plan: the behaviour and acceptance checks; per layer (protocol, persistence, server, harness adapters, web proxy, app, fixture) what changes and in which files, keeping shared files to small hooks; security boundary and limits; how each harness or platform supports it, or that it does not; and the focused tests, scratch end-to-end check and rendered states to capture. Name open questions instead of guessing. Do not edit. +``` + +```tools +read +glob +grep +``` + +```configs +provider=openai +model=gpt-5.6-luna +retries=1 +timeout=20m +``` + +```edges +success -> implement +blocked -> #failure +error -> #failure +``` + +# stage implement + +```limits +{"max_visits":5,"on":["blocked_retryable"]} +``` + +```prompt +Implement the task and plan across every layer it needs, following AGENTS.md, app/AGENTS.md and docs/feature-changes.md. Put logic in new small files; keep shared files to hooks; keep protocol fields additive. Add a fixture option for new rendered states. +Run focused, quiet checks for what you touched (Go package tests, `tool/memwatch/full.sh` with one quoted path list, `tool/analyze.sh`, `node --test` for web changes). For server behaviour run the scratch end-to-end check from the guide and stop every process afterwards. Do not build or capture UI here; ui-review does that. Write app/notes/.md with behaviour, limits, security and the exact verification output, stating what was not tested. +On re-entry fix only the handed-off must-fix findings. Do not commit, push, deploy or restart anything. Use blocked_retryable only for an evidenced transient prerequisite, otherwise blocked. +``` + +```tools +read +glob +grep +edit +shell +``` + +```configs +provider=openai +model=gpt-5.6-luna +retries=1 +timeout=90m +``` + +```checks +none: focused tests and the scratch end-to-end check only; the land delivery gate runs the suites +``` + +```edges +success -> review +blocked_retryable -> implement +blocked -> #failure +error -> #failure +``` + +# stage review + +```limits +{"max_visits":3,"on":["rejected"]} +``` + +```prompt +Review this run's diff against the task, the plan (in history.md) and docs/feature-changes.md. Start from the changed-file list and `git diff --stat`, then read per-file hunks and the code around them. Check correctness across layers, the authentication and home-folder boundary, nothing exposed through the web proxy, no logged or stored secrets or input, bounds on retained data, restart and reconnect behaviour, multi-machine routing through the chat's own gateway, additive protocol changes, harness support claims, Material and Cupertino controls, desktop vs phone behaviour, and meaningful tests including the reported end-to-end check. +Run no suites, builds or captures; ui-review owns rendered evidence. Do not edit or commit. On a revisit inspect only the fixes and new hunks. Return rejected for a concrete must-fix with location, evidence and fix; advisory for non-blocking notes; otherwise success. +``` + +```tools +read +glob +grep +shell +``` + +```configs +provider=openai +model=gpt-5.6-luna +retries=1 +timeout=45m +``` + +```checks +none: read-only review; shell is used only for git status and git diff +``` + +```edges +success -> ui-review +advisory -> ui-review +rejected -> implement +error -> #failure +``` + +# stage ui-review + +```limits +{"max_visits":3,"on":["rejected"]} +``` + +```prompt +Verify the changed UI in a real browser, per app/AGENTS.md, app/tool/capture/README.md and docs/feature-changes.md. Build the full-app fixture once, use the task's fixture option, and interact with every affected state: wide and narrow, light and dark, Material and Cupertino where relevant, including hover, keyboard and focus on desktop. Open every screenshot you cite and save captures and a short report in public/. Use only owned loopback servers and browsers; stop them afterwards. +Run no suites; do not edit or commit. Return skipped only when the change has no rendered effect; rejected for a concrete visual or interaction defect with evidence and fix; blocked for an evidenced capture failure; advisory for non-blocking findings; otherwise approved. +``` + +```tools +read +glob +grep +shell +``` + +```configs +provider=openai +model=gpt-5.6-luna +retries=1 +timeout=45m +``` + +```checks +none: read-only visual review; shell only builds the fixture and captures, the land delivery gate runs the suites +``` + +```edges +approved -> land +advisory -> land +skipped -> land +rejected -> implement +blocked -> #failure +error -> #failure +``` + +# stage land + +```prompt +Commit this run's reviewed change locally and leave a clean candidate. Inspect `git status --short` and the changed-file list; stage only this task's changes and its app/notes entry; check the staged diff (`git diff --cached --stat`, then per file as needed) for unrelated work, secrets and generated artifacts. Create no empty commit: when nothing is staged, report success with a clear note. Commit with a plain imperative subject and report the hash. Do not push, tag, amend, rebase or merge main, and run no suites: the server's delivery gate merges a moved main, runs the checks and lands the candidate. Do not deploy or restart anything. Return blocked with the paths if a clean candidate cannot be produced safely. +``` + +```tools +read +glob +grep +shell +``` + +```configs +provider=openai +model=gpt-5.6-luna +retries=1 +timeout=45m +delivery=true +``` + +```checks +git diff --check main...HEAD +cd "$(git rev-parse --show-toplevel)" && if git diff --quiet main...HEAD -- '*.go' go.mod go.sum; then echo "go: no Go changes since main"; else umask 022 && go build ./... && go vet ./... && go test ./...; fi +cd "$(git rev-parse --show-toplevel)" && if git diff --quiet main...HEAD -- web; then echo "web: no web changes since main"; else cd web && node --test test/; fi +cd "$(git rev-parse --show-toplevel)" && if git diff --quiet main...HEAD -- app; then echo "app: no app changes since main"; else cd app && /Users/alan/development/flutter/bin/flutter pub get >/dev/null && tool/analyze.sh && tool/memwatch/full.sh test; fi +``` + +```edges +success -> #success +blocked -> #failure +error -> #failure +```