Memory
DECISION — greenfield factory architecture (Mike, Sep 3, 2026, ~12:09pm BST; rules design proposal 63b8e328 IN with clarifications). DECIDED: (1) GITHUB CANONICAL — done. Artifacts for customer deployment tweaks deferred to a FUTURE release — explicitly NOT NOW; 'now it's simple, GitHub — done'. (2) INTERNAL CONTROL PLANE: Mike's custom cloudflare-os deployment (already done) = THE CONTROL APP Mike uses. Connections: control app → vibesdk THROUGH A GATEKEEPER (governed aperture); control app → existing sphere deployments via MCP (already working now). (3) The running CONTEXT GATEKEEPER = THE CONTRACTS STORE — vibesdk references contracts from it. (4) A GADGET WORKSPACE with DETERMINISTIC gadget(s) = the vibesdk controller + overall platform controller: controls deployment, contract validation, etc.; likely MULTIPLE gadgets. (5) vibesdk = custom internal-only fork (the factory that deploys the client's DocuClear system, owns the code lifecycle); new repos as separate entities; greenfield — legacy infra (existing sphere deployments, current vibesdk + cloudflare-os instances) untouched, disposition deferred. COMPOSITION NOTES (Perplexity, for the record): controller gadget(s) = deterministic control/validation surface; the first-party deployer worker (composed engine, 11:38am) remains the privileged EXECUTOR for binding taxonomy/secrets_store_secrets/health gating — gadgets control, gatekeeper disposes, worker executes; Cloudflare Workflows remain the durable deploy orchestration (provision→deploy→health-poll→verify→evidence-commit) — gadgets are not durable execution; contract reads from the context-gatekeeper store must be hash-pinned versions matching GitHub canonical. NEXT ACTIONS unchanged: draft Deployer Contract v0.1; then work items — docuclear-vibesdk fork + dedicated internal instance, sphere-core slimmed repo, controller gadget workspace + gatekeeper aperture for vibesdk.
[Update Sep 3, 2026]: [Runtime finding, Sep 3, 2026, ~12:20pm BST — Mike asked the cloudflare-os agent in the docuclear-os deployment what workflows gadgets can build; reported verbatim to the Sphere; status [INFERRED] pending file:line check of gadget-env binding wiring in dc-glassagent]: (1) Gadgets CANNOT run real Cloudflare Workflows — WorkflowEntrypoint is importable, but execution requires a Workflows binding declared at account level via wrangler; gadget environments only receive bindings wired from workspace resources, and no Workflows binding is available. (2) Gadgets CAN emulate durable execution natively: per-step persisted results, retries with backoff, alarm-driven scheduling/resume, live UI status. (3) KEY CONSTRAINT (agent's own caveat): gadget code has NO outbound internet — steps act only on wired-in workspace resources. CONSEQUENCES for the factory architecture: (a) SEAM 3 CONFIRMED — the deploy pipeline (provision→deploy→health-poll→verify→evidence-commit) stays on real Workflows in the deployer-worker estate (precedent d697a59e: Workflows for finite transactional pipelines, DO alarms for steady-state); the controller gadget triggers/supervises/reports only, reaching the factory THROUGH the gatekeeper — requires the controller workspace to carry GATEKEEPER_* service bindings per the workspace binding choreography. (b) STRUCTURAL ENFORCEMENT BONUS — the no-egress rule means the controller gadget physically cannot deploy except via the governed aperture: contract enforcement on the factory becomes a runtime property, not policy. (c) Gadget-native durability still has a role: control-room supervision, status surfaces, scheduling — not transactional pipelines. (d) OPEN QUESTION logged: whether a Workflows binding could ever be wired INTO a gadget env as a workspace resource — deliberately declined for the factory path (aperture purity); possible future capability for in-workspace use cases.
[Update Sep 3, 2026]: [Capability claim, Sep 3, 2026, ~12:23pm BST — Mike]: 'vibesdk can build and deploy workflow workers.' Status [UNKNOWN → verify]: vibesdk-exploration-v1 section B (buildWorkerBindings taxonomy, commit 89c5f3a) lists Workflows bindings in NEITHER the expressible set (assets/DO/KV/D1/R2/vars/migrations/dispatch namespaces/compat flags) NOR the inexpressible set (service bindings, secrets_store_secrets, tail_worker, cron, queues, vectorize, hyperdrive, AI) — a genuine exploration gap. TWO sub-questions: (1) can vibesdk's deploy path declare a workflows binding on a generated worker (file:line check — buildWorkerBindings, wrangler config generation, template manifest schema, sandbox wrangler validation); (2) do workflows bindings function on Workers-for-Platforms dispatch-namespace workers at the PLATFORM level (docs + spike). DESIGN IMPLICATION IF TRUE: durable orchestration becomes a deployable artifact — a per-customer lifecycle workflow worker could ship INSIDE the deployed DocuClear system alongside its contract; privileged duties (platform tokens, evidence-commit, cross-customer ops) stay in the first-party deployer estate regardless — a customer-namespace worker must never hold platform secrets. Verification route: vibesdkexplorer code read first, then extend the spike — deploy a generated workflow worker to the throwaway namespace, create + run a workflow instance end-to-end.
[Update Sep 3, 2026]: [Platform verification, Sep 3, 2026, ~12:30pm BST — Perplexity, official Cloudflare docs]: the workflow-workers claim RESOLVES — 'Workflows cannot be deployed to Workers for Platforms namespaces, as Workflows do not support Workers for Platforms' (Workflows limits docs, updated Jun 2026) [VERIFIED]. vibesdk's deploy path targets a dispatch namespace (wrangler deploy --dispatch-namespace per the Cloudflare vibesdk launch blog) — so vibesdk can BUILD workflow-worker code but CANNOT deploy a functioning workflows binding into the namespace; account-level deploys (export path / first-party deployer worker) CAN carry workflows bindings. CONSEQUENCES: (1) factory orchestration stays account-level in the deployer estate — seam 3 unaffected; (2) the Deployer Contract manifest taxonomy must include workflows bindings for account-level deploys; (3) per-customer ACCOUNT-LEVEL workers hit the 500-scripts-per-account ceiling (Workers limits docs) — not viable at scale; (4) CANDIDATE PATTERN LOGGED — Cloudflare Dynamic Workflows (@cloudflare/dynamic-workflows, MIT, ~300 LoC, open beta May 2026, built on Dynamic Workers open beta Mar 2026, Workers Paid required): ONE account-level workflow worker, tenant workflow code loaded at runtime into V8 isolates via Worker Loader, state in DO Facets, code stored in Artifacts, ~zero idle cost, designed for durable execution of LLM/agent-generated code — the Cloudflare-blessed answer to per-customer durable execution WITHOUT namespace deploys; noted risks: prompt-injection code registration, non-deterministic step code corrupting replay. SPIKE QUESTION stays: docs-vs-reality check — attempt a namespace workflow deploy on the throwaway namespace to confirm the constraint still holds (docs can lag).
[Update Sep 3, 2026]: [MCP PORTAL — design add, Sep 3, 2026, ~12:25pm BST — Mike]: gatekeeper-vibesdk realized as an MCP PORTAL — 'all vibesdk tools get added to it, which we then expose as a gatekeeper'. VERIFIED CONTEXT (Perplexity, official sources): (1) vibesdk has NO MCP (exploration, this morning) — the portal wraps its REST/RPC API surface; (2) Mike's reference checks out — Cloudflare's own managed MCP servers exist (docs inventory, Jul 2026): Workers Bindings server ('Build Workers applications with storage, AI, and compute primitives', bindings.mcp.cloudflare.com/mcp), Workers Builds server, Docs, Observability, AI Gateway et al.; the suite is open source (github.com/cloudflare/mcp-server-cloudflare) so its tool schemas are available as design templates; note these are ACCOUNT-LEVEL builders — consistent with the WfP namespace Workflows constraint; (3) CLOUDFLARE MCP PORTAL REFERENCE ARCHITECTURE (blog.cloudflare.com/enterprise-mcp, Jul 2026): all upstream MCP servers collapse behind TWO portal tools — portal_codemode_search + portal_codemode_execute — the model writes JS calling upstream tools as functions, executed in a Dynamic-Workers sandbox, Access-gated. DESIGN RULINGS PROPOSED (Perplexity, to confirm): (a) the portal IS the gatekeeper aperture for the factory — contract enforcement at execute(), audit event per governed call (amendment 4); (b) LEAST PRIVILEGE — inventory vibesdk's API surface first, expose deliberately per DEPLOYER_CONTRACT version, not blanket 'all tools'; (c) Cloudflare's own MCP servers, if used at all, sit BEHIND the portal as upstreams — one front door; privileged production ops stay with the first-party deployer worker; (d) long-running generation sessions need async tool semantics mapped to work items + run records; (e) the portal must never echo secret values into tool results or audit trails (vibesdk holds per-user secrets in a DO with no lint rule).
[Update Sep 3, 2026]: [FINAL PIECE — contract management topology, Sep 3, 2026, ~12:29pm BST — Mike, composition confirmed with Perplexity]: the CONTRACT MANAGER sits in docuclear-os (the control app) — deterministic gadget surface for the contract lifecycle: author/diff/propose, version bumps, hash-pin computation, evidence snapshotting. WRITES to canonical go through a NEW gatekeeper family member: GATEKEEPER-GITHUB — the governed aperture to the canonical GitHub repos; contract versions + hash-pins merge only through it (approvals-as-clearances, audit per governed call); GitHub's official remote MCP server can sit behind it as an upstream, same portal pattern as gatekeeper-vibesdk. Runtime READS stay with the context gatekeeper serving hash-pinned versions to vibesdk/portal — invariant: served version+hash must match GitHub canonical, evidence snapshot at each referenced version (/contracts/NAME@version.md + hash). BONUS: gatekeeper-github is also the natural home for the agent PR-back path (vibesdk code tweaks returning to GitHub canonical). PATTERN COMPLETE: every external system the platform touches gets a contract + an aperture — sphere (MCP), ingestion, vibesdk (portal), GitHub (portal). New work item queued: gatekeeper-github, contract-first. OPEN: context-gatekeeper ↔ GitHub sync mechanism (CI push on merge vs gatekeeper-mediated mirror).
[Update Sep 3, 2026]: [Repo placement, Sep 3, 2026, ~12:32pm BST — Mike]: GitHub org 'docuclear' CREATED for separation — greenfield factory repos (docuclear-vibesdk fork, sphere-core, gatekeeper-github, controller gadget workspace) live in the docuclear org, separate from the legacy canonical repos under DevmanMikey (dc-glassagent, second-brain-cloudflare, docuclear-sphere-deployment, docuclear-ingestion). gatekeeper-github's policy scope splits accordingly: docuclear org = greenfield write aperture; DevmanMikey repos = legacy track, unchanged governance.
[Update Sep 3, 2026]: [NAMING — factory nomenclature, Sep 3, 2026, ~12:40pm BST — Mike; extends naming ruling 1950f2b5]: (1) Our vibesdk fork/deployment = DOCUCLEAR_FACTORY — 'vibesdk' unqualified now means UPSTREAM cloudflare/vibesdk only; avoids the upstream-vs-fork ambiguity (which the DEPLOYER_CONTRACT v0.1 draft currently has — terms to be updated at commit). (2) REPO PREFIXES: all internal repos prefixed int_, all customer repos prefixed cust_ — GitHub org 'docuclear' hosts the greenfield set. CONSEQUENCES: gatekeeper-vibesdk renames GATEKEEPER-FACTORY to match; repo examples — int_factory (the fork), int_sphere_core, int_gatekeeper_factory, int_gatekeeper_github. DEPLOYER_CONTRACT v0.1 draft references ('vibesdk', 'gatekeeper-vibesdk') to be renamed at canonical commit.
[Update Sep 3, 2026]: [Bootstrap deploy method, Sep 3, 2026, ~1:05pm BST — Mike's question, Perplexity recommendation, PENDING Mike's ruling]: docuclear_control deploys from its own clone of cloudflare-os-starter (new int_-prefixed repo in the docuclear org); contracts moved in post-deploy. Chicken-or-egg (the factory doesn't exist yet) resolved: OUT-OF-BAND ROOT DEPLOY via opencode (docucleardev) — clone → explicit wrangler binding config → deploy from canonical repo@SHA → run record per evidence standard a5e10e10. NOT the Cloudflare deploy wizard: wizard provenance is unverifiable (this morning's findings: 'default starter + minor undeployed edits'; the wizard-created MCP worker is the amend-2 inventory problem), and the control plane is the ROOT of the governed estate — it must be reconstructible from repo+config. RULE ESTABLISHED: out-of-band deploys are permitted exactly at the root (genesis ratification, deployer worker first deploy, docuclear_control) — and every root act must leave complete evidence so the factory can ADOPT the deployment later (keep_bindings path) instead of rebuilding. The wizard retains one legitimate role: throwaway sandboxes/spikes — never governed estate.
[Update Sep 3, 2026]: [RULED, Sep 3, 2026, ~1:24pm BST — Mike]: the Cloudflare deploy wizard is NO MORE — full retirement, stronger than Perplexity's sandbox-only recommendation. No wizard deploys anywhere in the estate, governed or otherwise. Bootstrap method confirmed: out-of-band root deploys via opencode (docucleardev) with full evidence, adopted by the factory later via the keep_bindings path. Consequence queued: the wizard-era docuclear-os instance's decommission becomes the loop's first documented decommission (already decided — now also the last wizard artifact).
Tags: docuclear, decision, architecture, factory-plane, vibesdk, gatekeeper, gadget-workspace, contracts-store, github-canonical, greenfield, project:docuclear, kind:episodic, status:canonical, volatility:state — Source: mcp — 2026-09-03 11:10:44 UTC