docs: two POC modes — branch vs standalone scratch project

- pocs.md: define both modes + per-POC assignment (POC-1/2 standalone at
  /workspace/alkgit-pocN, POC-3 branch mode); findings are the
  deliverable, POC source never merges to main
- sdd_process.md: phase 0 + POC Specialist sections cover both modes
- poc-specialist.md: mode determination up front, standalone environment
  section, 'stay in your lane' principle updated
- AGENTS.md: lifecycle status describes the two modes

Verified: none needed (markdown only)
This commit is contained in:
glm-5.3-flash committed 2026-09-19 17:35:58 +00:00
1 parent 4d3ec3cc63
commit b9ab5e4c9e
4 files changed
+88 -15

No files matched your search

+29 -4
View File
@@ -1,8 +1,24 @@
# alkgit POC Plan
POCs live in research worktrees (`.worktrees/research/<task-id>/`) per
sdd_process phase 0, or as scratch experiments outside the main workspace
tree if a worktree isn't available yet. Each POC records: hypothesis,
## POC modes
POCs are not production code — fewer constraints (comments, unwrap, error
taxonomy are all relaxed), and their code never merges to main. Two modes,
chosen by whether the POC touches code in this repo:
- **Branch mode** (POC depends on alkgit code in the repo): create a git
branch off main, do the work there, then **merge the findings into the
research docs** on main and drop the branch — the POC code itself does
not merge.
- **Standalone mode** (POC is independent of alkgit code): a scratch crate
or project at `/workspace/<poc-name>` (e.g. `/workspace/alkgit-poc1`),
outside the repo entirely. Findings are written directly into
`docs/research/` on main.
In both modes the deliverable on main is the findings write-up, not the
POC source. POC source is disposable once findings are recorded.
Each POC records: hypothesis,
method, result (proceed/pivot/block), and what it changes in the research
docs.
@@ -68,4 +84,13 @@ for receive-pack sizing.
POC-1 first (the BiStream/packetline fit is the load-bearing assumption).
POC-2 next (the crux of fetch). POC-3 last (http shape). Each POC updates
the corresponding research doc with results and a proceed/pivot/block note.
the corresponding research doc with results and a proceed/pivot/block note.
## Modes applied to these POCs
- POC-1, POC-2: **standalone mode** — nothing in the alkgit repo exists to
build on yet; run as `/workspace/alkgit-poc1` and `/workspace/alkgit-poc2`.
(If POC-1's bridge turns out to want the workspace deps, it can flip to
branch mode on the repo instead — decide before writing, not after.)
- POC-3: **branch mode** — it exercises alkhttp wiring against this repo's
skeleton; findings merge into `alk-stack.md`, branch is dropped after.