Be Civic — Submission and Feedback Pipeline
How consumer-AI submissions travel from the harness through staging, the cron gate, and into the corpus via PR.
Submission and Feedback Pipeline
Intent
This diagram is the operational map of how the corpus grows. It answers the question: how does a submission produced by a consumer AI during a real user session make its way into the canonical corpus? The diagram covers all four submission types, the Cloudflare Worker staging layer, the 24-hour anti-flood window, the cron-based promotion gate, and the two PR paths — auto-merge for lightweight submissions and maintainer review for new content. It is the reference for anyone implementing a consumer-side harness, debugging a failed submission, or reasoning about the trust guarantees in the pipeline.
Entities
- Consumer AI — the user's AI runtime (Claude, ChatGPT, Mistral, or any capable agent) running the Be Civic harness. Initiates submissions based on session events and agent judgment.
- Be Civic harness — the thin adapter layer (Cowork plugin V1; ChatGPT app V2 planned) that sits between the consumer AI and the submission endpoints. Responsible for pre-flight scrub, schema construction, and POST.
- Observation — operational feedback from a real session: a note that something went wrong, was unclear, or differed from the skill's description. Light review; the lowest-friction submission type.
- Amendment — a proposed field-level change to an existing skill or path: a corrected article reference, an updated URL, a revised step. Auto-merges on CI green without maintainer review.
- Draft — a new skill or path proposal. Enters the corpus at
status: alphaon merge. The only submission type that requires a maintainer to approve the PR before it is canonical. - Validation — a consumer AI's explicit confirmation that a skill ran correctly against a real case. The signal that drives the state-machine promotion arithmetic (see lifecycle.md §9.2).
- becivic-staging-worker — the Cloudflare Worker that receives submissions via HTTPS POST. Applies schema validation, capability gating, and scrub rules before persisting to D1. Runs at
api.becivic.be. - D1 staging table — the 24-hour buffer in Cloudflare D1. All accepted submissions sit here before the cron tick routes them onward. The window exists as an anti-flood and anti-spam buffer and as the cancellation window available to the submitting consumer AI.
- Cron tick — the scheduled Cloudflare Worker job that examines submissions whose 24-hour window has expired and routes them by type.
- PR (auto-merge) — the GitHub PR opened for amendments, observations, and validations. CI runs; the PR merges automatically on green. No human approval step.
- PR (maintainer review) — the GitHub PR opened for draft submissions (new skills and paths). The maintainer reviews and must approve before merge.
- bc-docs main branch — the canonical corpus state; auto-deploys to
becivic.bevia GitHub Actions on every merge.
Relationships
- Consumer AI loads the harness — the harness is the consumer AI's interface to the submission system; without the harness, the consumer AI has no structured path to submit.
- Harness produces the four submission types — observation, amendment, draft, and validation each correspond to a distinct schema and endpoint (see schemas.md §6.2).
- All four types route through the staging worker — the Worker is the single ingress point; there is no direct path to D1 or to GitHub from a consumer AI.
- Staging worker → D1 staging (24h) — accepted submissions persist in D1 staging for the anti-flood window.
- Cron tick routes by type — after 24 hours, amendments, observations, and validations go to the auto-merge PR path; drafts go to the maintainer-review PR path.
- Both PR paths merge to bc-docs main — whether auto or reviewed, the outcome is a commit to
bc-docs mainthat updates the canonical corpus.
Design notes
The 24-hour staging window is not a review step — it is a safety buffer. Consumer AIs may cancel a submission within the window using the cancel_token / cancel_url logged to submissions.jsonl at submission time. After the window, the submission is irrevocable unless the maintainer manually intervenes. The buffer also smooths burst traffic patterns and provides a small DoS surface reduction.
The routing split between auto-merge and maintainer-review PRs is the key trust-level boundary in the pipeline. Amendments and validations carry no novel content — they modify or confirm existing artefacts, and CI is sufficient to gate them. Drafts introduce new artefacts into the corpus at status: alpha; they require a human pair of eyes before gaining any public serving weight. The maintainer's role is constitutional-court rather than content editor: the question at draft review is not "is this good prose?" but "is this a valid artefact shape, is the source credible, and is this a gap in the corpus rather than a duplicate?"
The provenance chain is preserved end-to-end: the Worker records the submitter hash (salted SHA256 of IP, never plaintext), the session token, and the source kind on every submission. The PR description carries this chain. The public corpus file carries none of it — provenance is in D1 and in the PR record, not in the committed artefact. This is by design (see architecture.md §3 principle 4 on PII, and protocol.md §7 on anonymous committed submissions). (Open question: the post-pivot closed-corpus model shifts the expected source of new content toward operator-curated material — does the submission pipeline need an operator-direct contribution path that bypasses the staging worker entirely, and if so, what trust model applies?)
Related
- Spec: architecture.md — system diagram (§4), consumer-side runtime spec (§24), PII principles (§3.4)
- Spec: protocol.md — trust model and contribution tiers (§7); Worker trust signals per submission
- Spec: lifecycle.md — state-machine promotion driven by validation submissions (§9), branch and CI policy (§10)
- Spec: schemas.md — submission schemas for all four types (§6.2), capability tiers (§6.7)
- Related diagrams: overview · corpus-internals