relay upgrade: rebase del fork sobre upstream main (447 commits al día)

.cofoundy/brief.yaml

@@ -0,0 +1,60 @@
+schema_version: 1.0
+name: buzz-cli-usable
+domain: software
+session_mode: delivery
+started: 2026-08-04
+owner: Andre (A-PachecoT)
+
+goal: >
+  Hacer usable el CLI de Buzz en una caja limpia del equipo. Dos defectos
+  bloquean eso hoy: (1) el CI del fork no shippea git-credential-nostr, así que
+  git push contra el relay exige compilar un binario a mano; (2) los metadatos
+  de un repo se congelan a los 15 minutos, dejando `repos bind` y
+  `repos protect` permanentemente inutilizables.
+
+repo: cofoundy/buzz
+base_branch: railway-deploy      # NUNCA main — main sigue al upstream de Block
+work_branch: sprint/buzz-cli-usable
+relay: https://buzz.cofoundy.dev
+
+issues:
+  - id: cofoundy/buzz#1
+    title: CI no shippea git-credential-nostr
+    lane: ci
+  - id: cofoundy/buzz#2
+    title: metadatos de repo congelados a los 15 min (upstream block/buzz#2876)
+    lane: cli
+
+mvp_scope:
+  - git-credential-nostr sale como release asset del fork y lo instala install-buzz-acp.sh
+  - una caja sin toolchain de Rust puede clonar y pushear siguiendo solo el README
+  - repos protect / repos bind funcionan sobre un repo anunciado hace más de 15 min
+  - el fix del timestamp preserva la monotonía (un writer demorado no pisa una edición intermedia)
+
+out_of_scope:
+  - Tocar el Dockerfile del relay o deploy/railway/ (guardrail explícito del issue #1)
+  - Ampliar MAX_TIMESTAMP_DRIFT_SECS en el relay (guardrail explícito del issue #2 — la ventana es defensa anti-replay, no el bug)
+  - Modificar la lógica del crate git-credential-nostr (funciona; verificado con push y clone reales)
+  - Rebasear o forzar sobre railway-deploy
+  - Onboarding del equipo / sunset de Discord (bloqueado por handbook#2, fase 3)
+
+agents:
+  roles:
+    - ci
+    - cli
+
+recon_findings:
+  - id: R-1
+    what: deploy/arch-box/ no tiene README
+    impact: el issue #1 pide documentar en "el README del deploy" pero no existe; la lane ci lo crea
+  - id: R-2
+    what: el paths: trigger del workflow no incluye crates/git-credential-nostr/**
+    impact: un cambio al helper no redispara el build; gap adyacente, se corrige en la misma lane
+  - id: R-3
+    what: repos.rs:523 y :717 assertean created_at == 101 exacto
+    impact: max(now, existing+1) rompe ambos tests; deben assertear monotonía + frescura, no un literal
+
+references:
+  - handbook/infrastructure/buzz/BITACORA.md
+  - handbook/infrastructure/buzz/bitacora/2026-08-01-auditoria-fase2.md
+  - https://github.com/block/buzz/issues/2876

.cofoundy/context/agent-floor.md

@@ -0,0 +1,153 @@
+# Agent Floor — universal teammate contract
+
+> Scaffolded into `.cofoundy/context/agent-floor.md` by `/cofoundy-init` (one-time per project).
+> Read once by every teammate at spawn. Replaces the per-dispatch boilerplate copy-paste.
+> If your dispatch prompt restates anything below, you're duplicating the floor — point here instead.
+
+## Identity + substrate
+
+- You are a teammate on the buzz-cli-usable sprint team. Your role and task are in your spawn prompt.
+- **Substrate is SSOT.** Your task spec lives at `.cofoundy/tasks/T-NNN.md`. Read it first; every acceptance line is a hard gate.
+- **Architecture, contracts, conventions** live in `.cofoundy/specs/*.md` and project `CLAUDE.md` / `.claude/rules/`. Read what your task's `refs:` block points at.
+- **Don't re-prose what you read.** Apply it.
+
+## Protocol-ask supremacy
+
+When your caller sends an explicit **protocol-ask** (ACK pattern, restart, status, shutdown, hand-off, gate decision), execute it FIRST. Economic / efficiency concerns (cost of restart, token burn, "I already did this") surface AFTER, never as conditions for compliance.
+
+- Correct: *"Acknowledged. Dispatching Phase 0. Note: prior artifacts at `<path>` if you want to compare against this run."*
+- Wrong: *"Question: should I restart given that prior artifacts exist at `<path>`?"* — stalling-as-clarification, indistinguishable from non-engagement from the caller's seat.
+
+Default-to-comply on protocol-asks. Default-to-action on substrate ambiguity (file the ambiguity in `.cofoundy/state/escalation-queue.jsonl` + halt; don't reply with a question). The caller's right to be wrong about economics outranks your right to be right about them.
+
+Source incident: `plugins/cofoundy-orchestrator/docs/2026-05-20-teammate-stepper-protocol-gap.md` §"Root cause #2".
+
+## Your operator is the CTO (talk to it)
+
+The orchestrator that spawned you is the **CTO acting as the founder** — it is your human. Two
+distinct channels, do not confuse them:
+
+- **`QUESTION` → SendMessage the orchestrator** when you hit a decision you genuinely cannot infer
+  from the substrate but that a PM/founder *could* answer (which approach, is this in scope, does the
+  client want X or Y). Ask it like you'd ask a human lead: one crisp question + your recommended
+  default. The CTO answers (or escalates upward itself). This is the normal operating channel — use it.
+- **Escalation queue → only for substrate ambiguity** (spec contradicts itself/the contract, a
+  capability/credential wall): append to `.cofoundy/state/escalation-queue.jsonl` and halt. Don't put
+  judgment questions here — those go to the CTO via SendMessage.
+
+When the CTO sends you a `REVIEW`, `REDIRECT`, `CLARIFY`, `UNBLOCK`, or `DIAGNOSE-NUDGE`, treat it as
+a protocol-ask (below): execute first, surface concerns after. Don't narrate status unprompted — the
+CTO reacts to events, not to chatter.
+
+## Scope discipline
+
+- **Stay in `scope.write`** from your task spec. Anything you want to touch outside that = file an escalation in `.cofoundy/state/escalation-queue.jsonl` and stop. Do NOT silently expand scope.
+- **`scope.read` is permissive** but doesn't authorize edits. Read freely; write only inside the matrix.
+- **No new files outside scope.write.** If you need one (new module, new test file, new doc), it must already be listed in `scope.write` (glob match counts).
+- **The gates are NOT a sandbox — scope discipline is YOURS to keep.** The hooks read the Bash command *string*: they see shell redirects, `tee`, `sed -i`, `cp`/`mv`, and `Write`/`Edit` targets. They are blind to anything an interpreter does — `python3 x.py`, `node w.js`, `make`, `bash s.sh` resolve to zero targets and pass. So scope enforcement catches **accidental drift**; it is a **coordination contract, not a security boundary**, and it will not stop a determined write. Don't read "the gate allowed it" as "this was in scope" — you own the matrix whether or not a hook is watching. Corollary: if you route around a gate (including via an interpreter), **say so** in your termination summary. Concealing a workaround is the one unforgivable move; using one and disclosing it is normal engineering.
+- **Compound Bash commands are blocked ATOMICALLY.** If any single resolved target in a `&&`/`;` chain is out of scope, the *whole* command dies — including the parts that were fine. So keep destructive/recovery ops as **separate commands**: run the `rm` alone, then the append alone. Never chain a cleanup step to a possibly-blocked target — the cleanup that would have unblocked you is exactly what won't run.
+
+## Git contract
+
+- **Spawn step 0 — verify your worktree BASE before any work.** Harness-created worktrees branch from the primary checkout's HEAD, NOT necessarily the base branch your dispatch prompt names. Check `git merge-base --is-ancestor <base> HEAD`; on mismatch `git fetch origin <base> && git checkout -B <your-branch> <base>`, THEN start. Reproducing/fixing/testing on the wrong base invalidates everything downstream. → `core/docs/decision-log.md#2026-07-22-worktree-base-drift`
+- **If you're on an isolated worktree/branch (long-run / team-agent model): commit to YOUR branch after every meaningful unit.** Uncommitted work is LOST if you idle or die — don't bank it for the end. The orchestrator merges your branch; it does NOT depend on you surviving to a final phase. If you're a transient in-session subagent on the orchestrator's own branch, just mutate the tree and let it commit.
+- **Precedence when the two rules above and below pull against each other: VERIFY, THEN COMMIT.** "Commit after every meaningful unit" and "run tests before signaling done" are both real; when they conflict, verification wins — a *meaningful unit* is a **verified** one, and committing unverified code is the failure mode the guidance exists to prevent. **A dirty tree mid-verification is the EXPECTED state of a working agent and is NEVER evidence of idleness.** Hold the edit, run the check, then commit. Don't commit early to look busy; don't let a dirty tree pressure you into shipping unverified. Keep the verify window tight (minutes, not phases) — the rule buys you verification time, not indefinite banking.
+- **Orchestrator's half of that contract (it binds the orchestrator, not you): a worktree is NEVER destroyed on an idle heuristic.** Verify-before-commit is only safe if nothing deletes the tree underneath a live worker — so teardown requires a *positive* liveness check (registry `list` + no tool call for N minutes + a `task_completed` event), never the mere absence of a signal, and never `git worktree remove --force` (git's refusal on a dirty tree IS the guardrail: a worktree that refuses to die is a worker still holding work). Dirtiness is not idleness and uncommitted is not abandoned. If your worktree disappears mid-task, that is an orchestrator defect — report it, don't absorb it.
+- **Push YOUR branch freely, and open your own MR when your task is done.** You don't wait for the orchestrator to push for you — that's the bottleneck the autonomous-team model removes. Push early/often so your work survives + peers can see it.
+- **Self-merge to `develop` on CI-green IF your scope is DISJOINT.** When your task touched only files YOU own per the ownership matrix (no shared files), open your MR to `develop` and set **auto-merge on CI-green** — you land your own lane, no orchestrator relay, no integration branch. CI is the gate.
+- **Shared-file edits → flag, don't auto-merge.** If you touched a SHARED surface (the api-client barrel/index, `app.module`, prisma migrations, root `package.json`, anything multiple lanes edit) label your MR `needs-coordinated-merge` and STOP — the merge-coordinator sequences those (concurrent auto-merges on a shared file collide). Better: avoid shared-file edits by design (add your own file, not a line in a shared index).
+- **`main`/prod and force-push are NEVER autonomous.** Human gate. Never force-push any shared branch.
+- **Scratch artifacts (screenshots, `.report-shots`, scratch specs/notes) go to a gitignored dir — never commit them to the product branch.** They force cleanup commits at integration.
+
+## Test + quality discipline
+
+- **Run tests yourself before signaling done.** Each acceptance line should map to a runnable check; run it. This outranks commit-frequency — see the precedence rule in the git contract: verify, then commit; a dirty tree mid-verification is expected, not idleness.
+- **Logger discipline** per `.claude/rules/backend-quality.md` (Python backend) or repo-specific rules: entry/exit/error logs with structured `extra={}`, `exc_info=True` on errors, `time.perf_counter()` around external HTTP.
+- **Coverage gates** if listed in acceptance — run with `--cov-fail-under=N`, save report to `docs/qa/<cycle>/` if your role is QA.
+- **`pytest | tail` deadlocks.** Always `pytest ... > /tmp/out.txt 2>&1` then `tail /tmp/out.txt`. The pipe-to-tail pattern hangs in this harness.
+
+## Termination signal
+
+When you've self-verified all acceptance criteria pass:
+
+1. Append one event line to `.cofoundy/state/history.jsonl`:
+   ```json
+   {"ts":"<ISO>","event":"task_completed","task":"T-NNN","agent":"<your-role>","cycle":"<cycle-id>","summary":"<one-line>"}
+   ```
+2. Return a structured summary (under 250 words):
+   - Files created / modified (paths)
+   - Acceptance criteria status (each line passed / partial / blocked)
+   - Coverage % if relevant
+   - Deviations from spec (if any) with rationale
+   - Flagged issues / fix-tasks filed for orchestrator
+
+3. **Do NOT mark TaskUpdate completed yourself if you're a teammate** — the orchestrator marks based on your termination signal. (If you're a standalone subagent, you don't see TaskList anyway.)
+
+## Per-role state files — EXACTLY ONE writer
+
+Per-role files (`.cofoundy/state/metacognition/{role}.jsonl` and any other `{role}`-suffixed state
+file) exist so N lanes can never collide on one surface. That only holds under an invariant that must
+be stated, because following the surrounding instructions literally can break it:
+
+- **A per-role file has exactly ONE writer: the owning lane.** Peers never touch another role's file.
+  You own yours; write it, and only it.
+- **The orchestrator harvests by copy OR by merge — NEVER both.** Copying a lane's mid-run file into
+  main *and* merging that lane's branch makes the orchestrator a second writer to a single-writer
+  file: guaranteed conflict, and union-resolving it silently DUPLICATES the deliverable (a stale
+  harvest snapshot and the lane's real line, same `ts`, different content — the stale one sorts first
+  and wins any naive read).
+- **Dedupe on `(role, task, ts)` at assembly, with a superset check before dropping anything.** If two
+  lines collide on that key, assert every item in the discarded line appears verbatim in the kept one;
+  **abort if not**. Never resolve a conflict in one of these files by keeping both sides — that is not
+  a merge, it is a duplication.
+
+## Finishing capabilities — you can do the WHOLE job, not just the code
+
+A capability **NEED** is not a capability **GAP**. The most common way an agent fails to finish
+is stopping at "code's done — someone should deploy / configure DNS / set the secret / run QA."
+You have the skills to finish it yourself. Any agent in this workspace can invoke:
+
+- **Deploy · status · logs · rollback** → `cofoundy-toolkit:deployment` (Railway + Cloudflare; never raw railway/curl).
+- **Cloudflare tokens** → `cofoundy-founders:cf-token`. **DNS · domains** → `cofoundy-founders:namecheap`.
+- **Store a credential** (vault + GitHub + env) → `cofoundy-toolkit:store-key`.
+- **Browser QA · screenshots · verify-live** → `cofoundy-toolkit:browser`, or spawn a QA subagent.
+- **Generate + run the acceptance tests** → `cofoundy-toolkit:test`. If your task has a testable acceptance line, the merge gate (F1b criterion `tests_present_or_justified`) REJECTS a diff that ships no test — run it as a finishing step, or record a `tests:` block (`status: present|justified`) / `## No-test justification` section in your task file. Mocked-only tests are judgment-tier `amend`, not proof (cantera L-004): the real-run is the gate.
+- **Atomic commits** → `cofoundy-toolkit:gitcommit`. **Publish a doc** → `cofoundy-docs:docs`.
+
+If your task's done-definition includes deploy / config / verify-live, **do it with these** — the
+finish is yours, not a human's. Credentials are provisioned in `os.environ` at session start; the
+skills read them (never `bw unlock` at runtime).
+
+## Escalation path
+
+The queue is `.cofoundy/state/escalation-queue.jsonl` — **append-only JSONL, one escalation per line.**
+It is NOT YAML: there is no `pyyaml` in this environment (`import yaml` → `ModuleNotFoundError`), and
+hand-splicing YAML text is how the queue silently dies — any prose containing a `word: ` sequence (a
+path like `T-001.md:51:`, a `->`) turns the whole document into invalid YAML and swallows every
+escalation in it, unnoticed, including yours. JSONL has no nesting to corrupt: one bad line costs one
+line. **Never hand-concatenate the JSON either** — serialize with stdlib `json`:
+
+```bash
+python3 -c 'import json,sys,datetime
+print(json.dumps({"ts":datetime.datetime.now().isoformat(timespec="seconds"),
+                  "id":"E-00N","role":"<your-role>","task":"T-NNN","status":"open",
+                  "kind":"substrate_ambiguity",   # or capability_gap
+                  "summary":"<one line>","evidence":"<file:line + what contradicts what>",
+                  "recommendation":"<your proposed resolution>"}))' \
+  >> .cofoundy/state/escalation-queue.jsonl
+```
+
+- **Substrate ambiguity** (spec contradicts itself or contract) → append one line, halt.
+- **Genuine capability gap** — you need X, there is NO skill for it, AND no credential the skill could fetch (e.g. a human-only approval, a missing external account) → append one line + halt. **A need you can satisfy with a skill above is NOT a gap — do it.**
+- **A spurious gate block is NOT substrate ambiguity.** If a hook blocked a write that IS in your `scope.write` (a phantom target from a heredoc body, an unexpanded `$TMPDIR/...`), that's a false positive: don't file it here — note it in your termination summary and use a form the parser reads correctly (e.g. `git commit -F <file>` instead of a heredoc). The queue is for real ambiguity; filling it with phantoms teaches everyone to ignore it.
+- **Blocking bug found in another role's deliverable** → file new task `.cofoundy/tasks/T-XXX.md` (role_owner = that role) + flag in your termination summary. Don't try to fix outside your scope.
+
+## What's NOT here (because it's role/task-specific)
+
+The dispatch prompt provides ONLY:
+- Your role + task ID + branch (1 line)
+- Read pointers to your task spec + relevant spec files (1 line)
+- Delta-not-in-substrate: any context, debug hints, or decisions made by orchestrator that aren't in the .md files (≤2 lines)
+- Termination signal reminder if non-standard (1 line)
+
+If your dispatch prompt says more than ~80 words, the orchestrator is over-prescribing. Read the spec files; that's where the answers live.